Package pygeodesy :: Module sphericalNvector
[frames] | no frames]

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.


Version: 20.10.02

Classes
  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.
Functions
 
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.
 
nearestOn2(point, points, **closed_radius_height)
DEPRECATED, use method sphericalNvector.nearestOn3.
 
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.
Variables
  __all__ = _ALL_LAZY.sphericalNvector
Function Details

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:
  • PointsError - Insufficient number of points.
  • TypeError - Some points are not LatLon.

See Also: pygeodesy.areaOf, sphericalTrigonometry.areaOf and ellipsoidalKarney.areaOf.

Example:

>>> b = LatLon(45, 1), LatLon(45, 2), LatLon(46, 2), LatLon(46, 1)
>>> areaOf(b)  # 8666058750.718977

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)  # 50.9076°N, 004.5086°E

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:
  • PointsError - Insufficient number of points.
  • TypeError - Some points are not LatLon.

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")  # Basse Castouillet
>>> q = LatLon("47°18.664'N","002°31.717'W")  # Basse Hergo
>>> t = triangulate(p, 7, q, 295)  # 47.323667°N, 002.568501°W'

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.

See Also: Trilateration.