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

# Module formy

Formulary of basic geodesy functions and approximations.

Version: 20.03.19

Functions
antipode(lat, lon) Return the antipode, the point diametrically opposite to a given point in `degrees`. |
antipode_(phi, lam) Return the antipode, the point diametrically opposite to a given point in `radians`. |
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. |
isantipode_(phi1, lam1, phi2, lam2, eps=2.22044604925e-16) Check whether two points are antipodal, on diametrically opposite sides of the earth. |
latlon2n_xyz(lat, lon) Convert lat-, longitude to `n-vector` (normal to the earth's surface) X, Y and Z components. |
n_xyz2latlon(x, y, z) Convert `n-vector` components to lat- and longitude in `degrees`. |
n_xyz2philam(x, y, z) Convert `n-vector` components to lat- and longitude in `radians`. |
philam2n_xyz(phi, lam) Convert lat-, longitude to `n-vector` (normal to the earth's surface) X, Y and Z components. |
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 in `degrees`. Parameters: `lat` - Latitude (`degrees`). `lon` - Longitude (`degrees`). Returns: A LatLon2Tuple`(lat, lon)`. See Also: Geosphere.

### antipode_(phi, lam) |
Return the antipode, the point diametrically opposite to a given point in `radians`. Parameters: `phi` - Latitude (`radians`). `lam` - Longitude (`radians`). Returns: A PhiLam2Tuple`(phi, lam)`. 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` - 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` - 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` - 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`. 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.

### isantipode_(phi1, lam1, phi2, lam2, eps=2.22044604925e-16) |
Check whether two points are antipodal, on diametrically opposite sides of the earth. Parameters: `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: Geosphere.

### latlon2n_xyz(lat, lon) |
Convert lat-, longitude to `n-vector` (normal to the earth's surface) X, Y and Z components. Parameters: `lat` - Latitude (`degrees`). `lon` - Longitude (`degrees`). 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!

### n_xyz2latlon(x, y, z) |
Convert `n-vector` components to lat- and longitude in `degrees`. Parameters: `x` - X component (`scalar`). `y` - Y component (`scalar`). `z` - Z component (`scalar`). Returns: A LatLon2Tuple`(lat, lon)` in `degrees`. See Also: Function n_xyz2philam.

### n_xyz2philam(x, y, z) |
Convert `n-vector` components to lat- and longitude in `radians`. Parameters: `x` - X component (`scalar`). `y` - Y component (`scalar`). `z` - Z component (`scalar`). Returns: A PhiLam2Tuple`(phi, lam)` in `radian`. See Also: Function n_xyz2latlon.

### philam2n_xyz(phi, lam) |
Convert lat-, longitude to `n-vector` (normal to the earth's surface) X, Y and Z components. Parameters: `phi` - Latitude (`radians`). `lam` - Longitude (`radians`). 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!

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