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

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. |
nearestOn3(point, points, closed=False, wrap=False, **options) DEPRECATED, use function nearestOn5. |
nearestOn4(point, points, closed=False, wrap=False, **options) DEPRECATED, use function nearestOn5. |
nearestOn5(point, points, closed=False, wrap=False, **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` - Optional, 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 is an area approximation with limited accuracy, 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 (sub-)class to return the bounds (`LatLon`) or `None`. Returns: 2-Tuple (`loLatLon, hiLatLon`) of LatLon for the lower-left respectively upper-right corner or 4-tuple (`loLat, loLon, hiLat, hiLon`) of bounds (`degrees`) if LatLon is `None`. 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 (sub-)class to return the centroid (`LatLon`) or `None`. Returns: Centroid location (LatLon) or as 2-tuple (`lat, lon`) in `degrees` 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 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 a pole is enclosed by the polygon, `False` otherwise. Raises: `ValueError` - Insufficient number of points. `TypeError` - Some points are not `LatLon` or don't have `bearingTo2`, `initialBearingTo` and `finalBearingTo` methods.

### nearestOn3(point, points, closed=False, wrap=False, **options) |
DEPRECATED, use function nearestOn5. Returns: ... 3-Tuple (lat, lon, distance) ...

### nearestOn4(point, points, closed=False, wrap=False, **options) |
DEPRECATED, use function nearestOn5. Returns: ... 4-Tuple (lat, lon, distance, angle) ...

### nearestOn5(point, points, closed=False, wrap=False, **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_. `options` - Other keyword arguments for function equirectangular_. Returns: 5-Tuple (`lat, lon, distance, angle, height`) all in `degrees` except height. The distance is the equirectangular_ distance between the closest and the reference point in `degrees`. The angle from the reference point to the closest point is in compass `degrees360`, see function compassAngle. The height is the (interpolated) height at the closest point in `meter` or `0`. Raises: `LimitError` - Lat- and/or longitudinal delta exceeds 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` - Optional, 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.