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

# Module sphericalTrigonometry

Spherical, `trigonometry`-based geodesy.

Trigonometric classes geodetic (lat-/longitude) LatLon and geocentric (ECEF) Cartesian and functions areaOf, intersection, intersections2, isPoleEnclosedBy, meanOf, nearestOn3 and perimeterOf, all spherical.

Pure Python implementation of geodetic (lat-/longitude) methods using spherical trigonometry, transcoded from JavaScript originals by (C) Chris Veness 2011-2016 published under the same MIT Licence**, see Latitude/Longitude.

Version: 23.04.11

Classes
| Cartesian Extended to convert geocentric, Cartesian points to spherical, geodetic LatLon.
| LatLon New point on spherical model earth model.

Functions
ispolar(points, wrap=False) Check whether a polygon encloses a pole. |
sumOf(vectors, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds) Compute the vectorial sum of several vectors. |
areaOf(points, radius=6371008.771415, wrap=True) Calculate the area of a (spherical) polygon or composite (with the pointsjoined by great circle arcs). |
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, wrap=False, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **LatLon_kwds) Compute the intersection point of two lines, each defined by two points or a start point and bearing from North. |
intersections2(center1, rad1, center2, rad2, radius=6371008.771415, eps=0.0, height=None, wrap=True, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **LatLon_kwds) Compute the intersection points of two circles each defined by a center point and a radius. |
isPoleEnclosedBy(points, wrap=False) DEPRECATED, use function pygeodesy.ispolar. |
meanOf(points, height=None, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **LatLon_kwds) Compute the geographic mean of several points. |
nearestOn2(point, points, **closed_radius_LatLon_options) DEPRECATED, use function sphericalTrigonometry.nearestOn3. |
nearestOn3(point, points, closed=False, radius=6371008.771415, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **options) Locate the point on a path or polygon closest to a reference point. |
perimeterOf(points, closed=False, radius=6371008.771415, wrap=True) Compute the perimeter of a (spherical) polygon or composite (with great circle arcs joining the points). |
triangle7(latA, lonA, latB, lonB, latC, lonC, radius=6371008.771415, excess=<function excessAbc_ at 0x7f99107ce450>, wrap=False) Compute the angles, sides, and area of a (spherical) triangle. |
triangle8_(phiA, lamA, phiB, lamB, phiC, lamC, excess=<function excessAbc_ at 0x7f99107ce450>, wrap=False) Compute the angles, sides, spherical deficit and spherical excess of a (spherical) triangle. |

Variables
| __all__ = `_ALL_LAZY.sphericalTrigonometry`

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.

### sumOf (vectors, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds) |
Compute the vectorial sum of several vectors. Arguments: `vectors` - Vectors to be added (Vector3d[]). `Vector` - Optional class for the vectorial sum (Vector3d). `Vector_kwds` - Optional `Vector` keyword arguments, ignored if `Vector is None`. Returns: Vectorial sum as `Vector` or if `Vector` is `None`, a named Vector3Tuple`(x, y, z)`. Raises: `VectorError` - No `vectors`.

### areaOf (points, radius=6371008.771415, wrap=True) |
Calculate the area of a (spherical) polygon or composite (with the pointsjoined by great circle arcs). Arguments: `points` - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH). `radius` - Mean earth radius, ellipsoid or datum (`meter`, Ellipsoid, Ellipsoid2, Datum or a_f2Tuple) or `None`. `wrap` - Wrap and unroll longitudes (`bool`). Returns: Polygon area (`meter` quared, 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 semi-circular polygon edge. Note: The area is based on Karney's 'Area of a spherical polygon', 3rd Answer. See Also: Functions pygeodesy.areaOf, sphericalNvector.areaOf, pygeodesy.excessKarney, ellipsoidalExact.areaOf and ellipsoidalKarney.areaOf. Example:
    >>> b = LatLon(45, 1), LatLon(45, 2), LatLon(46, 2), LatLon(46, 1)
    >>> areaOf(b)  # 8666058750.718977
    >>> c = LatLon(0, 0), LatLon(1, 0), LatLon(0, 1)
    >>> areaOf(c)  # 6.18e9

### 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, wrap=False, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **LatLon_kwds) |
Compute the intersection point of two lines, each defined by two points or a start point and bearing from North. 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 for the intersection point, overriding the mean height (`meter`). `wrap` - Wrap and unroll longitudes (`bool`). `LatLon` - Optional class to return the intersection point (LatLon) or `None`. `LatLon_kwds` - Optional, additional `LatLon` keyword arguments, ignored if `LatLon is None`. Returns: The intersection point as a (`LatLon`) or if `LatLon is None` a LatLon3Tuple`(lat, lon, height)`. An alternate intersection point might be the antipode to the returned result. Raises: `IntersectionError` - Ambiguous or infinite intersection or colinear, parallel or otherwise non-intersecting lines. `TypeError` - A `start` or `end` point not LatLon. `ValueError` - Invalid `height` or `null` line. Example:
    >>> p = LatLon(51.8853, 0.2545)
    >>> s = LatLon(49.0034, 2.5735)
    >>> i = intersection(p, 108.547, s, 32.435)  # '50.9078°N, 004.5084°E'

### intersections2 (center1, rad1, center2, rad2, radius=6371008.771415, eps=0.0, height=None, wrap=True, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **LatLon_kwds) |
Compute the intersection points of two circles each defined by a center point and a radius. Arguments: `center1` - Center of the first circle (LatLon). `rad1` - Radius of the first circle (`meter` or `radians`, see `radius`). `center2` - Center of the second circle (LatLon). `rad2` - Radius of the second circle (`meter` or `radians`, see `radius`). `radius` - Mean earth radius (`meter` or `None` if `rad1`, `rad2` and `eps` are given in `radians`). `eps` - Required overlap (`meter` or `radians`, see `radius`). `height` - Optional height for the intersection points (`meter`, conventionally) or `None` for the "radical height" at the radical line between both centers. `wrap` - Wrap and unroll longitudes (`bool`). `LatLon` - Optional class to return the intersection points (LatLon) or `None`. `LatLon_kwds` - Optional, additional `LatLon` keyword arguments, ignored if `LatLon is None`. Returns: 2-Tuple of the intersection points, each a `LatLon` instance or if `LatLon is None` a LatLon3Tuple`(lat, lon, height)`. For abutting circles, both intersection points are the same instance, aka the radical center. Raises: `IntersectionError` - Concentric, antipodal, invalid or non-intersecting circles. `TypeError` - If `center1` or `center2` not LatLon. `ValueError` - Invalid `rad1`, `rad2`, `radius`, `eps` or `height`. Note: Courtesy of Samuel Čavoj. See Also: This Answer.

### isPoleEnclosedBy (points, wrap=False) |
DEPRECATED, use function pygeodesy.ispolar. Decorators: `@deprecated_function`

### meanOf (points, height=None, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **LatLon_kwds) |
Compute the geographic mean of several points. Arguments: `points` - Points to be averaged (LatLon[]). `height` - Optional height at mean point, overriding the mean height (`meter`). `LatLon` - Optional class to return the mean point (LatLon) or `None`. `LatLon_kwds` - Optional, additional `LatLon` keyword arguments, ignored if `LatLon is None`. Returns: The geographic mean and height (`LatLon`) or a LatLon3Tuple`(lat, lon, height)` if `LatLon` is `None`. Raises: `TypeError` - Some `points` are not LatLon. `ValueError` - No `points` or invalid `height`.

### nearestOn2 (point, points, **closed_radius_LatLon_options) |
DEPRECATED, use function sphericalTrigonometry.nearestOn3. Returns: ... 2-tuple `(closest, distance)` of the `closest` point (LatLon) on the polygon and the `distance` between the `closest` and the given `point`. The `closest` is a `LatLon` or a LatLon2Tuple`(lat, lon)` if `LatLon` is `None` ... Decorators: `@deprecated_function`

### nearestOn3 (point, points, closed=False, radius=6371008.771415, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **options) |
Locate the point on a path or polygon closest to a reference point. Distances are approximated using function pygeodesy.equirectangular_, subject to the supplied `options`. Arguments: `point` - The reference point (LatLon). `points` - The path or polygon points (LatLon[]). `closed` - Optionally, close the polygon (`bool`). `radius` - Mean earth radius (`meter`). `LatLon` - Optional class to return the closest point (LatLon) or `None`. `options` - Optional keyword arguments for function pygeodesy.equirectangular_. Returns: A NearestOn3Tuple`(closest, distance, angle)` with the `closest` point as `LatLon` or LatLon3Tuple`(lat, lon, height)` if `LatLon` is `None`. The `distance` is the pygeodesy.equirectangular_ distance between the `closest` and the given `point` converted to `meter`, same units as `radius`. The `angle` from the given `point` to the `closest` is in compass `degrees360`, like function pygeodesy.compassAngle. The `height` is the (interpolated) height at the `closest` point. Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function pygeodesy.equirectangular_. `PointsError` - Insufficient number of `points`. `TypeError` - Some `points` are not `LatLon`. `ValueError` - Invalid `radius`. See Also: Functions pygeodesy.equirectangular_ and pygeodesy.nearestOn5.

### perimeterOf (points, closed=False, radius=6371008.771415, wrap=True) |
Compute the perimeter of a (spherical) polygon or composite (with great circle arcs joining the points). Arguments: `points` - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH). `closed` - Optionally, close the polygon (`bool`). `radius` - Mean earth radius (`meter`) or `None`. `wrap` - Wrap and unroll longitudes (`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. Note: Distances are based on function pygeodesy.vincentys_. See Also: Functions pygeodesy.perimeterOf, sphericalNvector.perimeterOf and ellipsoidalKarney.perimeterOf.

### triangle7 (latA, lonA, latB, lonB, latC, lonC, radius=6371008.771415, excess=<function excessAbc_ at 0x7f99107ce450>, wrap=False) |
Compute the angles, sides, and area of a (spherical) triangle. Arguments: `latA` - First corner latitude (`degrees`). `lonA` - First corner longitude (`degrees`). `latB` - Second corner latitude (`degrees`). `lonB` - Second corner longitude (`degrees`). `latC` - Third corner latitude (`degrees`). `lonC` - Third corner longitude (`degrees`). `radius` - Mean earth radius, ellipsoid or datum (`meter`, Ellipsoid, Ellipsoid2, Datum or a_f2Tuple) or `None`. `excess` - Spherical excess callable (excessAbc_, excessGirard_ or excessLHuilier_). `wrap` - Wrap and pygeodesy.unroll180 longitudes (`bool`). Returns: A Triangle7Tuple`(A, a, B, b, C, c, area)` with spherical angles `A`, `B` and `C`, angular sides `a`, `b` and `c` all in `degrees` and `area` in square `meter` or same units as `radius` squared or if `radius=0` or `None`, a Triangle8Tuple`(A, a, B, b, C, c, D, E)` all in `radians` with the spherical excess `E` as the `unit area` in `radians`.

### triangle8_ (phiA, lamA, phiB, lamB, phiC, lamC, excess=<function excessAbc_ at 0x7f99107ce450>, wrap=False) |
Compute the angles, sides, spherical deficit and spherical excess of a (spherical) triangle. Arguments: `phiA` - First corner latitude (`radians`). `lamA` - First corner longitude (`radians`). `phiB` - Second corner latitude (`radians`). `lamB` - Second corner longitude (`radians`). `phiC` - Third corner latitude (`radians`). `lamC` - Third corner longitude (`radians`). `excess` - Spherical excess callable (excessAbc_, excessGirard_ or excessLHuilier_). `wrap` - Wrap and pygeodesy.unrollPI longitudes (`bool`). Returns: A Triangle8Tuple`(A, a, B, b, C, c, D, E)` with spherical angles `A`, `B` and `C`, angular sides `a`, `b` and `c`, spherical deficit `D` and spherical excess `E`, all in `radians`.