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

# Module formy

Formulary of basic geodesy functions and approximations.

Version: 19.04.07

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. |
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. |
equirectangular(lat1, lon1, lat2, lon2, radius=6371008.77141, **options) Compute the distance between two points using the Equirectangular Approximation / Projection. |
equirectangular3(lat1, lon1, lat2, lon2, **options) DEPRECATED, use function `equirectangular_`. |
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. |
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. |

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, **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.

### 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 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_.

### 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.

### equirectangular3(lat1, lon1, lat2, lon2, **options) |
DEPRECATED, use function `equirectangular_`. Returns: 3-Tuple (distance2, delta_lat, delta_lon).

### 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, euclidean, haversine and vincentys and methods Ellipsoid.distance2, `LatLon` distanceTo* and equirectangularTo.

### 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 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: Functions haversine, equirectangular_, euclidean_ and 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. See Also: MultiDop geog_lib.GeogBeamHt (Shapiro et al. 2009, JTECH and Potvin et al. 2012, JTECH).

### 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.

### 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 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).