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

Module sphericalTrigonometry

Trigonometric classes geodetic (lat-/longitude) LatLon and geocentric (ECEF) Cartesian and functionsareaOf, intersection, isPoleEnclosedBy, meanOf, nearestOn2 and perimeterOf, all spherical.

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

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'>, **kwds)
Compute the vectorial sum of several vectors.
 
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.

sumOf(vectors, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **kwds)

 

Compute the vectorial sum of several vectors.

Parameters:
  • vectors - Vectors to be added (Vector3d[]).
  • Vector - Optional class for the vectorial sum (Vector3d).
  • kwds - Optional, additional Vector keyword arguments, ignored if Vector=None.
Returns:
Vectorial sum (Vector).
Raises:

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.