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.10.26

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, 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)
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)
Locate the point on a polygon closest to an other point.
 
perimeterOf(points, closed=False, radius=6371008.77141, wrap=True)
Compute the perimeter of a polygon.
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 a pole is enclosed by the polygon, 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, 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 degrees360).
  • start2 - Start point of second path (LatLon).
  • bearing2 - Initial bearing from start2 (compass degrees360).
  • height - Optional height for the intersection point, overriding the mean height (meter).
  • wrap - Wrap and unroll longitudes (bool).
  • LatLon - Optional (sub-)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'

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 3-tuple (degrees90, degrees180, 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)

 

Locate the point on a polygon closest to an other 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 for the closest point (LatLon) or None.
  • options - Optional keyword arguments for function equirectangular_.
Returns:
2-Tuple (closest, distance) of the closest point on the polygon and the distance to that point. The closest as LatLon or a 2-tuple (lat, lon) if LatLon is None. The distance is the equirectangular_ distance between the closest and reference point in meter, same units as radius.
Raises:
  • LimitError - Lat- and/or longitudinal delta exceeds limit, see function equirectangular_.
  • TypeError - Some points are not LatLon.
  • ValueError - Insufficient number of points.

See Also: Functions equirectangular_ and nearestOn3.

perimeterOf(points, closed=False, radius=6371008.77141, wrap=True)

 

Compute the perimeter of a polygon.

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 and ellipsoidalKarney.perimeterOf.