pygeodesy.sphericalNvector

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

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

Version: 25.05.27

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.771415, wrap=False, polar=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. |
nearestOn2(point, points, **closed_radius_height) DEPRECATED, use method sphericalNvector.nearestOn3. |
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. |

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` - 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, polar=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`). `polar` - Use of `polar=True` not implemented (`bool`). Returns: Polygon area (`meter` squared, same units as `radius`, or `radians` if `radius is None`). Raises: `PointsError` - Insufficient number of `points`. `TypeError` - Some `points` are not LatLon. See Also: Functions pygeodesy.areaOf, sphericalTrigonometry.areaOf and ellipsoidalKarney.areaOf.

### 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. See Also: Function intersection2 for further details.

### 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. See Also: Function sphericalNvector.intersection.

### 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: `@deprecated_function`

### 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. See Also: Functions pygeodesy.perimeterOf, ellipsoidalKarney.perimeterOf and sphericalTrigonometry.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`). `Vector_kwds` - Optional, additional `Vector` keyword arguments. Returns: Vectorial sum (`Vector`). Raises: `VectorError` - No `nvectors`.

### 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`. See Also: Trilateration.