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

Module ellipsoidalVincenty

Ellipsoidal, Vincenty-based geodesy.

Thaddeus Vincenty's geodetic (lat-/longitude) LatLon, geocentric (ECEF) Cartesian and VincentyError classes and functions areaOf, intersections2, nearestOn and perimeterOf.

Pure Python implementation of geodesy tools for ellipsoidal earth models, transcoded from JavaScript originals by (C) Chris Veness 2005-2016 and published under the same MIT Licence**, see Vincenty geodesics. More at geographiclib and GeoPy.

Calculate geodesic distance between two points using the Vincenty formulae and one of several ellipsoidal earth models. The default model is WGS-84, the most accurate and widely used globally-applicable model for the earth ellipsoid.

Other ellipsoids offering a better fit to the local geoid include Airy (1830) in the UK, Clarke (1880) in Africa, International 1924 in much of Europe, and GRS-67 in South America. North America (NAD83) and Australia (GDA) use GRS-80, which is equivalent to the WGS-84 model.

Great-circle distance uses a spherical model of the earth with the mean earth radius defined by the International Union of Geodesy and Geophysics (IUGG) as (2 * a + b) / 3 = 6371008.7714150598 meter or approx. 6371009 meter (for WGS-84, resulting in an error of up to about 0.5%).

Here's an example usage of ellipsoidalVincenty:

>>> from pygeodesy.ellipsoidalVincenty import LatLon
>>> Newport_RI = LatLon(41.49008, -71.312796)
>>> Cleveland_OH = LatLon(41.499498, -81.695391)
>>> Newport_RI.distanceTo(Cleveland_OH)
866,455.4329158525  # meter

You can change the ellipsoid model used by the Vincenty formulae as follows:

>>> from pygeodesy import Datums
>>> from pygeodesy.ellipsoidalVincenty import LatLon
>>> p = LatLon(0, 0, datum=Datums.OSGB36)

or by converting to anothor datum:

>>> p = p.toDatum(Datums.OSGB36)

Version: 22.04.27

Classes
  VincentyError
Error raised from Vincenty's direct and inverse methods for coincident points or lack of convergence.
  Cartesian
Extended to convert geocentric, Cartesian points to Vincenty-based, ellipsoidal, geodetic LatLon.
  LatLon
Using the formulae devised by Thaddeus Vincenty (1975) for an (oblate) ellipsoidal model of the earth to compute the geodesic distance and bearings between two given points or the destination point given an start point and (initial) bearing.
Functions
 
ispolar(points, wrap=False)
Check whether a polygon encloses a pole.
 
areaOf(points, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=True)
DEPRECATED, use function ellipsoidalExact.areaOf or ellipsoidalKarney.areaOf.
 
intersection3(start1, end1, start2, end2, height=None, wrap=True, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalVincenty.LatLon'>, **LatLon_kwds)
Interatively compute the intersection point of two paths, each defined by two (ellipsoidal) points or by an (ellipsoidal) start point and a bearing from North.
 
intersections2(center1, radius1, center2, radius2, height=None, wrap=True, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalVincenty.LatLon'>, **LatLon_kwds)
Iteratively compute the intersection points of two circles, each defined by an (ellipsoidal) center point and a radius.
 
nearestOn(point, point1, point2, within=True, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalVincenty.LatLon'>, **LatLon_kwds)
Iteratively locate the closest point on the geodesic between two other (ellipsoidal) points.
 
perimeterOf(points, closed=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=True)
DEPRECATED, use function ellipsoidalExact.perimeterOf or ellipsoidalKarney.perimeterOf.
Variables
  __all__ = _ALL_LAZY.ellipsoidalVincenty
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.

areaOf (points, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=True)

 

DEPRECATED, use function ellipsoidalExact.areaOf or ellipsoidalKarney.areaOf.

Decorators:
  • @deprecated_function

intersection3 (start1, end1, start2, end2, height=None, wrap=True, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalVincenty.LatLon'>, **LatLon_kwds)

 

Interatively compute the intersection point of two paths, each defined by two (ellipsoidal) points or by an (ellipsoidal) start point and a 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 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 point (compass degrees360).
  • height - Optional height at the intersection (meter, conventionally) or None for the mean height.
  • wrap - Wrap and unroll longitudes (bool).
  • equidistant - An azimuthal equidistant projection (class or function pygeodesy.equidistant) or None for the preferred start1.Equidistant.
  • tol - Tolerance for convergence and for skew line distance and length (meter, conventionally).
  • LatLon - Optional class to return the intersection points (LatLon) or None.
  • LatLon_kwds - Optional, additional LatLon keyword arguments, ignored if LatLon is None.
Returns:
An Intersection3Tuple(point, outside1, outside2) with point a LatLon or if LatLon is None, a LatLon4Tuple(lat, lon, height, datum).
Raises:
  • IntersectionError - Skew, colinear, parallel or otherwise non-intersecting paths or no convergence for the given tol.
  • TypeError - Invalid or non-ellipsoidal start1, end1, start2 or end2 or invalid equidistant.

Note: For each path specified with an initial bearing, a pseudo-end point is computed as the destination along that bearing at about 1.5 times the distance from the start point to an initial gu-/estimate of the intersection point (and between 1/8 and 3/8 of the authalic earth perimeter).

See Also: The ellipsoidal case and Karney's paper, pp 20-21, section 14. MARITIME BOUNDARIES for more details about the iteration algorithm.

intersections2 (center1, radius1, center2, radius2, height=None, wrap=True, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalVincenty.LatLon'>, **LatLon_kwds)

 

Iteratively compute the intersection points of two circles, each defined by an (ellipsoidal) center point and a radius.

Arguments:
  • center1 - Center of the first circle (LatLon).
  • radius1 - Radius of the first circle (meter, conventionally).
  • center2 - Center of the second circle (LatLon).
  • radius2 - Radius of the second circle (meter, same units as radius1).
  • 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).
  • equidistant - An azimuthal equidistant projection (class or function pygeodesy.equidistant) or None for the preferred center1.Equidistant.
  • tol - Convergence tolerance (meter, same units as radius1 and radius2).
  • 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 LatLon4Tuple(lat, lon, height, datum) if LatLon is None. For abutting circles, both points are the same instance, aka the radical center.
Raises:
  • IntersectionError - Concentric, antipodal, invalid or non-intersecting circles or no convergence for the tol.
  • TypeError - Invalid or non-ellipsoidal center1 or center2 or invalid equidistant.
  • UnitError - Invalid radius1, radius2 or height.

See Also: The ellipsoidal case, Karney's paper, pp 20-21, section 14. MARITIME BOUNDARIES, circle-circle and sphere-sphere intersections.

nearestOn (point, point1, point2, within=True, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalVincenty.LatLon'>, **LatLon_kwds)

 

Iteratively locate the closest point on the geodesic between two other (ellipsoidal) points.

Arguments:
  • point - Reference point (LatLon).
  • point1 - Start point of the geodesic (LatLon).
  • point2 - End point of the geodesic (LatLon).
  • within - If True return the closest point between point1 and point2, otherwise the closest point elsewhere on the geodesic (bool).
  • height - Optional height for the closest point (meter, conventionally) or None or False for the interpolated height. If False, the closest takes the heights of the points into account.
  • wrap - Wrap and unroll longitudes (bool).
  • equidistant - An azimuthal equidistant projection (class or function pygeodesy.equidistant) or None for the preferred point.Equidistant.
  • tol - Convergence tolerance (meter).
  • LatLon - Optional class to return the closest point (LatLon) or None.
  • LatLon_kwds - Optional, additional LatLon keyword arguments, ignored if LatLon is None.
Returns:
Closest point, a LatLon instance or if LatLon is None, a LatLon4Tuple(lat, lon, height, datum).
Raises:
  • ImportError - Package geographiclib not installed or not found, but only if equidistant=EquidistantKarney.
  • TypeError - Invalid or non-ellipsoidal point, point1 or point2 or invalid equidistant.
  • ValueError - No convergence for the tol.

See Also: The ellipsoidal case and Karney's paper, pp 20-21, section 14. MARITIME BOUNDARIES for more details about the iteration algorithm.

perimeterOf (points, closed=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=True)

 

DEPRECATED, use function ellipsoidalExact.perimeterOf or ellipsoidalKarney.perimeterOf.

Decorators:
  • @deprecated_function