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

# Module formy

Formulary of basic geodesy functions and approximations.

Version: 25.04.14

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

Functions
angle2chord(rad, radius=6371008.771415) Get the chord length of a (central) angle or angular distance. |
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 two (spherical) points. |
bearing_(phi1, lam1, phi2, lam2, final=False, wrap=False) Compute the initial or final bearing (forward or reverse azimuth) between two (spherical) points. |
chord2angle(chord, radius=6371008.771415) Get the (central) angle from a chord length or distance. |
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, corr=0, earth=None, wrap=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, radius=6371008.771415) Compute the distance between two points using the Law of Cosines formula, optionally corrected. |
cosineLaw_(phi2, phi1, lam21, corr=0, earth=None, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) Compute the angular distance between two points using the Law of Cosines formula, optionally corrected. |
equirectangular(lat1, lon1, lat2, lon2, radius=6371008.771415, **adjust_limit_wrap) Approximate the distance between two points using the Equirectangular Approximation / Projection. |
equirectangular4(lat1, lon1, lat2, lon2, adjust=True, limit=45, wrap=False) Approximate 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 (small) angle. |
excessCagnoli_(a, b, c) Compute the spherical excess `E` of a (spherical) triangle using Cagnoli's (D.34) formula. |
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'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=False, 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. |
heightOrthometric(h_loc, N) Get the orthometric height H, the height above the geoid, earth surface. |
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`. |
normal(lat, lon, **name) Normalize a lat- and longitude pair in `degrees`. |
normal_(phi, lam, **name) Normalize a lat- and longitude pair 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`. |
radical2(distance, radius1, radius2, **name) 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

### angle2chord (rad, radius=6371008.771415) |
Get the chord length of a (central) angle or angular distance. Arguments: `rad` - Central angle (`radians`). `radius` - Mean earth radius (`meter`, conventionally), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use or `None`. Returns: Chord length (`meter`, same units as `radius` or if `radius is None`, `radians`). See Also: Function chord2angle, method intermediateChordTo and great-circle-distance.

### 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=NN` (`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=NN` (`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 two (spherical) points. 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 both points coincide.

### bearing_ (phi1, lam1, phi2, lam2, final=False, wrap=False) |
Compute the initial or final bearing (forward or reverse azimuth) between two (spherical) points. Arguments: `phi1` - Start latitude (`radians`). `lam1` - Start longitude (`radians`). `phi2` - End latitude (`radians`). `lam2` - End longitude (`radians`). `final` - If `True`, return the final, otherwise the initial bearing (`bool`). `wrap` - If `True`, wrap or normalize and unroll `phi2` and `lam2` (`bool`). Returns: Initial or final bearing (compass `radiansPI2`) or zero if both points coincide. See Also: Bearing, Course between two points and Bearing Between Two Points.

### chord2angle (chord, radius=6371008.771415) |
Get the (central) angle from a chord length or distance. Arguments: `chord` - Length or distance (`meter`, same units as `radius`). `radius` - Mean earth radius (`meter`, conventionally), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. Returns: Angle (`radians` with sign of `chord`) or `0` if `radius=0`. Note: The angle will exceed `PI` if `chord > radius * 2`. See Also: Function angle2chord.

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

### cosineLaw (lat1, lon1, lat2, lon2, corr=0, earth=None, wrap=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, radius=6371008.771415) |
Compute the distance between two points using the Law of Cosines formula, optionally corrected. Arguments: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `corr` - Use `corr=2` to apply the Forsythe-Andoyer-Lambert, `corr=1` for the Andoyer-Lambert corrected (ellipsoidal) or keep `corr=0` for the uncorrected (spherical) `Law of Cosines` formula (`int`). `earth` - Mean earth radius (`meter`) or datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `wrap` - If `True`, wrap or normalize and `lat2` and `lon2` (`bool`). `datum` - Default ellipsiodal `earth` (and for backward compatibility). `radius` - Default spherical `earth` (and for backward compatibility). Returns: Distance (`meter`, same units as `radius` or the datum's or ellipsoid axes). Raises: `TypeError` - Invalid `earth`, `datum` or `radius`. `ValueError` - Invalid `corr`. See Also: Functions cosineLaw_, equirectangular, euclidean, flatLocal / hubeny, flatPolar, haversine, thomas and vincentys and method Ellipsoid.distance2. Note: See note at function vincentys_.

### cosineLaw_ (phi2, phi1, lam21, corr=0, earth=None, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`) |
Compute the angular distance between two points using the Law of Cosines formula, optionally corrected. Arguments: `phi2` - End latitude (`radians`). `phi1` - Start latitude (`radians`). `lam21` - Longitudinal delta, end-start (`radians`). `corr` - Use `corr=2` to apply the Forsythe-Andoyer-Lambert, `corr=1` for the Andoyer-Lambert corrected (ellipsoidal) or keep `corr=0` for the uncorrected (spherical) `Law of Cosines` formula (`int`). `earth` - Mean earth radius (`meter`) or datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use. `datum` - Default ellipsoidal `earth` (and for backward compatibility). Returns: Angular distance (`radians`). Raises: `TypeError` - Invalid `earth` or `datum`. `ValueError` - Invalid `corr`. See Also: Functions cosineLaw, euclidean_, flatLocal_ / hubeny_, flatPolar_, haversine_, thomas_ and vincentys_ and Geodesy-PHP.

### equirectangular (lat1, lon1, lat2, lon2, radius=6371008.771415, **adjust_limit_wrap) |
Approximate 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` - Optionally, keyword arguments for function equirectangular4. Returns: Distance (`meter`, same units as `radius` or the datum's ellipsoid axes). Raises: `TypeError` - Invalid `radius`. See Also: Function equirectangular4 for more details, the available `options`, errors, restrictions and other, approximate or accurate distance functions.

### equirectangular4 (lat1, lon1, lat2, lon2, adjust=True, limit=45, wrap=False) |
Approximate 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)` with `distance2` in `degrees squared`. Raises: `LimitError` - The lat- or longitudinal delta exceeds the `-limit..limit` range and limiterrors is `True`. See Also: Local, flat earth approximation, functions equirectangular, 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_, 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, cosineLaw_, 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 (small) 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.

### excessCagnoli_ (a, b, c) |
Compute the spherical excess `E` of a (spherical) triangle using Cagnoli's (D.34) formula. 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 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'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 excessCagnoli_, 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 and 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 or 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, equirectangular, euclidean, flatPolar, haversine, thomas and 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 or 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, equirectangular, euclidean, flatPolar, haversine, thomas and 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, cosineLaw_, flatPolar_, 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, cosineLaw_, flatPolar_, 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 datum's or ellipsoid axes). Raises: `TypeError` - Invalid `radius`. See Also: Functions flatPolar_, 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, cosineLaw_, euclidean_, flatLocal_ / hubeny_, haversine_, thomas_ and vincentys_.

### hartzell (pov, los=False, 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 (`LatLon`, `Cartesian`, Ecef9Tuple or Vector3d). `los` - Line-Of-Sight, direction to earth (Los, Vector3d), `True` for the normal, plumb onto the surface or `False` or `None` to point to the center of the earth. `earth` - The earth model (Datum, Ellipsoid, Ellipsoid2, a_f2Tuple or a `scalar` earth radius in `meter`). `name_LatLon_and_kwds` - Optional `name="hartzell"` (`str`), class `LatLon=None` to return the intersection and optionally, additional `LatLon` keyword arguments, include the `datum` if different from and to convert from `earth`. Returns: The intersection (Vector3d, `pov`'s `cartesian type` or the given `LatLon` instance) with attribute `height` set to the distance to the `pov`. Raises: `IntersectionError` - Invalid `pov` or `pov` inside the earth or invalid `los` or `los` points outside or away from the earth. `TypeError` - Invalid `earth`, `ellipsoid` or `datum`. See Also: Class Los, functions tyr3d and hartzell4 and methods Ellipsoid.hartzell4, any `Cartesian.hartzell` and `LatLon.hartzell`.

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

### heightOrthometric (h_loc, N) |
Get the orthometric height H, the height above the geoid, earth surface. Arguments: `h_loc` - The height above the ellipsoid (`meter`) or an ellipsoidal location (`LatLon` or `Cartesian` with a `height` or `h` attribute), otherwise `0 meter`. `N` - The geoid height (`meter`), the height of the geoid above the ellipsoid at the same `h_loc` location. Returns: Orthometric height `H = h - N` (`meter`, same units as `h` and `N`). See Also: Ellipsoid, Geoid, and Orthometric Heights, page 6 and module pygeodesy.geoids.

### 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 `degrees360`). `lat2` - Latitude of the second point (`degrees`). `lon2` - Longitude of the second point (`degrees`). `bearing2` - Bearing at the second point (compass `degrees360`). `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: Intersection point (LatLon2Tuple`(lat, lon)`). Raises: `IntersectionError` - No or an ambiguous 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.

### 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)`. Both points are the same instance, aka the radical center if the circles are abutting 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` otherwise. 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_.

### normal (lat, lon, **name) |
Normalize a lat- and longitude pair in `degrees`. Arguments: `lat` - Latitude (`degrees`). `lon` - Longitude (`degrees`). `name` - Optional `name="normal"` (`str`). Returns: LatLon2Tuple`(lat, lon)` with `-90 <= lat <= 90` and `-180 <= 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="normal_"` (`str`). Returns: PhiLam2Tuple`(phi, lam)` with `abs(phi) <= PI/2` and `abs(lam) <= PI`. See Also: Functions normal and isnormal_.

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

### radical2 (distance, radius1, radius2, **name) |
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`). `name` - Optional `name=NN` (`str`). 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`.

### 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 or ellipsoid axes). Raises: `TypeError` - Invalid `datum`. See Also: Functions thomas_, 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 (Datum) ?or ellipsoid to use (Ellipsoid, Ellipsoid2 or a_f2Tuple). Returns: Angular distance (`radians`). Raises: `TypeError` - Invalid `datum`. See Also: Functions thomas, cosineLaw_, 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_, 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, cosineLaw_, 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).