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-2024 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 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 or about 6,371,009 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

To change the ellipsoid model used by the Vincenty formulae use:

    >>> 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: 25.04.21

Classes
| VincentyError Error raised by 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 New point on an (oblate) ellipsoidal earth model, using the formulae devised by Thaddeus Vincenty (1975) to compute geodesic distances, bearings (azimuths), etc.

Functions
intersecant2(center, circle, point, other, **exact_height_wrap_tol) Compute the intersections of a circle and a geodesic given as two points or as a point and (forward) bearing. |
ispolar(points, wrap=False) Check whether a polygon encloses a pole. |
areaOf(points, **datum_wrap) DEPRECATED, use function ellipsoidalExact.areaOf or ellipsoidalKarney.areaOf. |
intersection3(start1, end1, start2, end2, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalVincenty.LatLon'>, **LatLon_kwds) Iteratively compute the intersection point of two lines, each defined by two (ellipsoidal) points or by an (ellipsoidal) start point and an (initial) bearing from North. |
intersections2(center1, radius1, center2, radius2, height=None, wrap=False, 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_datum_wrap) DEPRECATED, use function ellipsoidalExact.perimeterOf or ellipsoidalKarney.perimeterOf. |

Variables
| __all__ = `_ALL_LAZY.ellipsoidalVincenty`

Function Details

### intersecant2 (center, circle, point, other, **exact_height_wrap_tol) |
Compute the intersections of a circle and a geodesic given as two points or as a point and (forward) bearing. Arguments: `center` - Center of the circle (`LatLon`). `circle` - Radius of the circle (`meter`, conventionally) or a point on the circle (`LatLon`, as `center`). `point` - A point of the geodesic (`LatLon`, as `center`). `other` - An other point of the geodesic (`LatLon`, as `center`) or the (forward) bearing at the `point` (compass `degrees`). `exact_height_wrap_tol` - Optional keyword arguments `exact=False`, `height=None`, `wrap=False` and `tol`, see method intersecant2. Raises: `NotImplementedError` - Method `intersecant2` not available. `TypeError` - If `center`, `point` or `circle` or `other` points not ellipsoidal or not compatible with `center`. See Also: Method `LatLon.intersecant2` of class ellipsoidalExact.LatLon, ellipsoidalKarney.LatLon or ellipsoidalVincenty.LatLon.

### ispolar (points, wrap=False) |
Check whether a polygon encloses a pole. Arguments: `points` - The polygon points (`LatLon`[]). `wrap` - If `True`, wrap or normalize and unroll the `points` (`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_wrap) |
DEPRECATED, use function ellipsoidalExact.areaOf or ellipsoidalKarney.areaOf. Decorators: `@deprecated_function`

### intersection3 (start1, end1, start2, end2, height=None, wrap=False, equidistant=None, tol=0.001, LatLon=<class 'pygeodesy.ellipsoidalVincenty.LatLon'>, **LatLon_kwds) |
Iteratively compute the intersection point of two lines, each defined by two (ellipsoidal) points or by an (ellipsoidal) start point and an (initial) bearing from North. Arguments: `start1` - Start point of the first line (LatLon). `end1` - End point of the first line (LatLon) or the initial bearing at the first point (compass `degrees360`). `start2` - Start point of the second line (LatLon). `end2` - End point of the second line (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` - If `True`, wrap or normalize and unroll the `start2` and `end*` points (`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 lines or no convergence for the given `tol`. `TypeError` - Invalid or non-ellipsoidal `start1`, `end1`, `start2` or `end2` or invalid `equidistant`. Note: For each line 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=False, 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` - If `True`, wrap or normalize and unroll `center2` (`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` - If `True`, wrap or normalize and unroll both `point1` and `point2` (`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_datum_wrap) |
DEPRECATED, use function ellipsoidalExact.perimeterOf or ellipsoidalKarney.perimeterOf. Decorators: `@deprecated_function`