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

# Module points

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: 20.03.23

Classes
| LatLon_ Low-overhead `LatLon` class for Numpy2LatLon and Tuple2LatLon.
| LatLon2psxy Wrapper for `LatLon` points as "on-the-fly" pseudo-xy coordinates.
| Numpy2LatLon Wrapper for `NumPy` arrays as "on-the-fly" `LatLon` points.
| 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. |
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. |
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. |

Variables
| __all__ = `_ALL_LAZY.points`

Function Details

### areaOf(points, adjust=True, radius=6371008.77141, wrap=True) |
Approximate the area of a polygon. Parameters: `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`). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: Approximate area (`meter`, same units as `radius`, squared). Raises: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. 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. Parameters: `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: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. 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. Parameters: `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 location (`LatLon`) or a LatLon2Tuple`(lat, lon)` if `LatLon` is `None`. Raises: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points` or `points` enclose a pole or zero area. See Also: Centroid and Calculating The Area And Centroid Of A Polygon.

### isclockwise(points, adjust=False, wrap=True) |
Determine the direction of a path or polygon. Parameters: `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: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points` or 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. Parameters: `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. `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. 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. Parameters: `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. `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. 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. Parameters: `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: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points` or invalid `point`. 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. Parameters: `points` - The polygon points (`LatLon`[]). `wrap` - Wrap and unroll longitudes (`bool`). Returns: `True` if the polygon encloses a pole, `False` otherwise. Raises: `ValueError` - Insufficient number of `points`. `TypeError` - Some `points` are not `LatLon` or don't have `bearingTo2`, `initialBearingTo` and `finalBearingTo` methods.

### 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`. Parameters: `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_. `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. 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. Parameters: `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: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. 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.