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

# Module ellipsoidalVincenty

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

Pure Python implementation of geodesy tools for ellipsoidal earth models, transcribed 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.convertDatum(Datums.OSGB36)

Version: 20.09.22

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) with an 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. |
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) Locate the closest point on the arc between two other points. |
perimeterOf(points, closed=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=True) DEPRECATED, use function `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.

### 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`). `center2` - Center of the second circle (LatLon). `radius2` - Radius of the second circle (`meter`). `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`). `equidistant` - An azimuthal equidistant projection class (EquidistantKarney or Equidistant) or `None`. `tol` - Convergence tolerance (`meter`). `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 LatLon4Tuple`(lat, lon, height, datum)` if `LatLon` is `None`. For abutting circles, the intersection points are the same instance. 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) |
Locate the closest point on the arc between two other points. Arguments: `point` - Reference point (`LatLon`). `point1` - Start point of the arc (`LatLon`). `point2` - End point of the arc (`LatLon`). `within` - If `True` return the closest point between `point1` and `point2`, otherwise the closest point elsewhere on the arc (`bool`). `height` - Optional height for the closest point (`meter`) or `None`. `wrap` - Wrap and unroll longitudes (`bool`). `equidistant` - An azimuthal equidistant projection class (Equidistant or EquidistantKarney), function azimuthal.equidistant will be invoked if left unspecified. `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=None`. Returns: Closest point (`LatLon`). Raises: `ImportError` - Package geographiclib not installed or not found. `TypeError` - Invalid or non-ellipsoidal `point`, `point1` or `point2` or invalid `equidistant`.