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

Classes
  LatLon_
Low-overhead LatLon class for Numpy2LatLon and Tuple2LatLon.
  LatLon2psxy
Wrapper for LatLon points as "on-the-fly" pseudo-xy coordinates.
  NearestOn5Tuple
5-Tuple (lat, lon, distance, angle, height) all in degrees, except height.
  Numpy2LatLon
Wrapper for NumPy arrays as "on-the-fly" LatLon points.
  Point3Tuple
3-Tuple (x, y, ll) in meter, meter and LatLon.
  Shape2Tuple
2-Tuple (nrows, ncols), the number of rows and columns, both int.
  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.
 
luneOf(lon1, lon2, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds)
Generate an ellipsoidal or spherical lune-shaped path or polygon.
 
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.
 
quadOf(lat1, lon1, lat2, lon2, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds)
Generate a quadrilateral path or polygon from two points.
Variables
  __all__ = _ALL_LAZY.points
Function Details

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

 

Approximate the area of a polygon.

Arguments:
  • points - The polygon points (LatLon[]).
  • adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
  • radius - Mean earth radius (meter).
  • wrap - Wrap lat-, wrap and unroll longitudes (bool).
Returns:
Approximate area (meter, same units as radius, squared).
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.

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.

Arguments:
  • points - The path or polygon points (LatLon[]).
  • wrap - Wrap lat- and longitudes (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.

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.

Arguments:
  • points - The polygon points (LatLon[]).
  • wrap - Wrap lat-, wrap and unroll longitudes (bool).
  • LatLon - Optional class to return the centroid (LatLon) or None.
Returns:
Centroid location (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.

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 - Wrap lat-, wrap and unroll longitudes (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.

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.

Arguments:
  • 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.
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.

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.

Arguments:
  • 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.
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.

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.

Arguments:
  • 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:
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid point, lat- or longitude.

ispolar (points, wrap=False)

 

Check whether a polygon encloses a pole.

Arguments:
  • points - The polygon points (LatLon[]).
  • wrap - Wrap and unroll longitudes (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:
Yield 4 or 5 LatLon instances outlining the lune shape.

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.

Arguments:
  • 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 class to return the closest point (LatLon) or None.
  • options - Other keyword arguments for function equirectangular_.
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 equirectangular_ distance between the closest and reference point in degrees. The angle from the reference point to the closest is in compass degrees360, like function compassAngle.
Raises:

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.

Arguments:
  • 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 - Mean earth radius (meter).
  • wrap - Wrap lat-, wrap and unroll longitudes (bool).
Returns:
Approximate perimeter (meter, same units as radius).
Raises:
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid radius.

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.

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

 

Generate a quadrilateral path or polygon from two points.

Arguments:
  • lat1 - Lower latitude (degrees90).
  • lon1 - Left longitude (degrees180).
  • lat2 - Upper latitude (degrees90).
  • lon2 - Right longitude (degrees180).
  • closed - Optionally, close the path (bool).
  • LatLon - Class to use (LatLon_).
  • LatLon_kwds - Optional, additional LatLon keyword arguments.
Returns:
Yield 4 or 5 LatLon instances outlining the quadrilateral.