Module sphericalNvector
N-vector-based classes geodetic (lat-/longitude) LatLon, geocentric (ECEF) Cartesian and Nvector and functions areaOf, intersection, meanOf, nearestOn3, perimeterOf, sumOf, triangulate and trilaterate, all spherical.
Pure Python implementation of n-vector-based spherical geodetic
(lat-/longitude) methods, transcribed from JavaScript originals by (C)
Chris Veness 2011-2016, published under the same MIT Licence**. See
Vector-based geodesy and Module latlon-nvector-spherical.
Tools for working with points and paths on (a spherical model of) the
earth’s surface using using n-vectors rather than the more common
spherical trigonometry. N-vectors make many calculations much simpler,
and easier to follow, compared with the trigonometric equivalents.
Based on Kenneth Gade’s ‘Non-singular Horizontal Position Representation’, The
Journal of Navigation (2010), vol 63, nr 3, pp 395-417.
Note that the formulations below take x => 0°N,0°E, y =>
0°N,90°E and z => 90°N while Gade uses x => 90°N, y => 0°N,90°E,
z => 0°N,0°E.
Also note that on a spherical earth model, an n-vector is equivalent
to a normalised version of an (ECEF) cartesian coordinate.
|
Cartesian
Extended to convert geocentric, Cartesian points to Nvector and n-vector-based, spherical LatLon.
|
|
LatLon
New n-vector based point on a spherical earth model.
|
|
Nvector
An n-vector is a position representation using a (unit) vector
normal to the earth's surface.
|
|
ispolar(points,
wrap=False)
Check whether a polygon encloses a pole. |
|
|
|
areaOf(points,
radius=6371008.77141)
Calculate the area of a (spherical) polygon (with great circle arcs
joining consecutive points). |
|
|
|
intersection(start1,
end1,
start2,
end2,
height=None,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
**LatLon_kwds)
Locate the intersection of two paths each defined by two points or by
a start point and an initial bearing. |
|
|
|
meanOf(points,
height=None,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
**LatLon_kwds)
Compute the geographic mean of the supplied points. |
|
|
|
|
|
perimeterOf(points,
closed=False,
radius=6371008.77141)
Compute the perimeter of a (spherical) polygon (with great circle
arcs joining consecutive points). |
|
|
|
sumOf(nvectors,
Vector=<class 'pygeodesy.sphericalNvector.Nvector'>,
h=None,
**Vector_kwds)
Return the vectorial sum of two or more n-vectors. |
|
|
|
triangulate(point1,
bearing1,
point2,
bearing2,
height=None,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
**LatLon_kwds)
Locate a point given two known points and initial bearings from those
points. |
|
|
|
trilaterate(point1,
distance1,
point2,
distance2,
point3,
distance3,
radius=6371008.77141,
height=None,
useZ=False,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
**LatLon_kwds)
Locate a point at given distances from three other points. |
|
|
|
__all__ = _ALL_LAZY.sphericalNvector
|
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.
|
areaOf (points,
radius=6371008.77141)
|
|
Calculate the area of a (spherical) polygon (with great circle arcs
joining consecutive points).
- Arguments:
points - The polygon points (LatLon[]).
radius - Mean earth radius (meter ).
- Returns:
- Polygon area (
meter , same units as
radius , squared).
- Raises:
|
intersection (start1,
end1,
start2,
end2,
height=None,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
**LatLon_kwds)
|
|
Locate the intersection of two paths each defined by two points or by
a start point and an initial bearing.
- Arguments:
start1 - Start point of the first path (LatLon).
end1 - End point of the first path (LatLon) or the initial bearing at the first
start point (compass degrees360 ).
start2 - Start point of the second path (LatLon).
end2 - End point of the second path (LatLon) or the initial bearing at the second
start point (compass degrees360 ).
height - Optional height at the intersection point, overriding the mean
height (meter ).
LatLon - Optional class to return the intersection point (LatLon).
LatLon_kwds - Optional, additional LatLon keyword
arguments, ignored if LatLon=None .
- Returns:
- The intersection point (
LatLon ) or 3-tuple
(degrees90 , degrees180 , height) if
LatLon is None or
None if no unique intersection exists.
- Raises:
TypeError - If start* or end* is not LatLon.
ValueError - Intersection is ambiguous or infinite or the paths are parallel,
coincident or null.
Example:
>>> p = LatLon(51.8853, 0.2545)
>>> q = LatLon(49.0034, 2.5735)
>>> i = intersection(p, 108.55, q, 32.44)
|
meanOf (points,
height=None,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
**LatLon_kwds)
|
|
Compute the geographic mean of the supplied points.
- Arguments:
points - Array of points to be averaged (LatLon[]).
height - Optional height, overriding the mean height (meter ).
LatLon - Optional class to return the mean point (LatLon).
LatLon_kwds - Optional, additional LatLon keyword
arguments, ignored if LatLon=None .
- Returns:
- Point at geographic mean and mean height
(
LatLon ).
- Raises:
PointsError - Insufficient number of points .
TypeError - Some points are not LatLon .
|
nearestOn2 (point,
points,
**closed_radius_height)
|
|
DEPRECATED, use method sphericalNvector.nearestOn3.
- Returns:
- ... 2-Tuple
(closest, distance) of the
closest point (LatLon) on the polygon and the
distance between the closest and the
given point ...
|
perimeterOf (points,
closed=False,
radius=6371008.77141)
|
|
Compute the perimeter of a (spherical) polygon (with great circle arcs
joining consecutive points).
- Arguments:
points - The polygon points (LatLon[]).
closed - Optionally, close the polygon (bool ).
radius - Mean earth radius (meter ).
- Returns:
- Polygon perimeter (
meter , same units as
radius ).
- Raises:
|
sumOf (nvectors,
Vector=<class 'pygeodesy.sphericalNvector.Nvector'>,
h=None,
**Vector_kwds)
|
|
Return the vectorial sum of two or more n-vectors.
- Arguments:
nvectors - Vectors to be added (Nvector[]).
Vector - Optional class for the vectorial sum (Nvector).
h - Optional height, overriding the mean height (meter ).
kwds - Optional, additional Vector keyword
arguments.
- Returns:
- Vectorial sum (
Vector ).
- Raises:
|
triangulate (point1,
bearing1,
point2,
bearing2,
height=None,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
**LatLon_kwds)
|
|
Locate a point given two known points and initial bearings from those
points.
- Arguments:
point1 - First reference point (LatLon).
bearing1 - Bearing at the first point (compass degrees360 ).
point2 - Second reference point (LatLon).
bearing2 - Bearing at the second point (compass degrees360 ).
height - Optional height at the triangulated point, overriding the mean
height (meter ).
LatLon - Optional class to return the triangulated point (LatLon).
LatLon_kwds - Optional, additional LatLon keyword
arguments, ignored if LatLon=None .
- Returns:
- Triangulated point (
LatLon ).
- Raises:
TypeError - If point1 or point2 is not
LatLon.
Valuerror - Points coincide.
Example:
>>> p = LatLon("47°18.228'N","002°34.326'W")
>>> q = LatLon("47°18.664'N","002°31.717'W")
>>> t = triangulate(p, 7, q, 295)
|
trilaterate (point1,
distance1,
point2,
distance2,
point3,
distance3,
radius=6371008.77141,
height=None,
useZ=False,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
**LatLon_kwds)
|
|
Locate a point at given distances from three other points.
- Arguments:
point1 - First point (LatLon).
distance1 - Distance to the first point (meter , same units as
radius ).
point2 - Second point (LatLon).
distance2 - Distance to the second point (meter , same units as
radius ).
point3 - Third point (LatLon).
distance3 - Distance to the third point (meter , same units as
radius ).
radius - Mean earth radius (meter ).
height - Optional height at the trilaterated point, overriding the IDW
height (meter , same units as
radius ).
useZ - Include Z component iff non-NaN, non-zero (bool ).
LatLon - Optional class to return the trilaterated
LatLon_kwds - Optional, additional LatLon keyword
arguments, ignored if LatLon=None .
- Returns:
- Trilaterated point (
LatLon ).
- Raises:
IntersectionError - No intersection, trilateration failed.
TypeError - Invalid point1 , point2 or
point3 .
ValueError - Some points coincide or invalid
distance1 , distance2 ,
distance3 or radius .
|