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

# Module points

Handle 2-d NumPy, arrays or tuples as LatLons 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: 18.09.23

Classes
| LatLon_ Low-overhead LatLon 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.
| 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 defined by an array, list, sequence, set or tuple of points. |
bounds(points, wrap=True, LatLon=None) Determine the lower-left and upper-right corners of a polygon/-line defined by a list, sequence, set or tuple of points. |
isclockwise(points, adjust=False, wrap=True) Determine the direction of a polygon defined by an array, list, sequence, set or tuple of points. |
isconvex(points, adjust=False, wrap=True) Determine whether a polygon defined by an array, list, sequence, set or tuple of points is convex. |
isenclosedby(latlon, points, wrap=False) Determine whether a point is enclosed by a polygon defined by an array, list, sequence, set or tuple of points. |
perimeterOf(points, closed=False, adjust=True, radius=6371008.77141, wrap=True) Approximate the perimeter of a polygon/-line defined by an array, list, sequence, set or tuple of points. |

Function Details

### areaOf(points, adjust=True, radius=6371008.77141, wrap=True) |
Approximate the area of a polygon defined by an array, list, sequence, set or tuple of points. Parameters: `points` - The points defining the polygon (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.

### bounds(points, wrap=True, LatLon=None) |
Determine the lower-left and upper-right corners of a polygon/-line defined by a list, sequence, set or tuple of points. Parameters: `points` - The points defining the polygon (LatLon[]). `wrap` - Wrap lat- and longitudes (bool). `LatLon` - Optional class to use to return bounds (LatLon). Returns: 2-tuple (loLatLon, hiLatLon) of LatLons for the lower-left respectively upper-right corners 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)
    >>> bounds(b)  # False
    >>> 45.0, 1.0, 46.0, 2.0

### isclockwise(points, adjust=False, wrap=True) |
Determine the direction of a polygon defined by an array, list, sequence, set or tuple of points. Parameters: `points` - The points defining the polygon (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 clockwise, False otherwise. Raises: `TypeError` - Some points are not LatLon. `ValueError` - Insufficient number of points or zero area polygon. Example:
    >>> f = LatLon(45,1), LatLon(45,2), LatLon(46,2), LatLon(46,1)
    >>> isclockwise(f)  # False
    >>> t = LatLon(45,1), LatLon(46,1), LatLon(46,2)
    >>> isclockwise(t)  # True

### isconvex(points, adjust=False, wrap=True) |
Determine whether a polygon defined by an array, list, sequence, set or tuple of points is convex. Parameters: `points` - The points defining the polygon (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 convex, False otherwise. Raises: `CrossError` - Colinear point. `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

### isenclosedby(latlon, points, wrap=False) |
Determine whether a point is enclosed by a polygon defined by an array, list, sequence, set or tuple of points. Parameters: `latlon` - The point (LatLon or 2-tuple (lat, lon)). `points` - The points defining the polygon (LatLon[]). `wrap` - Wrap lat-, wrap and unroll longitudes (bool). Returns: True if latlon is inside the polygon, False otherwise. Raises: `TypeError` - Some points are not LatLon. `ValueError` - Insufficient number of points or invalid latlon. See Also: sphericalNvector.LatLon.isEnclosedBy, sphericalTrigonometry.LatLon.isEnclosedBy and MultiDop GeogContainPt (Shapiro et al. 2009, JTECH and Potvin et al. 2012, JTECH).

### perimeterOf(points, closed=False, adjust=True, radius=6371008.77141, wrap=True) |
Approximate the perimeter of a polygon/-line defined by an array, list, sequence, set or tuple of points. Parameters: `points` - The points defining the polygon/-line (LatLon[]). `closed` - Optionally, close the polygon/-line (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.