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

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 use to return 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 for 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.

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.

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, like function compassAngle. The height is the (interpolated) height at the closest point in meter or zero.
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: Use 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.