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

# Module sphericalTrigonometry

Trigonometric spherical geodetic (lat-/longitude) class LatLon and functions areaOf, intersection, isPoleEnclosedBy, meanOf, nearestOn2 and perimeterOf.

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

Version: 19.07.09

Classes
| LatLon New point on spherical model earth model.

Functions
ispolar(points, wrap=False) Check whether a polygon encloses a pole. |
areaOf(points, radius=6371008.77141, wrap=True) Calculate the area of a (spherical) polygon (with great circle arcs joining the points). |
intersection(start1, end1, start2, end2, height=None, wrap=False, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>) Compute the intersection point of two paths both defined by two points or a start point and bearing from North. |
isPoleEnclosedBy(points, wrap=False) DEPRECATED, use function ispolar. |
meanOf(points, height=None, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>) Compute the geographic mean of several points. |
nearestOn2(point, points, closed=False, radius=6371008.77141, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **options) DEPRECATED, use function sphericalTrigonometry.nearestOn3. |
nearestOn3(point, points, closed=False, radius=6371008.77141, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **options) Locate the point on a polygon closest to an other, reference point. |
perimeterOf(points, closed=False, radius=6371008.77141, wrap=True) Compute the perimeter of a (spherical) polygon (with great circle arcs joining the points). |

Function Details

### ispolar(points, wrap=False) |
Check whether a polygon encloses a pole. Parameters: `points` - The polygon points (`LatLon`[]). `wrap` - Wrap and unroll longitudes (`bool`). Returns: `True` if the polygon encloses a pole, `False` otherwise. Raises: `ValueError` - Insufficient number of `points`. `TypeError` - Some `points` are not `LatLon` or don't have `bearingTo2`, `initialBearingTo` and `finalBearingTo` methods.

### areaOf(points, radius=6371008.77141, wrap=True) |
Calculate the area of a (spherical) polygon (with great circle arcs joining the points). Parameters: `points` - The polygon points (LatLon[]). `radius` - Optional, mean earth radius (`meter`). `wrap` - Wrap and unroll longitudes (`bool`). Returns: Polygon area (`meter`, same units as `radius`, squared). Raises: `TypeError` - Some `points` are not LatLon. `ValueError` - Insufficient number of `points`. Note: The area is based on Karney's 'Area of a spherical polygon'. See Also: pygeodesy.areaOf, sphericalNvector.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

### intersection(start1, end1, start2, end2, height=None, wrap=False, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>) |
Compute the intersection point of two paths both defined by two points or a start point and bearing from North. Parameters: `start1` - Start point of the first path (LatLon). `end1` - End point ofthe 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 for the intersection point, overriding the mean height (`meter`). `wrap` - Wrap and unroll longitudes (`bool`). `LatLon` - Optional (sub-)class to return the intersection point (LatLon) or `None`. Returns: The intersection point (`LatLon`) or a LatLon3Tuple`(lat, lon, height)` if `LatLon` is `None`. An alternate intersection point might be the antipode to the returned result. Raises: `TypeError` - A `start` or `end` point not LatLon. `ValueError` - Intersection is ambiguous or infinite or the paths are parallel, coincident or null. 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'

### meanOf(points, height=None, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>) |
Compute the geographic mean of several points. Parameters: `points` - Points to be averaged (LatLon[]). `height` - Optional height at mean point, overriding the mean height (`meter`). `LatLon` - Optional (sub-)class to return the mean point (LatLon) or `None`. Returns: Point at 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`.

### nearestOn2(point, points, closed=False, radius=6371008.77141, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **options) |
DEPRECATED, use function sphericalTrigonometry.nearestOn3. Returns: ... `closest` as `LatLon` or a 2-tuple `(lat, lon)` without the height if `LatLon` is `None` ...

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

### perimeterOf(points, closed=False, radius=6371008.77141, wrap=True) |
Compute the perimeter of a (spherical) polygon (with great circle arcs joining the points). Parameters: `points` - The polygon points (LatLon[]). `closed` - Optionally, close the polygon (`bool`). `radius` - Optional, mean earth radius (`meter`). `wrap` - Wrap and unroll longitudes (`bool`). Returns: Polygon perimeter (`meter`, same units as `radius`). Raises: `TypeError` - Some `points` are not LatLon. `ValueError` - Insufficient number of `points`. Note: This perimeter is based on the haversine formula. See Also: pygeodesy.perimeterOf, sphericalNvector.perimeterOf and ellipsoidalKarney.perimeterOf.