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

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 - 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 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 (sub-)class to return the bounds corners (LatLon) or None.
Returns:
A Bounds2Tuple(latlonSW, latlonNE) as LatLon or a Bounds4Tuple(latS, lonW, latN, lonE) 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 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.

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.

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 (sub-)class to return the closest point (LatLon) or None.
  • options - Other keyword arguments for function equirectangular_.
Returns:
A NearestOn3Tuple(closest, distance, angle) or a NearestOn5Tuple(lat, lon, distance, angle, height) if LatLon is None.
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 - 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.