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)
|
|
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.
|
|
|
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. |
|
|
|
|
|
|
|
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. |
|
|
|
|
|
|
|
__all__ = _ALL_LAZY.ellipsoidalVincenty
|
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.
|
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 pointsTypeError - Some points are not LatLon or
don't have bearingTo2, initialBearingTo
and finalBearingTo methods.
|
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.
|
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.
|