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

# Module formy

Formulary of basic geodesy functions and approximations.

Version: 20.04.21

Classes
| PointsError Insufficient number of points.

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_(phi1, lam1, phi2, lam2, 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. |
cosineLaw(lat1, lon1, lat2, lon2, radius=6371008.77141, wrap=False) Compute the distance between two points using the spherical Law of Cosines fromula. |
cosineLaw_(phi2, phi1, lam21) Compute the angular distance between two points using the spherical Law of Cosines fromula. |
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_(phi2, phi1, lam21, adjust=True) Approximate the angular `Euclidean` distance between two (spherical) points. |
flatLocal(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=False) Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection fromula. |
flatLocal_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection fromula. |
flatPolar(lat1, lon1, lat2, lon2, radius=6371008.77141, 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. |
haversine(lat1, lon1, lat2, lon2, radius=6371008.77141, 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.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=<class 'pygeodesy.formy.PointsError'>) 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_(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) |
Return the antipode, the point diametrically opposite to a given point in `degrees`. Arguments: `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`. Arguments: `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. Arguments: `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_ (phi1, lam1, phi2, lam2, final=False, wrap=False) |
Compute the initial or final bearing (forward or reverse azimuth) between a (spherical) start and end point. Arguments: `phi1` - Start latitude (`radians`). `lam1` - Start longitude (`radians`). `phi2` - End latitude (`radians`). `lam2` - 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. 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` - Wrap and unroll180 longitudes (`bool`). Returns: Compass angle from North (`degrees360`). Note: Courtesy Martin Schultz. See Also: Local, flat earth approximation.

### cosineLaw (lat1, lon1, lat2, lon2, radius=6371008.77141, wrap=False) |
Compute the distance between two points using the spherical Law of Cosines fromula. Arguments: `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`). Raises: `TypeError` - Invalid `datum`. See Also: Functions cosineLaw_, equirectangular, euclidean, flatLocal, flatPolar, haversine, 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 fromula. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). Returns: Angular distance (`radians`). See Also: Functions cosineLaw, equirectangular_, euclidean_, flatLocal_, flatPolar_, haversine_ and vincentys_. Note: See note at function vincentys_.

### equirectangular (lat1, lon1, lat2, lon2, radius=6371008.77141, **options) |
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`). `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. 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` - 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, cosineLaw, euclidean, flatLocal, flatPolar, haversine, 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. Arguments: `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 euclidean_, cosineLaw, equirectangular, flatLocal, flatPolar, haversine, 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 euclidean, cosineLaw_, equirectangular_, flatLocal_, flatPolar_, haversine_ and vincentys_.

### flatLocal (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=False) |
Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection fromula. Arguments: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `datum` - Optional, (ellipsoidal) datum to use (Datum). `wrap` - Wrap and unroll180 longitudes (`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 latitude. See Also: Functions flatLocal_, cosineLaw, flatPolar, equirectangular, euclidean, haversine, vincentys, method Ellipsoid.distance2 and local, flat earth approximation.

### flatLocal_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) |
Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection fromula. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). `datum` - Optional, (ellipsoidal) datum to use (Datum). 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 latitude. See Also: Functions flatLocal, cosineLaw_, flatPolar_, equirectangular_, euclidean_, haversine_ and vincentys_ and local, flat earth approximation.

### flatPolar (lat1, lon1, lat2, lon2, radius=6371008.77141, 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`). `wrap` - Wrap and unroll180 longitudes (`bool`). Returns: Distance (`meter`, same units as `radius`). See Also: Functions flatPolar_, cosineLaw, flatLocal, equirectangular, euclidean, haversine 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, cosineLaw_, equirectangular_, euclidean_, flatLocal_, haversine_ and vincentys_.

### haversine (lat1, lon1, lat2, lon2, radius=6371008.77141, 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`). `wrap` - Wrap and unroll180 longitudes (`bool`). Returns: Distance (`meter`, same units as `radius`). See Also: Distance between two (spherical) points, functions cosineLaw, equirectangular, euclidean, flatLocal, flatPolar, 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, cosineLaw_, equirectangular_, euclidean_, flatLocal_, flatPolar_ and vincentys_. Note: See note at function vincentys_.

### heightOf (angle, distance, radius=6371008.77141) |
Determine the height above the (spherical) earth 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).

### horizon (height, radius=6371008.77141, 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.

### isantipode (lat1, lon1, lat2, lon2, eps=2.22044604925e-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: Geosphere.

### isantipode_ (phi1, lam1, phi2, lam2, eps=2.22044604925e-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: Geosphere.

### latlon2n_xyz (lat, lon) |
Convert lat-, longitude to `n-vector` (normal to the earth's surface) X, Y and Z components. Arguments: `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`. Arguments: `x` - X component (`scalar`). `y` - Y component (`scalar`). `z` - Z component (`scalar`). Returns: A LatLon2Tuple`(lat, lon)`. See Also: Function n_xyz2philam.

### n_xyz2philam (x, y, z) |
Convert `n-vector` components to lat- and longitude in `radians`. Arguments: `x` - X component (`scalar`). `y` - Y component (`scalar`). `z` - Z component (`scalar`). Returns: A PhiLam2Tuple`(phi, lam)`. 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. Arguments: `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=<class 'pygeodesy.formy.PointsError'>) |
Check a path or polygon represented by points. Arguments: `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: `PointsError` - Insufficient number of `points`. `TypeError` - Some `points` are not `base` compatible.

### vincentys (lat1, lon1, lat2, lon2, radius=6371008.77141, 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`). `wrap` - Wrap and unroll180 longitudes (`bool`). Returns: Distance (`meter`, same units as `radius`). See Also: Functions vincentys_, cosineLaw, equirectangular, euclidean, flatLocal, flatPolar, haversine 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, cosineLaw_, equirectangular_, euclidean_, flatLocal_, flatPolar_ and haversine_. Note: Functions vincentys_, haversine_ and cosineLaw_ produce equivalent results, but vincentys_ is suitable for antipodal points but 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).