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

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) 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=False) Compute the intersections of a circle and a line. |
intersection(start1, end1, start2, end2, height=None, wrap=False, LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>, **LatLon_kwds) Locate the intersections of two (great circle) lines each defined by two points or by a start point and an (initial) bearing. |
intersection2(start1, end1, start2, end2, height=None, wrap=False, LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>, **LatLon_kwds) Locate the intersections of two (great circle) lines each defined by two points or by a start point and an (initial) bearing. |
meanOf(points, height=None, wrap=False, 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, 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 points and the initial bearings 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) |
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`). 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=False) |
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` - If `True`, wrap or normalize and unroll the `point` and the `circle` and `bearing` points (`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, wrap=False, LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>, **LatLon_kwds) |
Locate the intersections of two (great circle) lines each defined by two points or by a start point and an (initial) bearing. Arguments: `start1` - Start point of the first line (LatLon). `end1` - End point of the first line (LatLon) or the initial bearing at the first start point (compass `degrees360`). `start2` - Start point of the second line (LatLon). `end2` - End point of the second line (LatLon) or the initial bearing at the second start point (compass `degrees360`). `height` - Optional height at the intersection point, overriding the mean height (`meter`). `wrap` - If `True`, wrap or normalize and unroll `start2` and both `end*` points (`bool`). `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 if `LatLon is 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.intersection2. 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

### intersection2 (start1, end1, start2, end2, height=None, wrap=False, LatLon=<class 'pygeodesy.sphericalNvector.LatLon'>, **LatLon_kwds) |
Locate the intersections of two (great circle) lines each defined by two points or by a start point and an (initial) bearing. Arguments: `start1` - Start point of the first line (LatLon). `end1` - End point of the first line (LatLon) or the initial bearing at the first start point (compass `degrees360`). `start2` - Start point of the second line (LatLon). `end2` - End point of the second line (LatLon) or the initial bearing at the second start point (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` - Optional class to return the intersection and antipodal points (LatLon). `LatLon_kwds` - Optional, additional `LatLon` keyword arguments, ignored if `LatLon is None`. Returns: 2-Tuple `(intersection, antipode)`, each a (`LatLon`) or if `LatLon is 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=<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`). `wrap` - If `True`, wrap or normalize `points` (`bool`). `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` 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 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`). `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. 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, 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.