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

Module formy

Formulary of basic geodesy functions and approximations.


Version: 18.10.20

Functions
 
antipode(lat, lon)
Return the antipode, the point diametrically opposite to a given point.
 
bearing(lat1, lon1, lat2, lon2, final=False, wrap=False)
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.
 
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.
Function Details

antipode(lat, lon)

 

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

Parameters:
  • lat - Latitude (degrees).
  • lon - Longitude (degrees).
Returns:
2-Tuple (lat, lon) of the antipodal point (degrees, degrees180).

See Also: Geosphere.

bearing(lat1, lon1, lat2, lon2, final=False, wrap=False)

 

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).
  • final - Return final or initial bearing (bool).
  • wrap - Wrap and unroll180 longitudes (bool).
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 or initial bearing (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, more 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:
4-Tuple (distance2, delta_lat, delta_lon, unroll_lon2) with the distance in degrees squared, the latitudinal delta lat2-lat1, the wrapped, unrolled, and adjusted longitudinal delta lon2-lon1 and the unrollment for lon2. Use Function degrees2m to convert degrees squared to distance in meter as degrees2m(sqrt(distance2), ...) or degrees2m(hypot(delta_lat, delta_lon), ...).
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 and haversine, Ellipsoid method distance2 and LatLon methods distanceTo* for more accurate and/or larger distances.

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, Ellipsoid.distance2 or LatLon methods distanceTo* and equirectangularTo.

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: Function haversine.

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.