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

# Module sphericalNvector

N-vector-based spherical geodetic (lat-/longitude) classes LatLon and Nvector and functions areaOf, intersection, meanOf, nearestOn2, triangulate and trilaterate.

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: 18.09.23

Classes
| LatLon New n-vector based point on spherical earth model.
| Nvector An n-vector is a position representation using a (unit) vector normal to the earth's surface.

Functions
areaOf(points, radius=6371008.77141) Calculate the area of a spherical polygon where the sides of the polygon are great circle arcs joining the 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, radius=6371008.77141, height=None) Locate the closest point on the great circle segment between any two consecutive points of a path. |
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'>) Locate a point at given distances from three other points. |

Function Details

### areaOf(points, radius=6371008.77141) |
Calculate the area of a spherical polygon where the sides of the polygon are great circle arcs joining the points. Parameters: `points` - The points defining the polygon (LatLon[]). `radius` - Optional, mean earth radius (meter). Returns: Polygon area (float, same units as radius squared). Raises: `TypeError` - Some points are not LatLon. `ValueError` - Insufficient number of points. 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'>) |
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 first path (LatLon) or the initial bearing at the first start point (compass degrees). `start2` - Start point of the second path (LatLon). `end2` - End point of second path (LatLon) or the initial bearing at the second start point (compass degrees). `height` - Optional height at the intersection point, overriding the default height (meter). `LatLon` - Optional LatLon class for the intersection point (LatLon). Returns: Intersection point (LatLon) or None if no unique intersection exists. Raises: `TypeError` - Start or end point(s) not LatLon. `Valuerror` - Paths coincide. 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'>) |
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 LatLon class for the mean point (LatLon). Returns: Point at geographic mean and mean height (LatLon). Raises: `ValueError` - Insufficient number of points.

### nearestOn2(point, points, radius=6371008.77141, height=None) |
Locate the closest point on the great circle segment between any two consecutive points of a path. If the given point is within the extent of any segment, the closest point is on the segment. Otherwise the closest point is the nearest of the segment end points. Parameters: `point` - The reference point (LatLon). `points` - The points of the path (LatLon[]). `radius` - Optional, mean earth radius (meter). `height` - Optional height, overriding the mean height for a point if within segment (meter). Returns: 2-Tuple (closest, distance) of the closest point (LatLon) on the path and the distance to that point from the given point in meter, rather the units of radius. Raises: `TypeError` - Some points or the point not LatLon. `ValueError` - No points.

### 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 degrees). `point2` - Second reference point (LatLon). `bearing2` - Bearing at the second point (compass degrees). `height` - Optional height at the triangulated point, overriding the mean height (meter). `LatLon` - Optional LatLon class for the triangulated point (LatLon). Returns: Triangulated point (LatLon). Raises: `TypeError` - One of the points 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, LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>) |
Locate a point at given distances from three other points. See also Trilateration. Parameters: `point1` - First point (LatLon). `distance1` - Distance to the first point (same units as radius). `point2` - Second point (LatLon). `distance2` - Distance to the second point (same units as radius). `point3` - Third point (LatLon). `distance3` - Distance to the third point (same units as radius). `radius` - Optional, mean earth radius (meter). `height` - Optional height at the trilaterated point, overriding the mean height (meter or same unit as radius). `LatLon` - Optional LatLon class for the trilaterated point (LatLon). Returns: Trilaterated point (LatLon). Raises: `TypeError` - One of the points is not LatLon. `ValueError` - Invalid radius, some distances exceed trilateration or some points coincide.