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

Classes
| LatLon New point on spherical model earth model.

Functions
areaOf(points, radius=6371008.77141, wrap=True) Calculate the area of a spherical polygon where the sides of the polygon are great circle arcs joining the points. |
intersection(start1, bearing1, start2, bearing2, height=None, wrap=False, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>) Compute the intersection point of two paths each defined by a start point and an initial bearing. |
isPoleEnclosedBy(points, wrap=False) Test whether a pole is enclosed by a polygon defined by a list, sequence, set or tuple of points. |
meanOf(points, height=None, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>) Compute the geographic mean of the supplied points. |
nearestOn2(point, points, radius=6371008.77141, **options) Locate the closest point on any segment between two consecutive points of a path. |
perimeterOf(points, closed=False, radius=6371008.77141, wrap=True) Compute the perimeter of a polygon/-line defined by an array, list, sequence, set or tuple of points. |

Function Details

### areaOf(points, radius=6371008.77141, wrap=True) |
Calculate the area of a spherical polygon where the sides of the polygon are great circle arcs joining the points. Parameters: `points` - The points defining the polygon (LatLon[]). `radius` - Optional, mean earth radius (meter). `wrap` - Wrap and unroll longitudes (bool). Returns: Polygon area (float, same units as radius squared). Raises: `TypeError` - Some points are not LatLon. `ValueError` - Insufficient number of points. Note: The area is based on Karney '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, bearing1, start2, bearing2, height=None, wrap=False, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>) |
Compute the intersection point of two paths each defined by a start point and an initial bearing. Parameters: `start1` - Start point of first path (LatLon). `bearing1` - Initial bearing from start1 (compass degrees). `start2` - Start point of second path (LatLon). `bearing2` - Initial bearing from start2 (compass degrees). `height` - Optional height for the intersection point, overriding the mean height (meter). `wrap` - Wrap and unroll longitudes (bool). `LatLon` - Optional LatLon class for the intersection point (LatLon) or None. Returns: Intersection point (LatLon) or 3-tuple (degrees90, degrees180, height) if LatLon is None. Raises: `TypeError` - Point start1 or start2 is not LatLon. `ValueError` - Intersection is ambiguous or infinite or the paths are parallel or coincident. 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'

### isPoleEnclosedBy(points, wrap=False) |
Test whether a pole is enclosed by a polygon defined by a list, sequence, set or tuple of points. Parameters: `points` - The points defining the polygon (LatLon[]). `wrap` - Wrap and unroll longitudes (bool). Returns: True if the polygon encloses a pole (bool). Raises: `ValueError` - Insufficient number of points. `TypeError` - Some points are not LatLon.

### meanOf(points, height=None, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>) |
Compute the geographic mean of the supplied points. Parameters: `points` - Points to be averaged (LatLon[]). `height` - Optional height at mean point overriding the mean height (meter). `LatLon` - Optional LatLon class to return mean point (LatLon) or None. Returns: Point at geographic mean and height (LatLon) or 3-tuple (degrees90, degrees180, height) if LatLon is None. Raises: `TypeError` - Some points are not LatLon. `ValueError` - No points.

### nearestOn2(point, points, radius=6371008.77141, **options) |
Locate the closest point on any segment between two consecutive points of a path. If the given point is within the extent of any segment, the closest point is on the segment. Otherwise the closest point is the nearest of the segment end points. Distances are approximated by function equirectangular_, subject to the supplied options. Parameters: `point` - The reference point (LatLon). `points` - The points of the path (LatLon[]). `radius` - Optional, mean earth radius (meter). `options` - Optional keyword arguments for function equirectangular_. Returns: 2-Tuple (closest, distance) of the closest point (LatLon) on the path and the distance to that point. The distance is the equirectangular_ distance between the given and the closest point in meter, rather the units of radius. Raises: `LimitError` - Lat- and/or longitudinal delta exceeds limit, see function equirectangular_. `TypeError` - Some points are not LatLon. `ValueError` - Insufficient number of points.

### perimeterOf(points, closed=False, radius=6371008.77141, wrap=True) |
Compute the perimeter of a polygon/-line defined by an array, list, sequence, set or tuple of points. Parameters: `points` - The points defining the polygon (LatLon[]). `closed` - Optionally, close the polygon/-line (bool). `radius` - Optional, mean earth radius (meter). `wrap` - Wrap and unroll longitudes (bool). Returns: Polygon perimeter (float, 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 and ellipsoidalKarney.perimeterOf.