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

# Module formy

Formulary of basic geodesy functions and approximations.

Version: 23.05.15

Classes
| Radical2Tuple 2-Tuple `(ratio, xline)` of the radical `ratio` and radical `xline`, both `scalar` and `0.0 <= ratio <= 1.0`

Functions
antipode(lat, lon, name='') Return the antipode, the point diametrically opposite to a given point in `degrees`. |
antipode_(phi, lam, name='') Return the antipode, the point diametrically opposite to a given point in `radians`. |
bearing(lat1, lon1, lat2, lon2, **final_wrap) 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. |
cosineAndoyerLambert(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=False) Compute the distance between two (ellipsoidal) points using the Andoyer-Lambert correction of the Law of Cosines formula. |
cosineAndoyerLambert_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) Compute the angular distance between two (ellipsoidal) points using the Andoyer-Lambert correction of the Law of Cosines formula. |
cosineForsytheAndoyerLambert(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=False) Compute the distance between two (ellipsoidal) points using the Forsythe-Andoyer-Lambert correction of the Law of Cosines formula. |
cosineForsytheAndoyerLambert_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) Compute the angular distance between two (ellipsoidal) points using the Forsythe-Andoyer-Lambert correction of the Law of Cosines formula. |
cosineLaw(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False) Compute the distance between two points using the spherical Law of Cosines formula. |
cosineLaw_(phi2, phi1, lam21) Compute the angular distance between two points using the spherical Law of Cosines formula. |
equirectangular(lat1, lon1, lat2, lon2, radius=6371008.771415, **adjust_limit_wrap) 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.771415, adjust=True, wrap=False) Approximate the `Euclidean` distance between two (spherical) points. |
euclidean_(phi2, phi1, lam21, adjust=True) Approximate the angular `Euclidean` distance between two (spherical) points. |
excessAbc_(A, b, c) Compute the spherical excess `E` of a (spherical) triangle from two sides and the included angle. |
excessGirard_(A, B, C) Compute the spherical excess `E` of a (spherical) triangle using Girard's formula. |
excessLHuilier_(a, b, c) Compute the spherical excess `E` of a (spherical) triangle using L'Huilier's Theorem. |
excessKarney(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False) Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method. |
excessKarney_(phi2, phi1, lam21) Compute the spherical excess `E` of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method. |
excessQuad(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False) Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator. |
excessQuad_(phi2, phi1, lam21) Compute the spherical excess `E` of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator. |
flatLocal(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, scaled=True, wrap=False) Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula. |
hubeny(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, scaled=True, wrap=False) Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula. |
flatLocal_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, scaled=True) Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula. |
hubeny_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, scaled=True) Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula. |
flatPolar(lat1, lon1, lat2, lon2, radius=6371008.771415, 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. |
hartzell(pov, los=None, earth=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, name='', **LatLon_and_kwds) Compute the intersection of the earth's surface and a Line-Of-Sight from a Point-Of-View in space. |
haversine(lat1, lon1, lat2, lon2, radius=6371008.771415, 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.771415) Determine the height above the (spherical) earth' surface after traveling along a straight line at a given tilt. |
horizon(height, radius=6371008.771415, refraction=False) Determine the distance to the horizon from a given altitude above the (spherical) earth. |
intersection2(lat1, lon1, bearing1, lat2, lon2, bearing2, datum=None, wrap=False, small=100000.0) Conveniently compute the intersection of two lines each defined by a (geodetic) point and a bearing from North, using either ... |
intersections2(lat1, lon1, radius1, lat2, lon2, radius2, datum=None, wrap=False, small=100000.0) Conveniently compute the intersections of two circles each defined by a (geodetic) center point and a radius, using either ... |
isantipode(lat1, lon1, lat2, lon2, eps=2.220446049250313e-16) Check whether two points are antipodal, on diametrically opposite sides of the earth. |
isantipode_(phi1, lam1, phi2, lam2, eps=2.220446049250313e-16) Check whether two points are antipodal, on diametrically opposite sides of the earth. |
isnormal(lat, lon, eps=0) Check whether `lat` and `lon` are within their respective normal range in `degrees`. |
isnormal_(phi, lam, eps=0) Check whether `phi` and `lam` are within their respective normal range in `radians`. |
latlon2n_xyz(lat, lon, name='') Convert lat-, longitude to `n-vector` (normal to the earth's surface) X, Y and Z components. |
normal(lat, lon, name='') Normalize a lat- and longitude pair in `degrees`. |
normal_(phi, lam, name='') Normalize a lat- and longitude pair in `radians`. |
n_xyz2latlon(x, y, z, name='') Convert `n-vector` components to lat- and longitude in `degrees`. |
n_xyz2philam(x, y, z, name='') Convert `n-vector` components to lat- and longitude in `radians`. |
opposing(bearing1, bearing2, margin=90.0) Compare the direction of two bearings given in `degrees`. |
opposing_(radians1, radians2, margin=1.5707963267948966) Compare the direction of two bearings given in `radians`. |
philam2n_xyz(phi, lam, name='') Convert lat-, longitude to `n-vector` (normal to the earth's surface) X, Y and Z components. |
radical2(distance, radius1, radius2) Compute the radical ratio and radical line of two intersecting circles. |
thomas(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=False) Compute the distance between two (ellipsoidal) points using Thomas' formula. |
thomas_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) Compute the angular distance between two (ellipsoidal) points using Thomas' formula. |
vincentys(lat1, lon1, lat2, lon2, radius=6371008.771415, 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, name='') |
Return the antipode, the point diametrically opposite to a given point in `degrees`. Arguments: `lat` - Latitude (`degrees`). `lon` - Longitude (`degrees`). `name` - Optional name (`str`). Returns: A LatLon2Tuple`(lat, lon)`. See Also: Functions antipode_ and normal and Geosphere.

### antipode_ (phi, lam, name='') |
Return the antipode, the point diametrically opposite to a given point in `radians`. Arguments: `phi` - Latitude (`radians`). `lam` - Longitude (`radians`). `name` - Optional name (`str`). Returns: A PhiLam2Tuple`(phi, lam)`. See Also: Functions antipode and normal_ and Geosphere.

### bearing (lat1, lon1, lat2, lon2, **final_wrap) |
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`). `final_wrap` - Optional keyword arguments for function pygeodesy.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` - If `True`, wrap or normalize and unroll `phi2` and `lam2` (`bool`). Returns: Initial or final bearing (compass `radiansPI2`) or zero if start and end point coincide. See Also: Bearing, Course between two points and Bearing Between Two Points.

### 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, not near-polar vectors up to a few hundred Km or Miles. Use function pygeodesy.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` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). Returns: Compass angle from North (`degrees360`). Note: Courtesy of Martin Schultz. See Also: Local, flat earth approximation.

### cosineAndoyerLambert (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=False) |
Compute the distance between two (ellipsoidal) points using the Andoyer-Lambert correction of the Law of Cosines formula. Arguments: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `datum` - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). Returns: Distance (`meter`, same units as the `datum`'s ellipsoid axes or `radians` if `datum` is `None`). Raises: `TypeError` - Invalid `datum`. See Also: Functions cosineAndoyerLambert_, cosineForsytheAndoyerLambert, cosineLaw, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine, thomas and vincentys and method Ellipsoid.distance2.

### cosineAndoyerLambert_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) |
Compute the angular distance between two (ellipsoidal) points using the Andoyer-Lambert correction of the Law of Cosines formula. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). `datum` - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. Returns: Angular distance (`radians`). Raises: `TypeError` - Invalid `datum`. See Also: Functions cosineAndoyerLambert, cosineForsytheAndoyerLambert_, cosineLaw_, equirectangular_, euclidean_, flatLocal_/hubeny_, flatPolar_, haversine_, thomas_ and vincentys_ and Geodesy-PHP.

### cosineForsytheAndoyerLambert (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=False) |
Compute the distance between two (ellipsoidal) points using the Forsythe-Andoyer-Lambert correction of the Law of Cosines formula. Arguments: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `datum` - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). Returns: Distance (`meter`, same units as the `datum`'s ellipsoid axes or `radians` if `datum` is `None`). Raises: `TypeError` - Invalid `datum`. See Also: Functions cosineForsytheAndoyerLambert_, cosineAndoyerLambert, cosineLaw, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine, thomas and vincentys and method Ellipsoid.distance2.

### cosineForsytheAndoyerLambert_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) |
Compute the angular distance between two (ellipsoidal) points using the Forsythe-Andoyer-Lambert correction of the Law of Cosines formula. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). `datum` - Datum (Datum) or ellipsoid to use (Ellipsoid, Ellipsoid2 or a_f2Tuple). Returns: Angular distance (`radians`). Raises: `TypeError` - Invalid `datum`. See Also: Functions cosineForsytheAndoyerLambert, cosineAndoyerLambert_, cosineLaw_, equirectangular_, euclidean_, flatLocal_/hubeny_, flatPolar_, haversine_, thomas_ and vincentys_ and Geodesy-PHP.

### cosineLaw (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False) |
Compute the distance between two points using the spherical Law of Cosines formula. Arguments: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `radius` - Mean earth radius (`meter`), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `wrap` - If `True`, wrap or normalize and `lat2` and `lon2` (`bool`). Returns: Distance (`meter`, same units as `radius` or the ellipsoid or datum axes). Raises: `TypeError` - Invalid `radius`. See Also: Functions cosineLaw_, cosineAndoyerLambert, cosineForsytheAndoyerLambert, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine, thomas and 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 formula. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). Returns: Angular distance (`radians`). See Also: Functions cosineLaw, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, equirectangular_, euclidean_, flatLocal_/hubeny_, flatPolar_, haversine_, thomas_ and vincentys_. Note: See note at function vincentys_.

### equirectangular (lat1, lon1, lat2, lon2, radius=6371008.771415, **adjust_limit_wrap) |
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`), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple). `adjust_limit_wrap` - Optional keyword arguments for function equirectangular_. Returns: Distance (`meter`, same units as `radius` or the ellipsoid or datum axes). Raises: `TypeError` - Invalid `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 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` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). Returns: A Distance4Tuple`(distance2, delta_lat, delta_lon, unroll_lon2)` in `degrees squared`. Raises: `LimitError` - If the lat- and/or longitudinal delta exceeds the `-limit..limit` range and pygeodesy.limiterrors set to `True`. See Also: Local, flat earth approximation, functions equirectangular, cosineAndoyerLambert, cosineForsytheAndoyerLambert, cosineLaw, euclidean, flatLocal/hubeny, flatPolar, haversine, thomas and vincentys and methods Ellipsoid.distance2, `LatLon.distanceTo*` and `LatLon.equirectangularTo`.

### euclidean (lat1, lon1, lat2, lon2, radius=6371008.771415, adjust=True, wrap=False) |
Approximate the `Euclidean` 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`), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `adjust` - Adjust the longitudinal delta by the cosine of the mean latitude (`bool`). `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). Returns: Distance (`meter`, same units as `radius` or the ellipsoid or datum axes). Raises: `TypeError` - Invalid `radius`. See Also: Distance between two (spherical) points, functions euclid, euclidean_, cosineAndoyerLambert, cosineForsytheAndoyerLambert, cosineLaw, equirectangular, flatLocal/hubeny, flatPolar, haversine, thomas and 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 euclid, euclidean, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, equirectangular_, flatLocal_/hubeny_, flatPolar_, haversine_, thomas_ and vincentys_.

### excessAbc_ (A, b, c) |
Compute the spherical excess `E` of a (spherical) triangle from two sides and the included angle. Arguments: `A` - An interior triangle angle (`radians`). `b` - Frist adjacent triangle side (`radians`). `c` - Second adjacent triangle side (`radians`). Returns: Spherical excess (`radians`). Raises: `UnitError` - Invalid `A`, `b` or `c`. See Also: Functions excessGirard_, excessLHuilier_ and Spherical trigonometry.

### excessGirard_ (A, B, C) |
Compute the spherical excess `E` of a (spherical) triangle using Girard's formula. Arguments: `A` - First interior triangle angle (`radians`). `B` - Second interior triangle angle (`radians`). `C` - Third interior triangle angle (`radians`). Returns: Spherical excess (`radians`). Raises: `UnitError` - Invalid `A`, `B` or `C`. See Also: Function excessLHuilier_ and Spherical trigonometry.

### excessLHuilier_ (a, b, c) |
Compute the spherical excess `E` of a (spherical) triangle using L'Huilier's Theorem. Arguments: `a` - First triangle side (`radians`). `b` - Second triangle side (`radians`). `c` - Third triangle side (`radians`). Returns: Spherical excess (`radians`). Raises: `UnitError` - Invalid `a`, `b` or `c`. See Also: Function excessGirard_ and Spherical trigonometry.

### excessKarney (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False) |
Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method. Arguments: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `radius` - Mean earth radius (`meter`), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or `None`. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). Returns: Surface area, signed (square `meter` or the same units as `radius` squared) or the spherical excess (`radians`) if `radius=0` or `None`. Raises: `TypeError` - Invalid `radius`. `UnitError` - Invalid `lat2` or `lat1`. `ValueError` - Semi-circular longitudinal delta. See Also: Functions excessKarney_ and excessQuad.

### excessKarney_ (phi2, phi1, lam21) |
Compute the spherical excess `E` of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). Returns: Spherical excess, signed (`radians`). Raises: `ValueError` - Semi-circular longitudinal delta `lam21`. See Also: Function excessKarney and Area of a spherical polygon.

### excessQuad (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False) |
Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator. Arguments: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `radius` - Mean earth radius (`meter`), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or `None`. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). Returns: Surface area, signed (square `meter` or the same units as `radius` squared) or the spherical excess (`radians`) if `radius=0` or `None`. Raises: `TypeError` - Invalid `radius`. `UnitError` - Invalid `lat2` or `lat1`. See Also: Function excessQuad_ and excessKarney.

### excessQuad_ (phi2, phi1, lam21) |
Compute the spherical excess `E` of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). Returns: Spherical excess, signed (`radians`). See Also: Function excessQuad, Spherical trigonometry.

### flatLocal (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, scaled=True, wrap=False) |
Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula. Arguments: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `datum` - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `scaled` - Scale prime_vertical by `cos(phi)` (`bool`), see method pygeodesy.Ellipsoid.roc2_. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`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 of both latitude. See Also: Functions flatLocal_ or hubeny_, cosineLaw, flatPolar, cosineAndoyerLambert, cosineForsytheAndoyerLambert, equirectangular, euclidean, haversine, thomas, vincentys, method Ellipsoid.distance2 and local, flat earth approximation.

### hubeny (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, scaled=True, wrap=False) |
Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula. Arguments: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `datum` - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `scaled` - Scale prime_vertical by `cos(phi)` (`bool`), see method pygeodesy.Ellipsoid.roc2_. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`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 of both latitude. See Also: Functions flatLocal_ or hubeny_, cosineLaw, flatPolar, cosineAndoyerLambert, cosineForsytheAndoyerLambert, equirectangular, euclidean, haversine, thomas, vincentys, method Ellipsoid.distance2 and local, flat earth approximation.

### flatLocal_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, scaled=True) |
Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). `datum` - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `scaled` - Scale prime_vertical by `cos(phi)` (`bool`), see method pygeodesy.Ellipsoid.roc2_. Returns: Angular distance (`radians`). Raises: `TypeError` - Invalid `datum`. Note: The meridional and prime_vertical radii of curvature are taken and scaled at the mean of both latitude. See Also: Functions flatLocal or hubeny, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, flatPolar_, equirectangular_, euclidean_, haversine_, thomas_ and vincentys_ and local, flat earth approximation.

### hubeny_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, scaled=True) |
Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). `datum` - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `scaled` - Scale prime_vertical by `cos(phi)` (`bool`), see method pygeodesy.Ellipsoid.roc2_. Returns: Angular distance (`radians`). Raises: `TypeError` - Invalid `datum`. Note: The meridional and prime_vertical radii of curvature are taken and scaled at the mean of both latitude. See Also: Functions flatLocal or hubeny, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, flatPolar_, equirectangular_, euclidean_, haversine_, thomas_ and vincentys_ and local, flat earth approximation.

### flatPolar (lat1, lon1, lat2, lon2, radius=6371008.771415, 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`), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `wrap` - If `True`, wrap or normalize and `lat2` and `lon2` (`bool`). Returns: Distance (`meter`, same units as `radius` or the ellipsoid or datum axes). Raises: `TypeError` - Invalid `radius`. See Also: Functions flatPolar_, cosineAndoyerLambert, cosineForsytheAndoyerLambert,cosineLaw, flatLocal/hubeny, equirectangular, euclidean, haversine, thomas 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, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, equirectangular_, euclidean_, flatLocal_/hubeny_, haversine_, thomas_ and vincentys_.

### hartzell (pov, los=None, earth=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, name='', **LatLon_and_kwds) |
Compute the intersection of the earth's surface and a Line-Of-Sight from a Point-Of-View in space. Arguments: `pov` - Point-Of-View outside the earth (`Cartesian`, Ecef9Tuple or Vector3d). `los` - Line-Of-Sight, direction to earth (Vector3d) or `None` to point to the earth' center. `earth` - The earth model (Datum, Ellipsoid, Ellipsoid2, a_f2Tuple or `scalar` radius in `meter`). `name` - Optional name (`str`). `LatLon_and_kwds` - Optional `LatLon` class for the intersection point plus `LatLon` keyword arguments, include `datum` if different from `earth`. Returns: The earth intersection (Vector3d, `Cartesian type` of `pov` or `LatLon`). Raises: `IntersectionError` - Null `pov` or `los` vector, `pov` is inside the earth or `los` points outside the earth or points in an opposite direction. `TypeError` - Invalid `pov`, `los` or `earth`. See Also: Function pygeodesy.hartzell4, pygeodesy.tyr3d for `los`, method Ellipsoid.hartzell4 and Satellite Line-of-Sight Intersection with Earth.

### haversine (lat1, lon1, lat2, lon2, radius=6371008.771415, 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`), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). Returns: Distance (`meter`, same units as `radius`). Raises: `TypeError` - Invalid `radius`. See Also: Distance between two (spherical) points, functions cosineLaw, cosineAndoyerLambert, cosineForsytheAndoyerLambert, equirectangular, euclidean, flatLocal/hubeny, flatPolar, thomas and 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, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, equirectangular_, euclidean_, flatLocal_/hubeny_, flatPolar_, thomas_ and vincentys_. Note: See note at function vincentys_.

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

### intersection2 (lat1, lon1, bearing1, lat2, lon2, bearing2, datum=None, wrap=False, small=100000.0) |
Conveniently compute the intersection of two lines each defined by a (geodetic) point and a bearing from North, using either ... 1) vector3d.intersection3d3 for `small` distances (below 100 Km or about 0.88 degrees) or if no `datum` is specified, or ... 2) sphericalTrigonometry.intersection for a spherical `datum` or a `scalar datum` representing the earth radius, conventionally in `meter` or ... 3) sphericalNvector.intersection if `datum` is a negative `scalar`, (negative) earth radius, conventionally in `meter` or ... 4) ellipsoidalKarney.intersection3 for an ellipsoidal `datum` and if Karney's geographiclib is installed, otherwise ... 5) ellipsoidalExact.intersection3, provided `datum` is ellipsoidal. Arguments: `lat1` - Latitude of the first point (`degrees`). `lon1` - Longitude of the first point (`degrees`). `bearing1` - Bearing at the first point (compass `degrees`). `lat2` - Latitude of the second point (`degrees`). `lon2` - Longitude of the second point (`degrees`). `bearing2` - Bearing at the second point (compass `degrees`). `datum` - Optional datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or `scalar` earth radius (`meter`, same units as `radius1` and `radius2`) or `None`. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). `small` - Upper limit for small distances (`meter`). Returns: A LatLon2Tuple`(lat, lon)` with the lat- and longitude of the intersection point. Raises: `IntersectionError` - Ambiguous or infinite intersection or colinear, parallel or otherwise non-intersecting lines. `TypeError` - Invalid `datum`. `UnitError` - Invalid `lat1`, `lon1`, `bearing1`, `lat2`, `lon2` or `bearing2`. See Also: Method RhumbLine.intersection2. Note: The returned intersections may be near-antipodal.

### intersections2 (lat1, lon1, radius1, lat2, lon2, radius2, datum=None, wrap=False, small=100000.0) |
Conveniently compute the intersections of two circles each defined by a (geodetic) center point and a radius, using either ... 1) vector3d.intersections2 for `small` distances (below 100 Km or about 0.88 degrees) or if no `datum` is specified, or ... 2) sphericalTrigonometry.intersections2 for a spherical `datum` or a `scalar datum` representing the earth radius, conventionally in `meter` or ... 3) ellipsoidalKarney.intersections2 for an ellipsoidal `datum` and if Karney's geographiclib is installed, otherwise ... 4) ellipsoidalExact.intersections2, provided `datum` is ellipsoidal. Arguments: `lat1` - Latitude of the first circle center (`degrees`). `lon1` - Longitude of the first circle center (`degrees`). `radius1` - Radius of the first circle (`meter`, conventionally). `lat2` - Latitude of the second circle center (`degrees`). `lon2` - Longitude of the second circle center (`degrees`). `radius2` - Radius of the second circle (`meter`, same units as `radius1`). `datum` - Optional datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or `scalar` earth radius (`meter`, same units as `radius1` and `radius2`) or `None`. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). `small` - Upper limit for small distances (`meter`). Returns: 2-Tuple of the intersection points, each a LatLon2Tuple`(lat, lon)`. For abutting circles, the points are the same instance, aka the radical center. Raises: `IntersectionError` - Concentric, antipodal, invalid or non-intersecting circles or no convergence. `TypeError` - Invalid `datum`. `UnitError` - Invalid `lat1`, `lon1`, `radius1`, `lat2`, `lon2` or `radius2`.

### isantipode (lat1, lon1, lat2, lon2, eps=2.220446049250313e-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: Functions isantipode_ and antipode.

### isantipode_ (phi1, lam1, phi2, lam2, eps=2.220446049250313e-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: Functions isantipode and antipode_.

### isnormal (lat, lon, eps=0) |
Check whether `lat` and `lon` are within their respective normal range in `degrees`. Arguments: `lat` - Latitude (`degrees`). `lon` - Longitude (`degrees`). `eps` - Optional tolerance `degrees`). Returns: `True` if `(abs(lat) + eps) <= 90` and `(abs(lon) + eps) <= 180`, `False` othwerwise. See Also: Functions isnormal_ and normal.

### isnormal_ (phi, lam, eps=0) |
Check whether `phi` and `lam` are within their respective normal range in `radians`. Arguments: `phi` - Latitude (`radians`). `lam` - Longitude (`radians`). `eps` - Optional tolerance `radians`). Returns: `True` if `(abs(phi) + eps) <= PI/2` and `(abs(lam) + eps) <= PI`, `False` othwerwise. See Also: Functions isnormal and normal_.

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

### normal (lat, lon, name='') |
Normalize a lat- and longitude pair in `degrees`. Arguments: `lat` - Latitude (`degrees`). `lon` - Longitude (`degrees`). `name` - Optional name (`str`). Returns: LatLon2Tuple`(lat, lon)` with `abs(lat) <= 90` and `abs(lon) <= 180`. See Also: Functions normal_ and isnormal.

### normal_ (phi, lam, name='') |
Normalize a lat- and longitude pair in `radians`. Arguments: `phi` - Latitude (`radians`). `lam` - Longitude (`radians`). `name` - Optional name (`str`). Returns: PhiLam2Tuple`(phi, lam)` with `abs(phi) <= PI/2` and `abs(lam) <= PI`. See Also: Functions normal and isnormal_.

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

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

### opposing (bearing1, bearing2, margin=90.0) |
Compare the direction of two bearings given in `degrees`. Arguments: `bearing1` - First bearing (compass `degrees`). `bearing2` - Second bearing (compass `degrees`). `margin` - Optional, interior angle bracket (`degrees`). Returns: `True` if both bearings point in opposite, `False` if in similar or `None` if in perpendicular directions. See Also: Function opposing_.

### opposing_ (radians1, radians2, margin=1.5707963267948966) |
Compare the direction of two bearings given in `radians`. Arguments: `radians1` - First bearing (`radians`). `radians2` - Second bearing (`radians`). `margin` - Optional, interior angle bracket (`radians`). Returns: `True` if both bearings point in opposite, `False` if in similar or `None` if in perpendicular directions. See Also: Function opposing.

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

### radical2 (distance, radius1, radius2) |
Compute the radical ratio and radical line of two intersecting circles. The radical line is perpendicular to the axis thru the centers of the circles at `(0, 0)` and `(distance, 0)`. Arguments: `distance` - Distance between the circle centers (`scalar`). `radius1` - Radius of the first circle (`scalar`). `radius2` - Radius of the second circle (`scalar`). Returns: A Radical2Tuple`(ratio, xline)` where `0.0 <= ratio <= 1.0` and `xline` is along the `distance`. Raises: `IntersectionError` - The `distance` exceeds the sum of `radius1` and `radius2`. `UnitError` - Invalid `distance`, `radius1` or `radius2`. See Also: Circle-Circle Intersection.

### thomas (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, wrap=False) |
Compute the distance between two (ellipsoidal) points using Thomas' formula. Arguments: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `datum` - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). Returns: Distance (`meter`, same units as the `datum`'s ellipsoid axes). Raises: `TypeError` - Invalid `datum`. See Also: Functions thomas_, cosineAndoyerLambert, cosineForsytheAndoyerLambert, cosineLaw, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine, vincentys and method Ellipsoid.distance2.

### thomas_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) |
Compute the angular distance between two (ellipsoidal) points using Thomas' formula. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). `datum` - Datum or ellipsoid to use (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple). Returns: Angular distance (`radians`). Raises: `TypeError` - Invalid `datum`. See Also: Functions thomas, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, equirectangular_, euclidean_, flatLocal_/hubeny_, flatPolar_, haversine_ and vincentys_ and Geodesy-PHP.

### vincentys (lat1, lon1, lat2, lon2, radius=6371008.771415, 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`), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `wrap` - If `True`, wrap or normalize and unroll `lat2` and `lon2` (`bool`). Returns: Distance (`meter`, same units as `radius`). Raises: `UnitError` - Invalid `radius`. See Also: Functions vincentys_, cosineAndoyerLambert, cosineForsytheAndoyerLambert,cosineLaw, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine and thomas 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, cosineAndoyerLambert_, cosineForsytheAndoyerLambert_, cosineLaw_, equirectangular_, euclidean_, flatLocal_/hubeny_, flatPolar_, haversine_ and thomas_. Note: Functions vincentys_, haversine_ and cosineLaw_ produce equivalent results, but vincentys_ is suitable for antipodal points and 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).