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

Module formy

Formulary of basic geodesy functions and approximations.


Version: 19.10.19

Functions
 
antipode(lat, lon)
Return the antipode, the point diametrically opposite to a given point.
 
bearing(lat1, lon1, lat2, lon2, **options)
Compute the initial or final bearing (forward or reverse azimuth) between a (spherical) start and end point.
 
bearing_(a1, b1, a2, b2, final=False, wrap=False)
Compute the initial or final bearing (forward or reverse azimuth) between a (spherical) start and end point.
 
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.
 
equirectangular(lat1, lon1, lat2, lon2, radius=6371008.77141, **options)
Compute the distance between two points using the Equirectangular Approximation / Projection.
 
equirectangular_(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.77141, adjust=True, wrap=False)
Approximate the Euclidian distance between two (spherical) points.
 
euclidean_(a2, a1, b21, adjust=True)
Approximate the angular Euclidean distance between two (spherical) points.
 
haversine(lat1, lon1, lat2, lon2, radius=6371008.77141, wrap=False)
Compute the distance between two (spherical) points using the Haversine formula.
 
haversine_(a2, a1, b21)
Compute the angular distance between two (spherical) points using the Haversine formula.
 
heightOf(angle, distance, radius=6371008.77141)
Determine the height above the (spherical) earth after traveling along a straight line at a given tilt.
 
horizon(height, radius=6371008.77141, refraction=False)
Determine the distance to the horizon from a given altitude above the (spherical) earth.
 
isantipode(lat1, lon1, lat2, lon2, eps=2.22044604925e-16)
Check whether two points are antipodal, on diametrically opposite sides of the earth.
 
points2(points, closed=True, base=None, Error=<type 'exceptions.ValueError'>)
Check a path or polygon represented by points.
 
vincentys(lat1, lon1, lat2, lon2, radius=6371008.77141, wrap=False)
Compute the distance between two (spherical) points using Vincenty's spherical formula.
 
vincentys_(a2, a1, b21)
Compute the angular distance between two (spherical) points using Vincenty's spherical formula.
Variables
  __all__ = _ALL_LAZY.formy
Function Details

antipode(lat, lon)

 

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

Parameters:
  • lat - Latitude (degrees).
  • lon - Longitude (degrees).
Returns:
A LatLon2Tuple(lat, lon).

See Also: Geosphere.

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

 

Compute the initial or final bearing (forward or reverse azimuth) between a (spherical) start and end point.

Parameters:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • options - Optional keyword arguments for function bearing_.
Returns:
Initial or final bearing (compass degrees360) or zero if start and end point coincide.

bearing_(a1, b1, a2, b2, final=False, wrap=False)

 

Compute the initial or final bearing (forward or reverse azimuth) between a (spherical) start and end point.

Parameters:
  • a1 - Start latitude (radians).
  • b1 - Start longitude (radians).
  • a2 - End latitude (radians).
  • b2 - End longitude (radians).
  • final - Return final bearing if True, initial otherwise (bool).
  • wrap - Wrap and unrollPI longitudes (bool).
Returns:
Initial or final bearing (compass radiansPI2) or zero if start and end point coincide.

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, non-near-polar vectors up to a few hundred Km or Miles. Use function bearing for longer vectors.

Parameters:
  • 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 - Wrap and unroll180 longitudes (bool).
Returns:
Compass angle from North (degrees360).

Note: Courtesy Martin Schultz.

See Also: Local, flat earth approximation.

equirectangular(lat1, lon1, lat2, lon2, radius=6371008.77141, **options)

 

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

Parameters:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Optional, mean earth radius (meter).
  • options - Optional keyword arguments for function equirectangular_.
Returns:
Distance (meter, same units as radius).

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

equirectangular_(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 the LimitError.

Parameters:
  • 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 - Wrap and unroll180 longitudes (bool).
Returns:
A Distance4Tuple(distance2, delta_lat, delta_lon, unroll_lon2).
Raises:
  • LimitError - If the lat- and/or longitudinal delta exceeds the -limit..+limit range and limiterrors set to True.

See Also: Local, flat earth approximation, functions equirectangular, euclidean, haversine and vincentys and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

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

 

Approximate the Euclidian distance between two (spherical) points.

Parameters:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Optional, mean earth radius (meter).
  • adjust - Adjust the longitudinal delta by the cosine of the mean latitude (bool).
  • wrap - Wrap and unroll180 longitudes (bool).
Returns:
Distance (meter, same units as radius).

See Also: Distance between two (spherical) points, functions equirectangular, haversine and vincentys and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

euclidean_(a2, a1, b21, adjust=True)

 

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

Parameters:
  • a2 - End latitude (radians).
  • a1 - Start latitude (radians).
  • b21 - 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 euclidean, equirectangular_, haversine_ and vincentys_.

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

 

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

Parameters:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Optional, mean earth radius (meter).
  • wrap - Wrap and unroll180 longitudes (bool).
Returns:
Distance (meter, same units as radius).

See Also: Distance between two (spherical) points, functions equirectangular, euclidean and vincentys and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

Note: See note under vincentys_.

haversine_(a2, a1, b21)

 

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

Parameters:
  • a2 - End latitude (radians).
  • a1 - Start latitude (radians).
  • b21 - Longitudinal delta, end-start (radians).
Returns:
Angular distance (radians).

See Also: Functions haversine, equirectangular_, euclidean_ and vincentys_.

Note: See note under vincentys_.

heightOf(angle, distance, radius=6371008.77141)

 

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

Parameters:
  • 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.

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

 

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

Parameters:
  • 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.

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

 

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

Parameters:
  • 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: Geosphere.

points2(points, closed=True, base=None, Error=<type 'exceptions.ValueError'>)

 

Check a path or polygon represented by points.

Parameters:
  • points - The path or polygon points (LatLon[])
  • closed - Optionally, consider the polygon closed, ignoring any duplicate or closing final points (bool).
  • base - Optionally, check all points against this base class, if None don't check.
  • Error - Exception to raise (ValueError).
Returns:
A Points2Tuple(number, points) with the number of points and the points list or tuple.
Raises:
  • TypeError - Some points are not LatLon.
  • Error - Insufficient number of points.

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

 

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

Parameters:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Optional, mean earth radius (meter).
  • wrap - Wrap and unroll180 longitudes (bool).
Returns:
Distance (meter, same units as radius).

See Also: Functions equirectangular, euclidean and haversine and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

Note: See note under vincentys_.

vincentys_(a2, a1, b21)

 

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

Parameters:
  • a2 - End latitude (radians).
  • a1 - Start latitude (radians).
  • b21 - Longitudinal delta, end-start (radians).
Returns:
Angular distance (radians).

See Also: Functions vincentys, equirectangular_, euclidean_ and haversine_.

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