Module sphericalNvector
Spherical, N-vector-based geodesy.
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, transcoded from JavaScript originals by (C)
Chris Veness 2011-2024, published under the same MIT Licence**. See
Vector-based geodesy and Module latlon-nvector-spherical.
Tools for working with points and lines 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.771415,
wrap=False)
Calculate the area of a (spherical) polygon or composite (with great
circle arcs joining consecutive points). |
|
|
|
|
intersecant2(center,
circle,
point,
other,
**radius_exact_height_wrap)
Compute the intersections of a circle and a (great circle) line given
as two points or as a point and bearing. |
|
|
|
|
intersection(start1,
end1,
start2,
end2,
height=None,
wrap=False,
**LatLon_and_kwds)
Locate an intersection point of two (great circle) lines each defined
by two points or by a point and an (initial) bearing. |
|
|
|
|
intersection2(start1,
end1,
start2,
end2,
height=None,
wrap=False,
**LatLon_and_kwds)
Locate both intersections of two (great circle) lines each defined by
two points or by a point and an (initial) bearing. |
|
|
|
|
meanOf(points,
height=None,
wrap=False,
**LatLon_and_kwds)
Compute the geographic mean of the supplied points. |
|
|
|
|
|
|
|
nearestOn3(point,
points,
closed=False,
radius=6371008.771415,
height=None,
wrap=False)
Locate the point on a polygon (with great circle arcs joining
consecutive points) closest to an other point. |
|
|
|
|
perimeterOf(points,
closed=False,
radius=6371008.771415,
wrap=False)
Compute the perimeter of a (spherical) polygon or composite (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,
wrap=False,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
**LatLon_kwds)
Locate a point given two known, reference points and the (initial)
bearing from those points. |
|
|
|
|
trilaterate(point1,
distance1,
point2,
distance2,
point3,
distance3,
radius=6371008.771415,
height=None,
useZ=False,
wrap=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 - If True, wrap or normalize and unroll the
points (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.771415,
wrap=False)
|
|
Calculate the area of a (spherical) polygon or composite (with great
circle arcs joining consecutive points).
- Arguments:
points - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
radius - Mean earth radius (meter) or None.
wrap - If True, wrap or normalize and unroll the
points (bool).
- Returns:
- Polygon area (
meter squared, same units as
radius, or radians if
radius is None).
- Raises:
|
intersecant2 (center,
circle,
point,
other,
**radius_exact_height_wrap)
|
|
Compute the intersections of a circle and a (great circle) line given
as two points or as a point and bearing.
- Arguments:
center - Center of the circle (LatLon).
circle - Radius of the circle (meter, same units as the earth
radius) or a point on the circle (LatLon).
point - A point on the (great circle) line (LatLon).
other - An other point on the (great circle) line (LatLon) or the bearing at the
point (compass degrees360).
radius_exact_height_wrap - Optional keyword arguments, see method intersecant2 for further details.
- Returns:
- 2-Tuple of the intersection points (representing a chord), each
an instance of the
point class. Both points
are the same instance if the (great circle) line is tangent to
the circle.
- Raises:
IntersectionError - The circle and line do not intersect.
TypeError - If center, point,
circle or other not LatLon.
UnitError - Invalid circle, other,
radius, exact,
height or napieradius.
|
intersection (start1,
end1,
start2,
end2,
height=None,
wrap=False,
**LatLon_and_kwds)
|
|
Locate an intersection point of two (great circle) lines each defined
by two points or by a point and an (initial) bearing.
- Returns:
- The intersection point (LatLon) or if
LatLon=None, a
cartesian Ecef9Tuple(x, y, z, lat, lon, height, C,
M, datum) with C and M if
available.
|
intersection2 (start1,
end1,
start2,
end2,
height=None,
wrap=False,
**LatLon_and_kwds)
|
|
Locate both intersections of two (great circle) lines each defined by
two points or by a point and an (initial) bearing.
- Arguments:
start1 - Start point of the first line (LatLon).
end1 - End point of the first line (LatLon) or the bearing at
start1 (compass degrees360).
start2 - Start point of the second line (LatLon).
end2 - End point of the second line (LatLon) or the bearing at
start2 (compass degrees360).
height - Optional height at the intersection and antipodal point,
overriding the mean height (meter).
wrap - If True, wrap or normalize and unroll
start2 and both end*
points (bool).
LatLon_and_kwds - Optional class LatLon=LatLon to return the intersection points and
optionally, additional LatLon keyword
arguments, ignored if LatLon is None.
- Returns:
- 2-Tuple
(intersection, antipode), each a
(LatLon) or if
LatLon=None, a cartesian Ecef9Tuple(x, y, z, lat, lon, height, C,
M, datum) with C and M if
available.
- Raises:
TypeError - If start* or end* is not LatLon.
ValueError - Intersection is ambiguous or infinite or the lines are parallel,
coincident or null.
|
meanOf (points,
height=None,
wrap=False,
**LatLon_and_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).
wrap - If True, wrap or normalize
points (bool).
LatLon_and_kwds - Optional class LatLon=LatLon to return the mean point and optionally,
additional LatLon keyword arguments, ignored
if LatLon is None.
- Returns:
- Point at geographic mean and mean height
(
LatLon).
- Raises:
PointsError - Insufficient number of points or 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 ...
- Decorators:
|
nearestOn3 (point,
points,
closed=False,
radius=6371008.771415,
height=None,
wrap=False)
|
|
Locate the point on a polygon (with great circle arcs joining
consecutive points) closest to an other point.
If the given point is between the end points of a great circle arc,
the closest point is on that arc. Otherwise, the closest point is the
nearest of the arc's end points.
- Arguments:
point - The other, reference point (LatLon).
points - The polygon points (LatLon[]).
closed - Optionally, close the polygon (bool).
radius - Mean earth radius (meter) or None.
height - Optional height, overriding the mean height for a point within
the (great circle) arc (meter).
wrap - If True, wrap or normalize and unroll the
points (bool).
- Returns:
- A NearestOn3Tuple
(closest, distance,
angle) of the closest point (LatLon) on the polygon, the
distance and the angle between the
closest and the given point.
The distance is in meter, same units as
radius or in radians if
radius is None, the angle is in
compass degrees360.
- Raises:
PointsError - Insufficient number of points.
TypeError - Some points or point not
LatLon.
|
perimeterOf (points,
closed=False,
radius=6371008.771415,
wrap=False)
|
|
Compute the perimeter of a (spherical) polygon or composite (with
great circle arcs joining consecutive points).
- Arguments:
points - The polygon points (LatLon[]).
closed - Optionally, close the polygon (bool).
radius - Mean earth radius (meter) or None.
wrap - If True, wrap or normalize and unroll the
points (bool).
- Returns:
- Polygon perimeter (
meter, same units as
radius or radians if
radius is None).
- Raises:
PointsError - Insufficient number of points.
TypeError - Some points are not LatLon.
ValueError - Invalid radius or
closed=False with points a
composite.
|
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).
Vector_kwds - Optional, additional Vector keyword
arguments.
- Returns:
- Vectorial sum (
Vector).
- Raises:
|
triangulate (point1,
bearing1,
point2,
bearing2,
height=None,
wrap=False,
LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>,
**LatLon_kwds)
|
|
Locate a point given two known, reference points and the (initial)
bearing 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).
wrap - If True, wrap or normalize and unroll
point2 (bool).
LatLon - Optional class to return the triangulated point (LatLon).
LatLon_kwds - Optional, additional LatLon keyword
arguments, ignored if LatLon is None.
- Returns:
- Triangulated point (
LatLon).
- Raises:
TypeError - If point1 or point2 is not
LatLon.
Valuerror - Points coincide.
|
trilaterate (point1,
distance1,
point2,
distance2,
point3,
distance3,
radius=6371008.771415,
height=None,
useZ=False,
wrap=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).
wrap - If True, wrap or normalize and unroll
point2 and point3
(bool).
LatLon - Optional class to return the trilaterated point (LatLon).
LatLon_kwds - Optional, additional LatLon keyword
arguments, ignored if LatLon is None.
- Returns:
- Trilaterated point (
LatLon).
- Raises:
IntersectionError - No intersection, trilateration failed.
TypeError - Invalid point1, point2 or
point3.
ValueError - Coincident points or invalid
distance1, distance2,
distance3 or radius.
|