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

Module sphericalTrigonometry

Trigonometric classes geodetic (lat-/longitude) LatLon and geocentric (ECEF) Cartesian and functions areaOf, intersection, intersections2, isPoleEnclosedBy, meanOf, nearestOn3 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.10.08

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.
 
intersections2(center1, rad1, center2, rad2, radius=6371008.77141, height=None, wrap=True, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **LatLon_kwds)
Compute the intersection points of two circles each defined by a center point and a radius.
 
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).
Variables
  __all__ = _ALL_LAZY.sphericalTrigonometry
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 as Vector or if Vector is None, a Vector3Tuple(x, y, z).
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:
  • IntersectionError - Intersection is ambiguous or infinite or the paths are coincident, colinear or parallel.
  • TypeError - A start or end point not LatLon.
  • ValueError - 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'

intersections2 (center1, rad1, center2, rad2, radius=6371008.77141, height=None, wrap=True, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **LatLon_kwds)

 

Compute the intersection points of two circles each defined by a center point and a radius.

Arguments:
  • center1 - Center of the first circle (LatLon).
  • rad1 - Radius of the first circle (meter or radians, see radius).
  • center2 - Center of the second circle (LatLon).
  • rad2 - Radius of the second circle (meter or radians, see radius).
  • radius - Mean earth radius (meter or None if both rad1 and rad2 are given in radians).
  • height - Optional height for the intersection points, overriding the "radical height" at the "radical line" between both centers (meter) or None.
  • wrap - Wrap and unroll longitudes (bool).
  • LatLon - Optional class to return the intersection points (LatLon) or None.
  • LatLon_kwds - Optional, additional LatLon keyword arguments, ignored if LatLon=None.
Returns:
2-Tuple of the intersection points, each a LatLon instance or LatLon3Tuple(lat, lon, height) if LatLon is None. For abutting circles, both intersection points are the same instance.
Raises:
  • IntersectionError - Concentric, antipodal, invalid or non-intersecting circles.
  • TypeError - If center1 or center2 not LatLon.
  • ValueError - Invalid rad1, rad2, radius or height.

Note: Courtesy Samuel Čavoj.

See Also: This Answer.

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.