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

Module sphericalTrigonometry

Spherical, trigonometry-based geodesy.

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, transcoded from JavaScript originals by (C) Chris Veness 2011-2016 published under the same MIT Licence**, see Latitude/Longitude.


Version: 22.09.14

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.771415, wrap=True)
Calculate the area of a (spherical) polygon (with the points joined by great circle arcs).
 
intersection(start1, end1, start2, end2, height=None, wrap=False, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **LatLon_kwds)
Compute the intersection point of two paths, each defined by two points or a start point and bearing from North.
 
intersections2(center1, rad1, center2, rad2, radius=6371008.771415, eps=0.0, 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 pygeodesy.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.771415, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **options)
Locate the point on a path or polygon closest to a reference point.
 
perimeterOf(points, closed=False, radius=6371008.771415, wrap=True)
Compute the perimeter of a (spherical) polygon (with great circle arcs joining the points).
 
triangle7(latA, lonA, latB, lonB, latC, lonC, radius=6371008.771415, excess=<function excessAbc at 0x7f94907d7dd0>, wrap=False)
Compute the angles, sides, and area of a (spherical) triangle.
 
triangle8_(phiA, lamA, phiB, lamB, phiC, lamC, excess=<function excessAbc at 0x7f94907d7dd0>, wrap=False)
Compute the angles, sides, spherical deficit and spherical excess of a (spherical) triangle.
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 is None.
Returns:
Vectorial sum as Vector or if Vector is None, a named Vector3Tuple(x, y, z).
Raises:

areaOf (points, radius=6371008.771415, wrap=True)

 

Calculate the area of a (spherical) polygon (with the points joined by great circle arcs).

Arguments:
Returns:
Polygon area (meter quared, same units as radius or radians if radius is None).
Raises:
  • PointsError - Insufficient number of points.
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid radius or semi-circular polygon edge.

Note: The area is based on Karney's 'Area of a spherical polygon', 3rd Answer.

See Also: Functions pygeodesy.areaOf, sphericalNvector.areaOf, pygeodesy.excessKarney, ellipsoidalExact.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, each defined by two points or a start point and bearing from North.

Arguments:
  • start1 - Start point of the first path (LatLon).
  • end1 - End point of the 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 is None.
Returns:
The intersection point as a (LatLon) or if LatLon is None a LatLon3Tuple(lat, lon, height). An alternate intersection point might be the antipode to the returned result.
Raises:
  • IntersectionError - Ambiguous or infinite intersection or colinear, parallel or otherwise non-intersecting paths.
  • TypeError - A start or end point not LatLon.
  • ValueError - Invalid height or null path.

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.771415, eps=0.0, 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 rad1, rad2 and eps are given in radians).
  • eps - Required overlap (meter or radians, see radius).
  • height - Optional height for the intersection points (meter, conventionally) or None for the "radical height" at the radical line between both centers.
  • 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 is None.
Returns:
2-Tuple of the intersection points, each a LatLon instance or if LatLon is None a LatLon3Tuple(lat, lon, height). For abutting circles, both intersection points are the same instance, aka radical center.
Raises:
  • IntersectionError - Concentric, antipodal, invalid or non-intersecting circles.
  • TypeError - If center1 or center2 not LatLon.
  • ValueError - Invalid rad1, rad2, radius, eps or height.

Note: Courtesy of Samuel Čavoj.

See Also: This Answer.

isPoleEnclosedBy (points, wrap=False)

 

DEPRECATED, use function pygeodesy.ispolar.

Decorators:
  • @deprecated_function

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 is None.
Returns:
The 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 ...
Decorators:
  • @deprecated_function

nearestOn3 (point, points, closed=False, radius=6371008.771415, LatLon=<class 'pygeodesy.sphericalTrigonometry.LatLon'>, **options)

 

Locate the point on a path or polygon closest to a reference point.

Distances are approximated using function pygeodesy.equirectangular_, subject to the supplied options.

Arguments:
  • point - The reference point (LatLon).
  • points - The path or 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 pygeodesy.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 pygeodesy.equirectangular_ distance between the closest and the given point converted to meter, same units as radius. The angle from the given point to the closest is in compass degrees360, like function pygeodesy.compassAngle. The height is the (interpolated) height at the closest point.
Raises:

perimeterOf (points, closed=False, radius=6371008.771415, 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) or None.
  • wrap - Wrap and unroll longitudes (bool).
Returns:
Polygon perimeter (meter, same units as radius or radians if radius is None).
Raises:
  • PointsError - Insufficient number of points.
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid radius.

Note: Distances are based on function pygeodesy.vincentys_.

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

triangle7 (latA, lonA, latB, lonB, latC, lonC, radius=6371008.771415, excess=<function excessAbc at 0x7f94907d7dd0>, wrap=False)

 

Compute the angles, sides, and area of a (spherical) triangle.

Arguments:
  • latA - First corner latitude (degrees).
  • lonA - First corner longitude (degrees).
  • latB - Second corner latitude (degrees).
  • lonB - Second corner longitude (degrees).
  • latC - Third corner latitude (degrees).
  • lonC - Third corner longitude (degrees).
  • radius - Mean earth radius, ellipsoid or datum (meter, Ellipsoid, Ellipsoid2, Datum or a_f2Tuple) or None.
  • excess - Spherical excess callable (excessAbc, excessGirard or excessLHuilier).
  • wrap - Wrap and pygeodesy.unroll180 longitudes (bool).
Returns:
A Triangle7Tuple(A, a, B, b, C, c, area) with spherical angles A, B and C, angular sides a, b and c all in degrees and area in square meter or units of radius squared or if radius is None, a Triangle8Tuple(A, a, B, b, C, c, D, E) all in radians with spherical excess E as the unit area in radians.

triangle8_ (phiA, lamA, phiB, lamB, phiC, lamC, excess=<function excessAbc at 0x7f94907d7dd0>, wrap=False)

 

Compute the angles, sides, spherical deficit and spherical excess of a (spherical) triangle.

Arguments:
  • phiA - First corner latitude (radians).
  • lamA - First corner longitude (radians).
  • phiB - Second corner latitude (radians).
  • lamB - Second corner longitude (radians).
  • phiC - Third corner latitude (radians).
  • lamC - Third corner longitude (radians).
  • excess - Spherical excess callable (excessAbc, excessGirard or excessLHuilier).
  • wrap - Wrap and pygeodesy.unrollPI longitudes (bool).
Returns:
A Triangle8Tuple(A, a, B, b, C, c, D, E) with spherical angles A, B and C, angular sides a, b and c, spherical deficit D and spherical excess E, all in radians.