Module sphericalNvector
N-vector-based classes geodetic (lat-/longitude) LatLon, geocentric (ECEF) Cartesian and Nvector and functions areaOf, intersection, meanOf, nearestOn2, 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'>)
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'>)
Compute the geographic mean of the supplied points. |
|
|
|
nearestOn2(point,
points,
closed=False,
radius=6371008.77141,
height=None)
Locate the point on a polygon (with great circle arcs joining
consecutive points) closest to an other point. |
|
|
|
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,
**kwds)
Return the vectorial sum of two or more n-vectors. |
|
|
|
triangulate(point1,
bearing1,
point2,
bearing2,
height=None,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>)
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,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
useZ=False)
Locate a point at given distances from three other points. |
|
|
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.
|
areaOf(points,
radius=6371008.77141)
|
|
Calculate the area of a (spherical) polygon (with great circle arcs
joining consecutive points).
- Parameters:
points - The polygon points (LatLon[]).
radius - Optional, mean earth radius (meter ).
- Returns:
- Polygon area (
meter , same units as
radius , squared).
- Raises:
TypeError - Some points are not LatLon.
ValueError - Insufficient number of points .
|
intersection(start1,
end1,
start2,
end2,
height=None,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>)
|
|
Locate the intersection of two paths each defined by two points or by
a start point and an initial bearing.
- Parameters:
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 (sub-)class to return the intersection point (LatLon).
- 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'>)
|
|
Compute the geographic mean of the supplied points.
- Parameters:
points - Array of points to be averaged (LatLon[]).
height - Optional height, overriding the mean height (meter ).
LatLon - Optional (sub-)class to return the mean point (LatLon).
- Returns:
- Point at geographic mean and mean height
(
LatLon ).
- Raises:
ValueError - Insufficient number of points .
|
nearestOn2(point,
points,
closed=False,
radius=6371008.77141,
height=None)
|
|
Locate the point on a polygon (with great circle arcs joining
consecutive points) closest to an other point.
If the given point is within the extent of any great circle arc, the
closest point is on that arc. Otherwise, the closest is the nearest of
the arc's end points.
- Parameters:
point - The other, reference point (LatLon).
points - The polygon points (LatLon[]).
closed - Optionally, close the polygon (bool ).
radius - Optional, mean earth radius (meter ).
height - Optional height, overriding the mean height for a point within
the arc (meter ).
- Returns:
- 2-Tuple
(closest, distance) of the closest point (LatLon) on the polygon and the
distance from the closest to the other
point in meter , same units as
radius .
- Raises:
TypeError - Some points or point not
LatLon .
ValueError - No points .
|
perimeterOf(points,
closed=False,
radius=6371008.77141)
|
|
Compute the perimeter of a (spherical) polygon (with great circle arcs
joining consecutive points).
- Parameters:
points - The polygon points (LatLon[]).
closed - Optionally, close the polygon (bool ).
radius - Optional, mean earth radius (meter ).
- Returns:
- Polygon perimeter (
meter , same units as
radius ).
- Raises:
TypeError - Some points are not LatLon.
ValueError - Insufficient number of points .
|
sumOf(nvectors,
Vector=<class 'pygeodesy.sphericalNvector.Nvector'>,
h=None,
**kwds)
|
|
Return the vectorial sum of two or more n-vectors.
- Parameters:
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'>)
|
|
Locate a point given two known points and initial bearings from those
points.
- Parameters:
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 (sub-)class to return the triangulated point (LatLon).
- 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,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
useZ=False)
|
|
Locate a point at given distances from three other points. See also Trilateration.
- Parameters:
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 - Optional, mean earth radius (meter ).
height - Optional height at the trilaterated point, overriding the IDW
height (meter , same units as
radius ).
LatLon - Optional (sub-)class to return the trilaterated point (LatLon).
useZ - Include Z component iff non-NaN, non-zero (bool ).
- Returns:
- Trilaterated point (
LatLon ).
- Raises:
TypeError - If point1 , point2 or
point3 is not LatLon.
ValueError - Invalid radius , some
distances exceed trilateration or some
points coincide.
|