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, 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.

Version: 20.04.21

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. |

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. See Also: pygeodesy.perimeterOf, sphericalTrigonometry.perimeterOf and ellipsoidalKarney.perimeterOf.

### 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: `VectorError` - No `nvectors`.

### 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. See also Trilateration. 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: `TypeError` - If `point1`, `point2` or `point3` is not LatLon. `ValueError` - Invalid `distance1`, `distance2`, `distance3` or `radius`, or some `distances` exceed trilateration or some `points` coincide.