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: 20.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.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'>, **LatLon_kwds)
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'>, **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.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.

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=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).

Arguments:
  • points - The polygon points (LatLon[]).
  • radius - Mean earth radius (meter).
  • wrap - Wrap and unroll longitudes (bool).
Returns:
Polygon area (meter, same units as radius, squared).
Raises:
  • PointsError - Insufficient number of points.
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid radius.

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'>, **LatLon_kwds)

 

Compute the intersection point of two paths both defined by two points or a start point and bearing from North.

Arguments:
  • 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 class to return the intersection point (LatLon) or None.
  • LatLon_kwds - Optional, additional LatLon keyword arguments, ignored if LatLon=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 or invalid height.

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'>, **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=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 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 ...

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.

Arguments:
  • point - The other, reference point (LatLon).
  • points - The 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 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 equirectangular_ distance between the closest and the given point in meter, same units as radius. The angle from the given 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_.
  • PointsError - Insufficient number of points.
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid radius.

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

Arguments:
  • points - The polygon points (LatLon[]).
  • closed - Optionally, close the polygon (bool).
  • radius - Mean earth radius (meter).
  • wrap - Wrap and unroll longitudes (bool).
Returns:
Polygon perimeter (meter, same units as radius).
Raises:
  • PointsError - Insufficient number of points.
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid radius.

Note: This perimeter is based on the haversine formula.

See Also: pygeodesy.perimeterOf, sphericalNvector.perimeterOf and ellipsoidalKarney.perimeterOf.