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.
|
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.
|
|
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.
- 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 .
|
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
LatLon s 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)
>>> 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.
|
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)
>>> isclockwise(reversed(f))
|
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)
>>> 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.
- 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)
>>> 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.
- 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.
|
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 .
|