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

Module points

Utilities for point lists, tuples, etc.

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.


Version: 22.09.14

Classes
  LatLon_
Low-overhead LatLon class 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.
Functions
 
areaOf(points, adjust=True, radius=6371008.771415, 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.
 
fractional(points, fi, j=None, wrap=None, LatLon=None, Vector=None, **kwds)
Return the point at a given fractional index.
 
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 a reference point.
 
perimeterOf(points, closed=False, adjust=True, radius=6371008.771415, wrap=True)
Approximate the perimeter of a path or polygon.
 
quadOf(latS, lonW, latN, lonE, 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.771415, 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) or None.
  • wrap - Wrap lat-, wrap and unroll longitudes (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.

See Also: sphericalNvector.areaOf, sphericalTrigonometry.areaOf, ellipsoidalExact.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.

See Also: Function quadOf.

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 (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 - Wrap and unroll longitudes (bool) or None for backward compatible LatLon2Tuple or LatLon with averaged lat- and longitudes. Use True or False to get the fractional point computed 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 - 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.

See Also: Functions pygeodesy.isconvex, pygeodesy.isenclosedBy 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 - 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:
A tuple of 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 a reference point.

The closest point is either on and within the extent of a polygon edge or the nearest of that edge's end points.

Arguments:
  • point - Reference point (LatLon).
  • points - The path or polygon points (LatLon[]).
  • closed - Optionally, close the path or polygon (bool).
  • wrap - Wrap and pygeodesy.unroll180 longitudes and longitudinal delta (bool) in function pygeodesy.equirectangular_.
  • LatLon - Optional class to return the closest point (LatLon) or None.
  • options - Other keyword arguments for function pygeodesy.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 pygeodesy.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 pygeodesy.compassAngle.
Raises:

Note: Distances are approximated using function pygeodesy.equirectangular_, subject to the supplied options. Method LatLon.nearestOn6 measures distances more accurately.

See Also: Function pygeodesy.nearestOn6 for cartesian points. Use function pygeodesy.degrees2m to convert degrees to meter.

perimeterOf (points, closed=False, adjust=True, radius=6371008.771415, 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 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 - Southernmost latitude (degrees90).
  • lonW - Westernmost longitude (degrees180).
  • latN - Northernmost latitude (degrees90).
  • lonE - Easternmost 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.