pygeodesy.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 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.

areaOf (points, adjust=True, radius=6371008.771415, wrap=True)

Approximate the area of a polygon or composite.

Arguments:

points - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
radius - Mean earth radius (meter) or None.
wrap - If True, wrap or normalize and unroll the points (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.

boundsOf (points, wrap=False, LatLon=None)

Determine the bottom-left SW and top-right NE corners of a path or polygon.

Arguments:

points - The path or polygon points (LatLon[]).
wrap - If True, wrap or normalize and unroll the points (bool).
LatLon - Optional class to return the bounds corners (LatLon) or None.

Returns:

A Bounds2Tuple(latlonSW, latlonNE) as LatLons 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.

centroidOf (points, wrap=False, LatLon=None)

Determine the centroid of a polygon.

Arguments:

points - The polygon points (LatLon[]).
wrap - If True, wrap or normalize and unroll the points (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 - If True, wrap or normalize and unroll the {points} (bool) or None for a backward compatible LatLon2Tuple or LatLon with averaged lat- and longitudes. Use True or False to get the fractional point computed by 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 - If True, wrap or normalize and unroll the points (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.

isconvex (points, adjust=False, wrap=False)

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 - If True, wrap or normalize and unroll the points (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.

isconvex_ (points, adjust=False, wrap=False)

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 - If True, wrap or normalize and unroll the points (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.

isenclosedBy (point, points, wrap=False)

Determine whether a point is enclosed by a polygon or composite.

Arguments:

point - The point (LatLon or 2-tuple (lat, lon)).
points - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
wrap - If True, wrap or normalize and unroll the points (bool).

Returns:

True if the point is inside the polygon or composite, 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 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 - If True, wrap or normalize and unroll the points (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, adjust=True, limit=9, **LatLon_and_kwds)

Locate the point on a path or polygon closest to a reference point.

The closest point on each polygon edge is either the nearest of that edge's end points or a point in between.

Arguments:

point - The reference point (LatLon).
points - The path or polygon points (LatLon[]).
closed - Optionally, close the path or polygon (bool).
wrap - If True, wrap or normalize and unroll the points (bool).
adjust - See function pygeodesy.equirectangular_ (bool).
limit - See function pygeodesy.equirectangular_ (degrees), default 9 degrees is about 1,000 Kmeter (for mean spherical earth radius R_KM).
LatLon_and_kwds - Optional, LatLon=None class to use for the closest point and additional LatLon keyword arguments, ignored if LatLon=None or not given.

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 point to the closest is in compass degrees, 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 by function pygeodesy.equirectangular_. For more accuracy use one of the LatLon.nearestOn6 methods.

See Also: Function pygeodesy.degrees2m.

perimeterOf (points, closed=False, adjust=True, radius=6371008.771415, wrap=True)

Approximate the perimeter of a path, polygon. or composite.

Arguments:

points - The path or polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
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 - If True, wrap or normalize and unroll the points (bool).

Returns:

Approximate perimeter (meter, same units as radius).

Raises:

PointsError - Insufficient number of points
TypeError - Some points are not LatLon.
ValueError - Invalid radius or closed=False with points a composite.

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 - Souther-nmost latitude (degrees90).
lonW - Western-most longitude (degrees180).
latN - Norther-nmost latitude (degrees90).
lonE - Eastern-most 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.

Classes
	LatLon_ Low-overhead `LatLon` class, mainly 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.

Variables
	__all__ = `_ALL_LAZY.points`

Module points

areaOf (points, adjust=True, radius=6371008.771415, wrap=True)

boundsOf (points, wrap=False, LatLon=None)

centroidOf (points, wrap=False, LatLon=None)

fractional (points, fi, j=None, wrap=None, LatLon=None, Vector=None, **kwds)

isclockwise (points, adjust=False, wrap=True)

isconvex (points, adjust=False, wrap=False)

isconvex_ (points, adjust=False, wrap=False)

isenclosedBy (point, points, wrap=False)

ispolar (points, wrap=False)

luneOf (lon1, lon2, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds)

nearestOn5 (point, points, closed=False, wrap=False, adjust=True, limit=9, **LatLon_and_kwds)

perimeterOf (points, closed=False, adjust=True, radius=6371008.771415, wrap=True)

quadOf (latS, lonW, latN, lonE, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds)