Home       Trees       Indices       Help   
PyGeodesy
Package pygeodesy :: Module formy
[frames] | no frames]

Module formy

Formulary of basic geodesy functions and approximations.

Version: 24.10.14

Classes
  Radical2Tuple
2-Tuple (ratio, xline) of the radical ratio and radical xline, both scalar and 0.0 <= ratio <= 1.0
Functions
 
antipode(lat, lon, **name)
Return the antipode, the point diametrically opposite to a given point in degrees.
 
antipode_(phi, lam, **name)
Return the antipode, the point diametrically opposite to a given point in radians.
 
bearing(lat1, lon1, lat2, lon2, **final_wrap)
Compute the initial or final bearing (forward or reverse azimuth) between two (spherical) points.
 
bearing_(phi1, lam1, phi2, lam2, final=False, wrap=False)
Compute the initial or final bearing (forward or reverse azimuth) between two (spherical) points.
 
compassAngle(lat1, lon1, lat2, lon2, adjust=True, wrap=False)
Return the angle from North for the direction vector (lon2 - lon1, lat2 - lat1) between two points.
 
cosineAndoyerLambert(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=False)
Compute the distance between two (ellipsoidal) points using the Andoyer-Lambert correction of the Law of Cosines formula.
 
cosineAndoyerLambert_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)
Compute the angular distance between two (ellipsoidal) points using the Andoyer-Lambert correction of the Law of Cosines formula.
 
cosineForsytheAndoyerLambert(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=False)
Compute the distance between two (ellipsoidal) points using the Forsythe-Andoyer-Lambert correction of the Law of Cosines formula.
 
cosineForsytheAndoyerLambert_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)
Compute the angular distance between two (ellipsoidal) points using the Forsythe-Andoyer-Lambert correction of the Law of Cosines formula.
 
cosineLaw(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)
Compute the distance between two points using the spherical Law of Cosines formula.
 
cosineLaw_(phi2, phi1, lam21)
Compute the angular distance between two points using the spherical Law of Cosines formula.
 
equirectangular(lat1, lon1, lat2, lon2, radius=6371008.771415, **adjust_limit_wrap)
Compute the distance between two points using the Equirectangular Approximation / Projection.
 
equirectangular4(lat1, lon1, lat2, lon2, adjust=True, limit=45, wrap=False)
Compute the distance between two points using the Equirectangular Approximation / Projection.
 
euclidean(lat1, lon1, lat2, lon2, radius=6371008.771415, adjust=True, wrap=False)
Approximate the Euclidean distance between two (spherical) points.
 
euclidean_(phi2, phi1, lam21, adjust=True)
Approximate the angular Euclidean distance between two (spherical) points.
 
excessAbc_(A, b, c)
Compute the spherical excess E of a (spherical) triangle from two sides and the included (small) angle.
 
excessCagnoli_(a, b, c)
Compute the spherical excess E of a (spherical) triangle using Cagnoli's (D.34) formula.
 
excessGirard_(A, B, C)
Compute the spherical excess E of a (spherical) triangle using Girard's formula.
 
excessLHuilier_(a, b, c)
Compute the spherical excess E of a (spherical) triangle using L'Huilier's's Theorem.
 
excessKarney(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)
Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method.
 
excessKarney_(phi2, phi1, lam21)
Compute the spherical excess E of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method.
 
excessQuad(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)
Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator.
 
excessQuad_(phi2, phi1, lam21)
Compute the spherical excess E of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator.
 
flatLocal(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True, wrap=False)
Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.
 
hubeny(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True, wrap=False)
Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.
 
flatLocal_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True)
Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.
 
hubeny_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True)
Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.
 
flatPolar(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)
Compute the distance between two (spherical) points using the polar coordinate flat-Earth formula.
 
flatPolar_(phi2, phi1, lam21)
Compute the angular distance between two (spherical) points using the polar coordinate flat-Earth formula.
 
hartzell(pov, los=False, earth=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., **name_LatLon_and_kwds)
Compute the intersection of the earth's surface and a Line-Of-Sight from a Point-Of-View in space.
 
haversine(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)
Compute the distance between two (spherical) points using the Haversine formula.
 
haversine_(phi2, phi1, lam21)
Compute the angular distance between two (spherical) points using the Haversine formula.
 
heightOf(angle, distance, radius=6371008.771415)
Determine the height above the (spherical) earth' surface after traveling along a straight line at a given tilt.
 
heightOrthometric(h_ll, N)
Get the orthometric height H, the height above the geoid, earth surface.
 
horizon(height, radius=6371008.771415, refraction=False)
Determine the distance to the horizon from a given altitude above the (spherical) earth.
 
intersection2(lat1, lon1, bearing1, lat2, lon2, bearing2, datum=None, wrap=False, small=100000.0)
Conveniently compute the intersection of two lines each defined by a (geodetic) point and a bearing from North, using either ...
 
intersections2(lat1, lon1, radius1, lat2, lon2, radius2, datum=None, wrap=False, small=100000.0)
Conveniently compute the intersections of two circles each defined by a (geodetic) center point and a radius, using either ...
 
isantipode(lat1, lon1, lat2, lon2, eps=2.220446049250313e-16)
Check whether two points are antipodal, on diametrically opposite sides of the earth.
 
isantipode_(phi1, lam1, phi2, lam2, eps=2.220446049250313e-16)
Check whether two points are antipodal, on diametrically opposite sides of the earth.
 
isnormal(lat, lon, eps=0)
Check whether lat and lon are within their respective normal range in degrees.
 
isnormal_(phi, lam, eps=0)
Check whether phi and lam are within their respective normal range in radians.
 
latlon2n_xyz(lat, lon, **name)
Convert lat-, longitude to n-vector (normal to the earth's surface) X, Y and Z components.
 
normal(lat, lon, **name)
Normalize a lat- and longitude pair in degrees.
 
normal_(phi, lam, **name)
Normalize a lat- and longitude pair in radians.
 
n_xyz2latlon(x, y, z, **name)
Convert n-vector components to lat- and longitude in degrees.
 
n_xyz2philam(x, y, z, **name)
Convert n-vector components to lat- and longitude in radians.
 
opposing(bearing1, bearing2, margin=90.0)
Compare the direction of two bearings given in degrees.
 
opposing_(radians1, radians2, margin=1.5707963267948966)
Compare the direction of two bearings given in radians.
 
philam2n_xyz(phi, lam, **name)
Convert lat-, longitude to n-vector (normal to the earth's surface) X, Y and Z components.
 
radical2(distance, radius1, radius2, **name)
Compute the radical ratio and radical line of two intersecting circles.
 
thomas(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=False)
Compute the distance between two (ellipsoidal) points using Thomas' formula.
 
thomas_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)
Compute the angular distance between two (ellipsoidal) points using Thomas' formula.
 
vincentys(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)
Compute the distance between two (spherical) points using Vincenty's spherical formula.
 
vincentys_(phi2, phi1, lam21)
Compute the angular distance between two (spherical) points using Vincenty's spherical formula.
Variables
  __all__ = _ALL_LAZY.formy
Function Details

antipode (lat, lon, **name)

 

Return the antipode, the point diametrically opposite to a given point in degrees.

Arguments:
  • lat - Latitude (degrees).
  • lon - Longitude (degrees).
  • name - Optional name=NN (str).
Returns:
A LatLon2Tuple(lat, lon).

See Also: Functions antipode_ and normal and Geosphere.

antipode_ (phi, lam, **name)

 

Return the antipode, the point diametrically opposite to a given point in radians.

Arguments:
  • phi - Latitude (radians).
  • lam - Longitude (radians).
  • name - Optional name=NN (str).
Returns:
A PhiLam2Tuple(phi, lam).

See Also: Functions antipode and normal_ and Geosphere.

bearing (lat1, lon1, lat2, lon2, **final_wrap)

 

Compute the initial or final bearing (forward or reverse azimuth) between two (spherical) points.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • final_wrap - Optional keyword arguments for function pygeodesy.bearing_.
Returns:
Initial or final bearing (compass degrees360) or zero if both points coincide.

bearing_ (phi1, lam1, phi2, lam2, final=False, wrap=False)

 

Compute the initial or final bearing (forward or reverse azimuth) between two (spherical) points.

Arguments:
  • phi1 - Start latitude (radians).
  • lam1 - Start longitude (radians).
  • phi2 - End latitude (radians).
  • lam2 - End longitude (radians).
  • final - If True, return the final, otherwise the initial bearing (bool).
  • wrap - If True, wrap or normalize and unroll phi2 and lam2 (bool).
Returns:
Initial or final bearing (compass radiansPI2) or zero if both are coincident.

See Also: Bearing, Course between two points and Bearing Between Two Points.

compassAngle (lat1, lon1, lat2, lon2, adjust=True, wrap=False)

 

Return the angle from North for the direction vector (lon2 - lon1, lat2 - lat1) between two points.

Suitable only for short, not near-polar vectors up to a few hundred Km or Miles. Use function pygeodesy.bearing for longer vectors.

Arguments:
  • lat1 - From latitude (degrees).
  • lon1 - From longitude (degrees).
  • lat2 - To latitude (degrees).
  • lon2 - To longitude (degrees).
  • adjust - Adjust the longitudinal delta by the cosine of the mean latitude (bool).
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Compass angle from North (degrees360).

Note: Courtesy of Martin Schultz.

See Also: Local, flat earth approximation.

cosineAndoyerLambert (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=False)

 

Compute the distance between two (ellipsoidal) points using the Andoyer-Lambert correction of the Law of Cosines formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • datum - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as the datum's ellipsoid axes or radians if datum is None).
Raises:
  • TypeError - Invalid datum.

See Also: Functions cosineAndoyerLambert_, cosineForsytheAndoyerLambert, cosineLaw, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine, thomas and vincentys and method Ellipsoid.distance2.

cosineAndoyerLambert_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)

 

Compute the angular distance between two (ellipsoidal) points using the Andoyer-Lambert correction of the Law of Cosines formula.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
  • datum - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
Returns:
Angular distance (radians).
Raises:
  • TypeError - Invalid datum.

See Also: Functions cosineAndoyerLambert, cosineForsytheAndoyerLambert_, cosineLaw_, euclidean_, flatLocal_/hubeny_, flatPolar_, haversine_, thomas_ and vincentys_ and Geodesy-PHP.

cosineForsytheAndoyerLambert (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=False)

 

Compute the distance between two (ellipsoidal) points using the Forsythe-Andoyer-Lambert correction of the Law of Cosines formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • datum - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as the datum's ellipsoid axes or radians if datum is None).
Raises:
  • TypeError - Invalid datum.

See Also: Functions cosineForsytheAndoyerLambert_, cosineAndoyerLambert, cosineLaw, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine, thomas and vincentys and method Ellipsoid.distance2.

cosineForsytheAndoyerLambert_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)

 

Compute the angular distance between two (ellipsoidal) points using the Forsythe-Andoyer-Lambert correction of the Law of Cosines formula.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
  • datum - Datum (Datum) or ellipsoid to use (Ellipsoid, Ellipsoid2 or a_f2Tuple).
Returns:
Angular distance (radians).
Raises:
  • TypeError - Invalid datum.

See Also: Functions cosineForsytheAndoyerLambert, cosineAndoyerLambert_, cosineLaw_, euclidean_, flatLocal_/hubeny_, flatPolar_, haversine_, thomas_ and vincentys_ and Geodesy-PHP.

cosineLaw (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the distance between two points using the spherical Law of Cosines formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and lat2 and lon2 (bool).
Returns:
Distance (meter, same units as radius or the ellipsoid or datum axes).
Raises:
  • TypeError - Invalid radius.

See Also: Functions cosineLaw_, cosineAndoyerLambert, cosineForsytheAndoyerLambert, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine, thomas and vincentys and method Ellipsoid.distance2.

Note: See note at function vincentys_.

cosineLaw_ (phi2, phi1, lam21)

 

Compute the angular distance between two points using the spherical Law of Cosines formula.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
Returns:
Angular distance (radians).

See Also: Functions cosineLaw, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, euclidean_, flatLocal_/hubeny_, flatPolar_, haversine_, thomas_ and vincentys_.

Note: See note at function vincentys_.

equirectangular (lat1, lon1, lat2, lon2, radius=6371008.771415, **adjust_limit_wrap)

 

Compute the distance between two points using the Equirectangular Approximation / Projection.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple).
  • adjust_limit_wrap - Optional keyword arguments for function equirectangular4.
Returns:
Distance (meter, same units as radius or the ellipsoid or datum axes).
Raises:
  • TypeError - Invalid radius.

See Also: Function equirectangular4 for more details, the available options, errors, restrictions and other, approximate or accurate distance functions.

equirectangular4 (lat1, lon1, lat2, lon2, adjust=True, limit=45, wrap=False)

 

Compute the distance between two points using the Equirectangular Approximation / Projection.

This approximation is valid for short distance of several hundred Km or Miles, see the limit keyword argument and LimitError.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
  • limit - Optional limit for lat- and longitudinal deltas (degrees) or None or 0 for unlimited.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
A Distance4Tuple(distance2, delta_lat, delta_lon, unroll_lon2) in degrees squared.
Raises:
  • LimitError - If the lat- and/or longitudinal delta exceeds the -limit..limit range and limiterrors is True.

See Also: Local, flat earth approximation, functions equirectangular, cosineAndoyerLambert, cosineForsytheAndoyerLambert, cosineLaw, euclidean, flatLocal/hubeny, flatPolar, haversine, thomas and vincentys and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

euclidean (lat1, lon1, lat2, lon2, radius=6371008.771415, adjust=True, wrap=False)

 

Approximate the Euclidean distance between two (spherical) points.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • adjust - Adjust the longitudinal delta by the cosine of the mean latitude (bool).
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as radius or the ellipsoid or datum axes).
Raises:
  • TypeError - Invalid radius.

See Also: Distance between two (spherical) points, functions euclid, euclidean_, cosineAndoyerLambert, cosineForsytheAndoyerLambert, cosineLaw, equirectangular, flatLocal/hubeny, flatPolar, haversine, thomas and vincentys and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

euclidean_ (phi2, phi1, lam21, adjust=True)

 

Approximate the angular Euclidean distance between two (spherical) points.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
  • adjust - Adjust the longitudinal delta by the cosine of the mean latitude (bool).
Returns:
Angular distance (radians).

See Also: Functions euclid, euclidean, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, flatLocal_/hubeny_, flatPolar_, haversine_, thomas_ and vincentys_.

excessAbc_ (A, b, c)

 

Compute the spherical excess E of a (spherical) triangle from two sides and the included (small) angle.

Arguments:
  • A - An interior triangle angle (radians).
  • b - Frist adjacent triangle side (radians).
  • c - Second adjacent triangle side (radians).
Returns:
Spherical excess (radians).
Raises:

See Also: Functions excessGirard_, excessLHuilier_ and Spherical trigonometry.

excessCagnoli_ (a, b, c)

 

Compute the spherical excess E of a (spherical) triangle using Cagnoli's (D.34) formula.

Arguments:
  • a - First triangle side (radians).
  • b - Second triangle side (radians).
  • c - Third triangle side (radians).
Returns:
Spherical excess (radians).
Raises:

See Also: Function excessLHuilier_ and Spherical trigonometry.

excessGirard_ (A, B, C)

 

Compute the spherical excess E of a (spherical) triangle using Girard's formula.

Arguments:
  • A - First interior triangle angle (radians).
  • B - Second interior triangle angle (radians).
  • C - Third interior triangle angle (radians).
Returns:
Spherical excess (radians).
Raises:

See Also: Function excessLHuilier_ and Spherical trigonometry.

excessLHuilier_ (a, b, c)

 

Compute the spherical excess E of a (spherical) triangle using L'Huilier's's Theorem.

Arguments:
  • a - First triangle side (radians).
  • b - Second triangle side (radians).
  • c - Third triangle side (radians).
Returns:
Spherical excess (radians).
Raises:

See Also: Function excessCagnoli_, excessGirard_ and Spherical trigonometry.

excessKarney (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or None.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Surface area, signed (square meter or the same units as radius squared) or the spherical excess (radians) if radius=0 or None.
Raises:
  • TypeError - Invalid radius.
  • UnitError - Invalid lat2 or lat1.
  • ValueError - Semi-circular longitudinal delta.

See Also: Functions excessKarney_ and excessQuad.

excessKarney_ (phi2, phi1, lam21)

 

Compute the spherical excess E of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
Returns:
Spherical excess, signed (radians).
Raises:
  • ValueError - Semi-circular longitudinal delta lam21.

See Also: Function excessKarney and Area of a spherical polygon.

excessQuad (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or None.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Surface area, signed (square meter or the same units as radius squared) or the spherical excess (radians) if radius=0 or None.
Raises:
  • TypeError - Invalid radius.
  • UnitError - Invalid lat2 or lat1.

See Also: Function excessQuad_ and excessKarney.

excessQuad_ (phi2, phi1, lam21)

 

Compute the spherical excess E of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
Returns:
Spherical excess, signed (radians).

See Also: Function excessQuad and Spherical trigonometry.

flatLocal (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True, wrap=False)

 

Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • datum - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • scaled - Scale prime_vertical by cos(phi) (bool), see method pygeodesy.Ellipsoid.roc2_.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as the datum's ellipsoid axes).
Raises:
  • TypeError - Invalid datum.

Note: The meridional and prime_vertical radii of curvature are taken and scaled at the mean of both latitude.

See Also: Functions flatLocal_ or hubeny_, cosineLaw, flatPolar, cosineAndoyerLambert, cosineForsytheAndoyerLambert, equirectangular, euclidean, haversine, thomas, vincentys, method Ellipsoid.distance2 and local, flat earth approximation.

hubeny (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True, wrap=False)

 

Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • datum - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • scaled - Scale prime_vertical by cos(phi) (bool), see method pygeodesy.Ellipsoid.roc2_.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as the datum's ellipsoid axes).
Raises:
  • TypeError - Invalid datum.

Note: The meridional and prime_vertical radii of curvature are taken and scaled at the mean of both latitude.

See Also: Functions flatLocal_ or hubeny_, cosineLaw, flatPolar, cosineAndoyerLambert, cosineForsytheAndoyerLambert, equirectangular, euclidean, haversine, thomas, vincentys, method Ellipsoid.distance2 and local, flat earth approximation.

flatLocal_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True)

 

Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.

Arguments:
Returns:
Angular distance (radians).
Raises:
  • TypeError - Invalid datum.

Note: The meridional and prime_vertical radii of curvature are taken and scaled at the mean of both latitude.

See Also: Functions flatLocal or hubeny, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, flatPolar_, euclidean_, haversine_, thomas_ and vincentys_ and local, flat earth approximation.

hubeny_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True)

 

Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.

Arguments:
Returns:
Angular distance (radians).
Raises:
  • TypeError - Invalid datum.

Note: The meridional and prime_vertical radii of curvature are taken and scaled at the mean of both latitude.

See Also: Functions flatLocal or hubeny, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, flatPolar_, euclidean_, haversine_, thomas_ and vincentys_ and local, flat earth approximation.

flatPolar (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the distance between two (spherical) points using the polar coordinate flat-Earth formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and lat2 and lon2 (bool).
Returns:
Distance (meter, same units as radius or the ellipsoid or datum axes).
Raises:
  • TypeError - Invalid radius.

See Also: Functions flatPolar_, cosineAndoyerLambert, cosineForsytheAndoyerLambert,cosineLaw, flatLocal/hubeny, equirectangular, euclidean, haversine, thomas and vincentys.

flatPolar_ (phi2, phi1, lam21)

 

Compute the angular distance between two (spherical) points using the polar coordinate flat-Earth formula.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
Returns:
Angular distance (radians).

See Also: Functions flatPolar, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, euclidean_, flatLocal_/hubeny_, haversine_, thomas_ and vincentys_.

hartzell (pov, los=False, earth=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., **name_LatLon_and_kwds)

 

Compute the intersection of the earth's surface and a Line-Of-Sight from a Point-Of-View in space.

Arguments:
  • pov - Point-Of-View outside the earth (LatLon, Cartesian, Ecef9Tuple or Vector3d).
  • los - Line-Of-Sight, direction to earth (Los, Vector3d), True for the normal, plumb onto the surface or False or None to point to the center of the earth.
  • earth - The earth model (Datum, Ellipsoid, Ellipsoid2, a_f2Tuple or a scalar earth radius in meter).
  • name_LatLon_and_kwds - Optional, overriding name="hartzell" (str), class LatLon=None to return the intersection plus additional LatLon keyword arguments, include the datum if different and to convert from earth.
Returns:
The intersection (Vector3d, pov's cartesian type or the given LatLon instance) with attribute height set to the distance to the pov.
Raises:
  • IntersectionError - Invalid pov or pov inside the earth or invalid los or los points outside or away from the earth.
  • TypeError - Invalid earth, ellipsoid or datum.

See Also: Class Los, functions tyr3d and hartzell4 and methods Ellipsoid.hartzell4 and any Cartesian.hartzell and LatLon.hartzell.

haversine (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the distance between two (spherical) points using the Haversine formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as radius).
Raises:
  • TypeError - Invalid radius.

See Also: Distance between two (spherical) points, functions cosineLaw, cosineAndoyerLambert, cosineForsytheAndoyerLambert, equirectangular, euclidean, flatLocal/hubeny, flatPolar, thomas and vincentys and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

Note: See note at function vincentys_.

haversine_ (phi2, phi1, lam21)

 

Compute the angular distance between two (spherical) points using the Haversine formula.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
Returns:
Angular distance (radians).

See Also: Functions haversine, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, euclidean_, flatLocal_/hubeny_, flatPolar_, thomas_ and vincentys_.

Note: See note at function vincentys_.

heightOf (angle, distance, radius=6371008.771415)

 

Determine the height above the (spherical) earth' surface after traveling along a straight line at a given tilt.

Arguments:
  • angle - Tilt angle above horizontal (degrees).
  • distance - Distance along the line (meter or same units as radius).
  • radius - Optional mean earth radius (meter).
Returns:
Height (meter, same units as distance and radius).
Raises:
  • ValueError - Invalid angle, distance or radius.

See Also: MultiDop geog_lib.GeogBeamHt (Shapiro et al. 2009, JTECH and Potvin et al. 2012, JTECH).

heightOrthometric (h_ll, N)

 

Get the orthometric height H, the height above the geoid, earth surface.

Arguments:
  • h_ll - The height above the ellipsoid (meter) or an ellipsoidal location (LatLon with a height or h attribute).
  • N - The geoid height (meter), the height of the geoid above the ellipsoid at the same h_ll location.
Returns:
Orthometric height H = h - N (meter, same units as h and N).

See Also: Ellipsoid, Geoid, and Othometric Heights, page 6 and module pygeodesy.geoids.

horizon (height, radius=6371008.771415, refraction=False)

 

Determine the distance to the horizon from a given altitude above the (spherical) earth.

Arguments:
  • height - Altitude (meter or same units as radius).
  • radius - Optional mean earth radius (meter).
  • refraction - Consider atmospheric refraction (bool).
Returns:
Distance (meter, same units as height and radius).
Raises:
  • ValueError - Invalid height or radius.

See Also: Distance to horizon.

intersection2 (lat1, lon1, bearing1, lat2, lon2, bearing2, datum=None, wrap=False, small=100000.0)

 

Conveniently compute the intersection of two lines each defined by a (geodetic) point and a bearing from North, using either ...

1) vector3d.intersection3d3 for small distances (below 100 Km or about 0.88 degrees) or if no datum is specified, or ...

2) sphericalTrigonometry.intersection for a spherical datum or a scalar datum representing the earth radius, conventionally in meter or ...

3) sphericalNvector.intersection if datum is a negative scalar, (negative) earth radius, conventionally in meter or ...

4) ellipsoidalKarney.intersection3 for an ellipsoidal datum and if Karney's geographiclib is installed, otherwise ...

5) ellipsoidalExact.intersection3, provided datum is ellipsoidal.

Arguments:
  • lat1 - Latitude of the first point (degrees).
  • lon1 - Longitude of the first point (degrees).
  • bearing1 - Bearing at the first point (compass degrees).
  • lat2 - Latitude of the second point (degrees).
  • lon2 - Longitude of the second point (degrees).
  • bearing2 - Bearing at the second point (compass degrees).
  • datum - Optional datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or scalar earth radius (meter, same units as radius1 and radius2) or None.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
  • small - Upper limit for small distances (meter).
Returns:
A LatLon2Tuple(lat, lon) with the lat- and longitude of the intersection point.
Raises:
  • IntersectionError - Ambiguous or infinite intersection or colinear, parallel or otherwise non-intersecting lines.
  • TypeError - Invalid datum.
  • UnitError - Invalid lat1, lon1, bearing1, lat2, lon2 or bearing2.

See Also: Method RhumbLine.intersection2.

Note: The returned intersections may be near-antipodal.

intersections2 (lat1, lon1, radius1, lat2, lon2, radius2, datum=None, wrap=False, small=100000.0)

 

Conveniently compute the intersections of two circles each defined by a (geodetic) center point and a radius, using either ...

1) vector3d.intersections2 for small distances (below 100 Km or about 0.88 degrees) or if no datum is specified, or ...

2) sphericalTrigonometry.intersections2 for a spherical datum or a scalar datum representing the earth radius, conventionally in meter or ...

3) ellipsoidalKarney.intersections2 for an ellipsoidal datum and if Karney's geographiclib is installed, otherwise ...

4) ellipsoidalExact.intersections2, provided datum is ellipsoidal.

Arguments:
  • lat1 - Latitude of the first circle center (degrees).
  • lon1 - Longitude of the first circle center (degrees).
  • radius1 - Radius of the first circle (meter, conventionally).
  • lat2 - Latitude of the second circle center (degrees).
  • lon2 - Longitude of the second circle center (degrees).
  • radius2 - Radius of the second circle (meter, same units as radius1).
  • datum - Optional datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or scalar earth radius (meter, same units as radius1 and radius2) or None.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
  • small - Upper limit for small distances (meter).
Returns:
2-Tuple of the intersection points, each a LatLon2Tuple(lat, lon). For abutting circles, the points are the same instance, aka the radical center.
Raises:
  • IntersectionError - Concentric, antipodal, invalid or non-intersecting circles or no convergence.
  • TypeError - Invalid datum.
  • UnitError - Invalid lat1, lon1, radius1, lat2, lon2 or radius2.

isantipode (lat1, lon1, lat2, lon2, eps=2.220446049250313e-16)

 

Check whether two points are antipodal, on diametrically opposite sides of the earth.

Arguments:
  • lat1 - Latitude of one point (degrees).
  • lon1 - Longitude of one point (degrees).
  • lat2 - Latitude of the other point (degrees).
  • lon2 - Longitude of the other point (degrees).
  • eps - Tolerance for near-equality (degrees).
Returns:
True if points are antipodal within the eps tolerance, False otherwise.

See Also: Functions isantipode_ and antipode.

isantipode_ (phi1, lam1, phi2, lam2, eps=2.220446049250313e-16)

 

Check whether two points are antipodal, on diametrically opposite sides of the earth.

Arguments:
  • phi1 - Latitude of one point (radians).
  • lam1 - Longitude of one point (radians).
  • phi2 - Latitude of the other point (radians).
  • lam2 - Longitude of the other point (radians).
  • eps - Tolerance for near-equality (radians).
Returns:
True if points are antipodal within the eps tolerance, False otherwise.

See Also: Functions isantipode and antipode_.

isnormal (lat, lon, eps=0)

 

Check whether lat and lon are within their respective normal range in degrees.

Arguments:
  • lat - Latitude (degrees).
  • lon - Longitude (degrees).
  • eps - Optional tolerance degrees).
Returns:
True if (abs(lat) + eps) <= 90 and (abs(lon) + eps) <= 180, False othwerwise.

See Also: Functions isnormal_ and normal.

isnormal_ (phi, lam, eps=0)

 

Check whether phi and lam are within their respective normal range in radians.

Arguments:
  • phi - Latitude (radians).
  • lam - Longitude (radians).
  • eps - Optional tolerance radians).
Returns:
True if (abs(phi) + eps) <= PI/2 and (abs(lam) + eps) <= PI, False othwerwise.

See Also: Functions isnormal and normal_.

latlon2n_xyz (lat, lon, **name)

 

Convert lat-, longitude to n-vector (normal to the earth's surface) X, Y and Z components.

Arguments:
  • lat - Latitude (degrees).
  • lon - Longitude (degrees).
  • name - Optional name=NN (str).
Returns:
A Vector3Tuple(x, y, z).

See Also: Function philam2n_xyz.

Note: These are n-vector x, y and z components, NOT geocentric ECEF x, y and z coordinates!

normal (lat, lon, **name)

 

Normalize a lat- and longitude pair in degrees.

Arguments:
  • lat - Latitude (degrees).
  • lon - Longitude (degrees).
  • name - Optional, overriding name="normal" (str).
Returns:
LatLon2Tuple(lat, lon) with abs(lat) <= 90 and abs(lon) <= 180.

See Also: Functions normal_ and isnormal.

normal_ (phi, lam, **name)

 

Normalize a lat- and longitude pair in radians.

Arguments:
  • phi - Latitude (radians).
  • lam - Longitude (radians).
  • name - Optional, overriding name="normal_" (str).
Returns:
PhiLam2Tuple(phi, lam) with abs(phi) <= PI/2 and abs(lam) <= PI.

See Also: Functions normal and isnormal_.

n_xyz2latlon (x, y, z, **name)

 

Convert n-vector components to lat- and longitude in degrees.

Arguments:
  • x - X component (scalar).
  • y - Y component (scalar).
  • z - Z component (scalar).
  • name - Optional name=NN (str).
Returns:
A LatLon2Tuple(lat, lon).

See Also: Function n_xyz2philam.

n_xyz2philam (x, y, z, **name)

 

Convert n-vector components to lat- and longitude in radians.

Arguments:
  • x - X component (scalar).
  • y - Y component (scalar).
  • z - Z component (scalar).
  • name - Optional name=NN (str).
Returns:
A PhiLam2Tuple(phi, lam).

See Also: Function n_xyz2latlon.

opposing (bearing1, bearing2, margin=90.0)

 

Compare the direction of two bearings given in degrees.

Arguments:
  • bearing1 - First bearing (compass degrees).
  • bearing2 - Second bearing (compass degrees).
  • margin - Optional, interior angle bracket (degrees).
Returns:
True if both bearings point in opposite, False if in similar or None if in perpendicular directions.

See Also: Function opposing_.

opposing_ (radians1, radians2, margin=1.5707963267948966)

 

Compare the direction of two bearings given in radians.

Arguments:
  • radians1 - First bearing (radians).
  • radians2 - Second bearing (radians).
  • margin - Optional, interior angle bracket (radians).
Returns:
True if both bearings point in opposite, False if in similar or None if in perpendicular directions.

See Also: Function opposing.

philam2n_xyz (phi, lam, **name)

 

Convert lat-, longitude to n-vector (normal to the earth's surface) X, Y and Z components.

Arguments:
  • phi - Latitude (radians).
  • lam - Longitude (radians).
  • name - Optional name (str).
Returns:
A Vector3Tuple(x, y, z).

See Also: Function latlon2n_xyz.

Note: These are n-vector x, y and z components, NOT geocentric ECEF x, y and z coordinates!

radical2 (distance, radius1, radius2, **name)

 

Compute the radical ratio and radical line of two intersecting circles.

The radical line is perpendicular to the axis thru the centers of the circles at (0, 0) and (distance, 0).

Arguments:
  • distance - Distance between the circle centers (scalar).
  • radius1 - Radius of the first circle (scalar).
  • radius2 - Radius of the second circle (scalar).
  • name - Optional name=NN (str).
Returns:
A Radical2Tuple(ratio, xline) where 0.0 <= ratio <= 1.0 and xline is along the distance.
Raises:

See Also: Circle-Circle Intersection.

thomas (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=False)

 

Compute the distance between two (ellipsoidal) points using Thomas' formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • datum - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as the datum's ellipsoid axes).
Raises:
  • TypeError - Invalid datum.

See Also: Functions thomas_, cosineAndoyerLambert, cosineForsytheAndoyerLambert, cosineLaw, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine, vincentys and method Ellipsoid.distance2.

thomas_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)

 

Compute the angular distance between two (ellipsoidal) points using Thomas' formula.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
  • datum - Datum or ellipsoid to use (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple).
Returns:
Angular distance (radians).
Raises:
  • TypeError - Invalid datum.

See Also: Functions thomas, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, euclidean_, flatLocal_/hubeny_, flatPolar_, haversine_ and vincentys_ and Geodesy-PHP.

vincentys (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the distance between two (spherical) points using Vincenty's spherical formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as radius).
Raises:

See Also: Functions vincentys_, cosineAndoyerLambert, cosineForsytheAndoyerLambert,cosineLaw, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine and thomas and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

Note: See note at function vincentys_.

vincentys_ (phi2, phi1, lam21)

 

Compute the angular distance between two (spherical) points using Vincenty's spherical formula.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
Returns:
Angular distance (radians).

See Also: Functions vincentys, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, euclidean_, flatLocal_/hubeny_, flatPolar_, haversine_ and thomas_.

Note: Functions vincentys_, haversine_ and cosineLaw_ produce equivalent results, but vincentys_ is suitable for antipodal points and slightly more expensive (3 cos, 3 sin, 1 hypot, 1 atan2, 6 mul, 2 add) than haversine_ (2 cos, 2 sin, 2 sqrt, 1 atan2, 5 mul, 1 add) and cosineLaw_ (3 cos, 3 sin, 1 acos, 3 mul, 1 add).


   Home       Trees       Indices       Help   
PyGeodesy
Generated by Epydoc 3.0.1 on Tue Oct 22 17:06:19 2024 http://epydoc.sourceforge.net