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.
|
|
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. |
|
|
|
|
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. |
|
|
|
|
nearestOn3(point,
points,
closed=False,
wrap=False,
**options)
Locate the point on a path or polygon closest to an other point. |
|
|
|
|
nearestOn4(point,
points,
closed=False,
wrap=False,
**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 use to return bounds
(LatLon) or None.
- Returns:
- 2-Tuple (loLatLon, hiLatLon) of LatLon for the lower-left
respectively upper-right corner 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)
>>> boundsOf(b)
>>> 45.0, 1.0, 46.0, 2.0
|
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 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 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 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_.
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.
|
nearestOn4(point,
points,
closed=False,
wrap=False,
**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_.
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.
|
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.
|