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.
|
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. |
|
|
|
__all__ = _ALL_LAZY.points
|
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 .
|
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)
>>> 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)
>>> isclockwise(reversed(f))
|
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)
>>> f = LatLon(45,1), LatLon(46,2), LatLon(45,2), LatLon(46,1)
>>> isconvex(f)
|
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)
>>> f = LatLon(45,1), LatLon(46,2), LatLon(45,2), LatLon(46,1)
>>> isconvex_(f)
|
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 .
|