Package pygeodesy :: Module points |
[frames] | no frames]

# Module points

Utilities for point lists, tuples, etc.

Functions to handle collections and sequences of `LatLon` points specified as 2-d NumPy, `arrays` or tuples as `LatLon` or as `pseudo-x/-y` pairs.

`NumPy` arrays are assumed to contain rows of points with a lat-, a longitude -and possibly other- values in different columns. While iterating over the array rows, create an instance of a given `LatLon` class "on-the-fly" for each row with the row's lat- and longitude.

The original `NumPy` array is read-accessed only and never duplicated, except to return a subset of the original array.

For example, to process a `NumPy` array, wrap the array by instantiating class Numpy2LatLon and specifying the column index for the lat- and longitude in each row. Then, pass the Numpy2LatLon instance to any pygeodesy function or method accepting a points argument.

Similarly, class Tuple2LatLon is used to instantiate a `LatLon` from each 2+tuple in a sequence of such 2+tuples using the `ilat` lat- and `ilon` longitude index in each 2+tuple.

Version: 23.01.21

Classes
| LatLon_ Low-overhead `LatLon` class for Numpy2LatLon and Tuple2LatLon.
| _Basequence (INTERNAL) Base class.
| _Array2LatLon (INTERNAL) Base class for Numpy2LatLon or Tuple2LatLon.
| LatLon2psxy Wrapper for `LatLon` points as "on-the-fly" pseudo-xy coordinates.
| Numpy2LatLon Wrapper for `NumPy` arrays as "on-the-fly" `LatLon` points.
| Shape2Tuple 2-Tuple `(nrows, ncols)`, the number of rows and columns, both `int`.
| Tuple2LatLon Wrapper for tuple sequences as "on-the-fly" `LatLon` points.

Functions
areaOf(points, adjust=True, radius=6371008.771415, wrap=True) Approximate the area of a polygon. |
boundsOf(points, wrap=True, LatLon=None) Determine the lower-left SW and upper-right NE corners of a path or polygon. |
centroidOf(points, wrap=True, LatLon=None) Determine the centroid of a polygon. |
fractional(points, fi, j=None, wrap=None, LatLon=None, Vector=None, **kwds) Return the point at a given fractional index. |
isclockwise(points, adjust=False, wrap=True) Determine the direction of a path or polygon. |
isconvex(points, adjust=False, wrap=True) Determine whether a polygon is convex. |
isconvex_(points, adjust=False, wrap=True) Determine whether a polygon is convex and clockwise. |
isenclosedBy(point, points, wrap=False) Determine whether a point is enclosed by a polygon. |
ispolar(points, wrap=False) Check whether a polygon encloses a pole. |
luneOf(lon1, lon2, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds) Generate an ellipsoidal or spherical lune-shaped path or polygon. |
nearestOn5(point, points, closed=False, wrap=False, LatLon=None, **options) Locate the point on a path or polygon closest to a reference point. |
perimeterOf(points, closed=False, adjust=True, radius=6371008.771415, wrap=True) Approximate the perimeter of a path or polygon. |
quadOf(latS, lonW, latN, lonE, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds) Generate a quadrilateral path or polygon from two points. |

Variables
| __all__ = `_ALL_LAZY.points`

Function Details

### areaOf (points, adjust=True, radius=6371008.771415, wrap=True) |
Approximate the area of a polygon. Arguments: `points` - The polygon points (`LatLon`[]). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `radius` - Mean earth radius (`meter`) or `None`. `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: Approximate area (square `meter`, same units as `radius` or `radians` squared if `radius` is `None`). Raises: `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon`. `ValueError` - Invalid `radius`. Note: This area approximation has limited accuracy and is ill-suited for regions exceeding several hundred Km or Miles or with near-polar latitudes. See Also: sphericalNvector.areaOf, sphericalTrigonometry.areaOf, ellipsoidalExact.areaOf and ellipsoidalKarney.areaOf.

### boundsOf (points, wrap=True, LatLon=None) |
Determine the lower-left SW and upper-right NE corners of a path or polygon. Arguments: `points` - The path or polygon points (`LatLon`[]). `wrap` - Wrap lat- and longitudes (`bool`). `LatLon` - Optional class to return the `bounds` corners (`LatLon`) or `None`. Returns: A Bounds2Tuple`(latlonSW, latlonNE)` as `LatLon`s if `LatLon` is `None` a Bounds4Tuple`(latS, lonW, latN, lonE)`. Raises: `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon`. See Also: Function quadOf. Example:
    >>> b = LatLon(45,1), LatLon(45,2), LatLon(46,2), LatLon(46,1)
    >>> boundsOf(b)  # False
    >>> 45.0, 1.0, 46.0, 2.0

### centroidOf (points, wrap=True, LatLon=None) |
Determine the centroid of a polygon. Arguments: `points` - The polygon points (`LatLon`[]). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). `LatLon` - Optional class to return the centroid (`LatLon`) or `None`. Returns: Centroid (`LatLon`) or a LatLon2Tuple`(lat, lon)` if `LatLon is None`. Raises: `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon`. `ValueError` - The `points` enclose a pole or near-zero area. See Also: Centroid and Paul Bourke's Calculating The Area And Centroid Of A Polygon, 1988.

### fractional (points, fi, j=None, wrap=None, LatLon=None, Vector=None, **kwds) |
  Return the point at a given fractional index. Arguments: `points` - The points (`LatLon`[], Numpy2LatLon[], Tuple2LatLon[], `Cartesian`[], `Vector3d`[], Vector3Tuple[]). `fi` - The fractional index (FIx, `float` or `int`). `j` - Optionally, index of the other point (`int`). `wrap` - Wrap and unroll longitudes (`bool`) or `None` for backward compatible LatLon2Tuple or `LatLon` with averaged lat- and longitudes. Use `True` or `False` to get the fractional point computed method `points[fi].intermediateTo`. `LatLon` - Optional class to return the intermediate, fractional point (`LatLon`) or `None`. `Vector` - Optional class to return the intermediate, fractional point (`Cartesian`, `Vector3d`) or `None`. `kwds` - Optional, additional `LatLon` or `Vector` keyword arguments, ignored if both `LatLon` and `Vector` are `None`. Returns: A LatLon2Tuple`(lat, lon)` if `wrap`, `LatLon` and `Vector` all are `None`, the defaults. An instance of `LatLon` if not `None` or an instance of `Vector` if not `None`. Otherwise with `wrap` either `True` or `False` and `LatLon` and `Vector` both `None`, an instance of `points`' (sub-)class `intermediateTo` fractional. Summarized as follows:
      >>>  wrap  | LatLon | Vector | returned type/value
      #   -------+--------+--------+--------------+------
      #          |        |        | LatLon2Tuple | favg
      #    None  |  None  |  None  |   or**       |
      #          |        |        | Vector3Tuple | favg
      #    None  | LatLon |  None  | LatLon       | favg
      #    None  |  None  | Vector | Vector       | favg
      #   -------+--------+--------+--------------+------
      #    True  |  None  |  None  | points'      | .iTo
      #    True  | LatLon |  None  | LatLon       | .iTo
      #    True  |  None  | Vector | Vector       | .iTo
      #   -------+--------+--------+--------------+------
      #    False |  None  |  None  | points'      | .iTo
      #    False | LatLon |  None  | LatLon       | .iTo
      #    False |  None  | Vector | Vector       | .iTo
      # _____
      # favg) averaged lat, lon or x, y, z values
      # .iTo) value from points[fi].intermediateTo
      # **) depends on base class of points[fi]
Raises: `IndexError` - Fractional index `fi` invalid or `points` not subscriptable or not closed. `TypeError` - Invalid `LatLon`, `Vector` or `kwds` argument. See Also: Class FIx and method FIx.fractional.

### isclockwise (points, adjust=False, wrap=True) |
Determine the direction of a path or polygon. Arguments: `points` - The path or polygon points (`LatLon`[]). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: `True` if `points` are clockwise, `False` otherwise. Raises: `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon`. `ValueError` - The `points` enclose a pole or zero area. Example:
    >>> f = LatLon(45,1), LatLon(45,2), LatLon(46,2), LatLon(46,1)
    >>> isclockwise(f)  # False
    >>> isclockwise(reversed(f))  # True

### isconvex (points, adjust=False, wrap=True) |
Determine whether a polygon is convex. Arguments: `points` - The polygon points (`LatLon`[]). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: `True` if `points` are convex, `False` otherwise. Raises: `CrossError` - Some `points` are colinear. `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon`. Example:
    >>> t = LatLon(45,1), LatLon(46,1), LatLon(46,2)
    >>> isconvex(t)  # True
    >>> f = LatLon(45,1), LatLon(46,2), LatLon(45,2), LatLon(46,1)
    >>> isconvex(f)  # False

### isconvex_ (points, adjust=False, wrap=True) |
Determine whether a polygon is convex and clockwise. Arguments: `points` - The polygon points (`LatLon`[]). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: `+1` if `points` are convex clockwise, `-1` for convex counter-clockwise `points`, `0` otherwise. Raises: `CrossError` - Some `points` are colinear. `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon`. Example:
    >>> t = LatLon(45,1), LatLon(46,1), LatLon(46,2)
    >>> isconvex_(t)  # +1
    >>> f = LatLon(45,1), LatLon(46,2), LatLon(45,2), LatLon(46,1)
    >>> isconvex_(f)  # 0

### isenclosedBy (point, points, wrap=False) |
Determine whether a point is enclosed by a polygon. Arguments: `point` - The point (`LatLon` or 2-tuple `(lat, lon)`). `points` - The polygon points (`LatLon`[]). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: `True` if `point` is inside the polygon, `False` otherwise. Raises: `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon`. `ValueError` - Invalid `point`, lat- or longitude. See Also: Functions pygeodesy.isconvex, pygeodesy.isenclosedBy and pygeodesy.ispolar especially if the `points` may enclose a pole or wrap around the earth longitudinally, methods sphericalNvector.LatLon.isenclosedBy, sphericalTrigonometry.LatLon.isenclosedBy and MultiDop GeogContainPt (Shapiro et al. 2009, JTECH and Potvin et al. 2012, JTECH).

### ispolar (points, wrap=False) |
Check whether a polygon encloses a pole. Arguments: `points` - The polygon points (`LatLon`[]). `wrap` - Wrap and unroll longitudes (`bool`). Returns: `True` if the polygon encloses a pole, `False` otherwise. Raises: `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon` or don't have `bearingTo2`, `initialBearingTo` and `finalBearingTo` methods.

### luneOf (lon1, lon2, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds) |
Generate an ellipsoidal or spherical lune-shaped path or polygon. Arguments: `lon1` - Left longitude (`degrees90`). `lon2` - Right longitude (`degrees90`). `closed` - Optionally, close the path (`bool`). `LatLon` - Class to use (LatLon_). `LatLon_kwds` - Optional, additional `LatLon` keyword arguments. Returns: A tuple of 4 or 5 `LatLon` instances outlining the lune shape. See Also: Latitude-longitude quadrangle.

### nearestOn5 (point, points, closed=False, wrap=False, LatLon=None, **options) |
Locate the point on a path or polygon closest to a reference point. The closest point is either on and within the extent of a polygon edge or the nearest of that edge's end points. Arguments: `point` - Reference point (`LatLon`). `points` - The path or polygon points (`LatLon`[]). `closed` - Optionally, close the path or polygon (`bool`). `wrap` - Wrap and pygeodesy.unroll180 longitudes and longitudinal delta (`bool`) in function pygeodesy.equirectangular_. `LatLon` - Optional class to return the closest point (`LatLon`) or `None`. `options` - Other keyword arguments for function pygeodesy.equirectangular_. Returns: A NearestOn3Tuple`(closest, distance, angle)` with the {closest} point (`LatLon`) or if `LatLon is None`, a NearestOn5Tuple`(lat, lon, distance, angle, height)`. The `distance` is the pygeodesy.equirectangular distance between the `closest` and reference `point` in `degrees`. The `angle` from the reference `point` to the `closest` is in compass `degrees360`, like function pygeodesy.compassAngle. Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function pygeodesy.equirectangular_. `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon`. Note: Distances are approximated using function pygeodesy.equirectangular_, subject to the supplied `options`. Method `LatLon.nearestOn6` measures distances more accurately. See Also: Function pygeodesy.nearestOn6 for cartesian points. Use function pygeodesy.degrees2m to convert `degrees` to `meter`.

### perimeterOf (points, closed=False, adjust=True, radius=6371008.771415, wrap=True) |
Approximate the perimeter of a path or polygon. Arguments: `points` - The path or polygon points (`LatLon`[]). `closed` - Optionally, close the path or polygon (`bool`). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `radius` - Mean earth radius (`meter`). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: Approximate perimeter (`meter`, same units as `radius`). Raises: `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon`. `ValueError` - Invalid `radius`. Note: This perimeter is based on the pygeodesy.equirectangular_ distance approximation and is ill-suited for regions exceeding several hundred Km or Miles or with near-polar latitudes. See Also: Functions sphericalTrigonometry.perimeterOf and ellipsoidalKarney.perimeterOf.

### quadOf (latS, lonW, latN, lonE, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds) |
Generate a quadrilateral path or polygon from two points. Arguments: `latS` - Southernmost latitude (`degrees90`). `lonW` - Westernmost longitude (`degrees180`). `latN` - Northernmost latitude (`degrees90`). `lonE` - Easternmost longitude (`degrees180`). `closed` - Optionally, close the path (`bool`). `LatLon` - Class to use (LatLon_). `LatLon_kwds` - Optional, additional `LatLon` keyword arguments. Returns: Return a tuple of 4 or 5 `LatLon` instances outlining the quadrilateral. See Also: Function boundsOf.