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-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: 23.04.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.771415) Calculate the area of a (spherical) polygon or composite (with great circle arcs joining consecutive points). |
intersecant2(center, circle, point, bearing, radius=6371008.771415, exact=False, height=None, wrap=True) Compute the intersections of a circle and a line. |
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. |
nearestOn3(point, points, closed=False, radius=6371008.771415, height=None) 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) 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, LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>, **LatLon_kwds) Locate a point given two known points and the initial bearings from those points. |
trilaterate(point1, distance1, point2, distance2, point3, distance3, radius=6371008.771415, 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.771415) |
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`. 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. Example:
    >>> b = LatLon(45, 1), LatLon(45, 2), LatLon(46, 2), LatLon(46, 1)
    >>> areaOf(b)  # 8666058750.718977

### intersecant2 (center, circle, point, bearing, radius=6371008.771415, exact=False, height=None, wrap=True) |
Compute the intersections of a circle and a line. Arguments: `center` - Center of the circle (LatLon). `circle` - Radius of the circle (`meter`, same units as `radius`) or a point on the circle (LatLon). `point` - A point in- or outside the circle (LatLon). `bearing` - Bearing at the `point` (compass `degrees360`) or a second point on the line (LatLon). `radius` - Mean earth radius (`meter`, conventionally). `exact` - If `True` use the exact rhumb methods for azimuth, destination and distance, if `False` use the basic rhumb methods (`bool`) or if `None` use the great circle methods. `height` - Optional height for the intersection points (`meter`, conventionally) or `None`. `wrap` - Wrap and unroll longitudes (`bool`). Returns: 2-Tuple of the intersection points (representing a chord), each an instance of this class. For a tangent line, each point `is` this very instance. Raises: `IntersectionError` - The circle and line do not intersect. `TypeError` - If `center` or `point` not LatLon or `circle` or `bearing` invalid. `ValueError` - Invalid `circle`, `bearing`, `radius`, `exact` or `height`.

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

### nearestOn3 (point, points, closed=False, radius=6371008.771415, height=None) |
Locate the point on a polygon (with great circle arcs joining consecutive points) closest to an other point. If the given point is within the extent of any great circle arc, the closest point is on that arc. Otherwise, the closest 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 arc (`meter`). 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) |
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`. 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, 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`). `Vector_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 the 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 is 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.771415, 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 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.