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

Module points

Handle 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: 18.10.26

Classes
  LatLon_
Low-overhead LatLon 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.
  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.
 
bounds(points, wrap=True, LatLon=None)
Determine the lower-left and upper-right corners of a polygon.
 
isclockwise(points, adjust=False, wrap=True)
Determine the direction of a polygon.
 
isconvex(points, adjust=False, wrap=True)
Determine whether a polygon is convex.
 
isenclosedBy(point, points, wrap=False)
Determine whether a point is enclosed by a polygon.
 
isenclosedby(point, points, wrap=False)
DEPRECATED, use function isenclosedBy.
 
ispolar(points, wrap=False)
Check whether a polygon encloses a pole.
 
nearestOn3(point, points, closed=False, wrap=False, **options)
Locate the point on a polygon closest to an other point.
 
nearestOn4(point, points, closed=False, wrap=False, **options)
Locate the point on a polygon closest to an other point.
 
perimeterOf(points, closed=False, adjust=True, radius=6371008.77141, wrap=True)
Approximate the perimeter of a polygon.
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.

bounds(points, wrap=True, LatLon=None)

 

Determine the lower-left and upper-right corners of a polygon.

Parameters:
  • points - The 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 corners 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)
>>> bounds(b)  # False
>>> 45.0, 1.0, 46.0, 2.0

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

 

Determine the direction of a polygon.

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

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)

 

Locate the point on a 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 polygon points (LatLon[]).
  • closed - Optionally, close the polygon (bool).
  • wrap - Wrap and unroll180 longitudes and longitudinal delta (bool) in function equirectangular_.
  • options - Other keyword arguments for function equirectangular_.
Returns:
3-Tuple (lat, lon, distance) all in degrees. The distance is the equirectangular_ distance between the closest and the reference point in degrees.
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: Function nearestOn4. Use function degrees2m to convert degrees to meter.

nearestOn4(point, points, closed=False, wrap=False, **options)

 

Locate the point on a 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 polygon points (LatLon[]).
  • closed - Optionally, close the polygon (bool).
  • wrap - Wrap and unroll180 longitudes and longitudinal delta (bool) in function equirectangular_.
  • options - Other keyword arguments for function equirectangular_.
Returns:
4-Tuple (lat, lon, distance, angle) all in degrees. 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.
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: Function nearestOn3. Use function degrees2m to convert degrees to meter.

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

 

Approximate the perimeter of a polygon.

Parameters:
  • points - The polygon points (LatLon[]).
  • closed - Optionally, close the 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.