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 create 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` for each 2+tuple in a list, tuple or sequence of such 2+tuples from the index for the lat- and longitude index in each 2+tuple.

Version: 21.08.28

Classes
| LatLon_ Low-overhead `LatLon` class for Numpy2LatLon and Tuple2LatLon.
| LatLon2psxy Wrapper for `LatLon` points as "on-the-fly" pseudo-xy coordinates.
| NearestOn5Tuple 5-Tuple `(lat, lon, distance, angle, height)` all in `degrees`, except `height`.
| 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.77141, 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, LatLon=None, **LatLon_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 an other point. |
perimeterOf(points, closed=False, adjust=True, radius=6371008.77141, 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.77141, 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 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, LatLon=None, **LatLon_kwds) |
Return the point at a given fractional index. Arguments: `points` - The points (`LatLon`[], Numpy2LatLon[], Tuple2LatLon[] or `other`[]). `fi` - The fractional index (FIx, `float` or `int`). `LatLon` - Optional class to return the intermediate, fractional point (`LatLon`) or `None`. `LatLon_kwds` - Optional, additional `LatLon` keyword arguments, ignored of `LatLon is None`. Returns: A `LatLon` or if `LatLon` is `None`, a LatLon2Tuple`(lat, lon)` for `points[fi]` if fractional index `fi` is `int`, otherwise the intermediate point between `points[int(fi)]` and `points[int(fi) + 1]` for `float` fractional index `fi`. Raises: `IndexError` - Fractional index `fi` invalid or `points` not subscriptable or not closed. `TypeError` - Invalid `LatLon` or `LatLon_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: 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 an other point. If the given point is within the extent of a polygon edge, the closest point is on that edge, otherwise the closest point is the nearest of that edge's end points. Distances are approximated by function equirectangular_, subject to the supplied `options`. Arguments: `point` - The other, reference point (`LatLon`). `points` - The path or polygon points (`LatLon`[]). `closed` - Optionally, close the path or polygon (`bool`). `wrap` - Wrap and unroll180 longitudes and longitudinal delta (`bool`) in function equirectangular_. `LatLon` - Optional class to return the closest point (`LatLon`) or `None`. `options` - Other keyword arguments for function 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 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 compassAngle. Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `PointsError` - Insufficient number of `points` `TypeError` - Some `points` are not `LatLon`. See Also: Function degrees2m to convert `degrees` to `meter`.

### perimeterOf (points, closed=False, adjust=True, radius=6371008.77141, 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 equirectangular_ distance approximation and is ill-suited for regions exceeding several hundred Km or Miles or with near-polar latitudes. See Also: 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.