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

# Module utily

Utility, geodetic/geometric functions and constants.

After (C) Chris Veness 2011-2015 published under the same MIT Licence**, see Latitude/Longitude and Vector-based geodesy.

Version: 18.09.25

Classes
| LimitError Error raised for lat- and/or longitudinal deltas exceeding the limit in functions equirectangular and equirectangular_.

Functions
degrees(x) Convert angle x from radians to degrees. |
radians(x) Convert angle x from degrees to radians. |
acos1(x) Return math.acos(max(-1, min(1, x))). |
anStr(name, OKd=`'``._-``'`, sub=`'``_``'`) Make string a valid name of alphanumeric and OKd characters. |
antipode(lat, lon) Return the antipode, the point diametrically opposite to the given lat- and longitude. |
degrees90(rad) Convert and wrap radians to degrees (-270..+90]. |
degrees180(rad) Convert and wrap radians to degrees (-180..+180]. |
degrees360(rad) Convert and wrap radians to degrees (0..+360]. |
enStr2(easting, northing, prec, *extras) Return easting, northing string representations. |
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. |
false2f(value, name=`'``value``'`, false=True) Convert a false east-/northing to non-negative float. |
ft2m(feet) Convert International feet to meter (m). |
halfs(str2) Split a string in 2 halfs. |
haversine(lat1, lon1, lat2, lon2, radius=6371008.77141, wrap=False) Compute the distance between two points using the Haversine formula. |
haversine_(a2, a1, b21) Compute the angular distance between two 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 anitpodal, on diametrically opposite sides of the earth. |
isNumpy2(obj) Check for an Numpy2LatLon points wrapper. |
isPoints2(obj) Check for an LatLon2psxy points wrapper. |
issequence(obj, *excluded) Check for sequence types. |
isTuple2(obj) Check for an Tuple2LatLon points wrapper. |
iterNumpy2(obj) Iterate over Numpy2 wrappers or other sequences exceeding the threshold. |
iterNumpy2over(n=None) Get or set the iterNumpy2 threshold. |
limiterrors(raiser=None) Get/set the raising of limit errors. |
m2degrees(meter, radius=6371008.77141) Convert distance to angle along equator. |
m2ft(meter) Convert meter to International feet (ft). |
m2km(meter) Convert meter to kilo meter (km). |
m2NM(meter) Convert meter to nautical miles (NM). |
m2SM(meter) Convert meter to statute miles (SM). |
polygon(points, closed=True, base=None) Check a polygon given as an array, list, sequence, set or tuple of points. |
property_RO(method) Decorator for `Read_Only` property. |
radiansPI(deg) Convert and wrap degrees to radians (-PI..+PI]. |
radiansPI2(deg) Convert and wrap degrees to radians (0..+2PI]. |
radiansPI_2(deg) Convert and wrap degrees to radians (-3PI/2..+PI/2]. |
tan_2(rad) Compute the tangent of half angle. |
tanPI_2_2(rad) Compute the tangent of half angle, 90 degrees rotated. |
unroll180(lon1, lon2, wrap=True) Unroll longitudinal delta and wrap longitude in degrees. |
unrollPI(rad1, rad2, wrap=True) Unroll longitudinal delta and wrap longitude in radians. |
unStr(name, *args, **kwds) Return the string representation of an invokation. |
wrap90(deg) Wrap degrees to (-270..+90]. |
wrap180(deg) Wrap degrees to (-180..+180]. |
wrap360(deg) Wrap degrees to (0..+360]. |
wrapPI(rad) Wrap radians to (-PI..+PI]. |
wrapPI2(rad) Wrap radians to (0..+2PI]. |
wrapPI_2(rad) Wrap radians to (-3PI/2..+PI/2]. |

Variables
| PI = `3.14159265359`
| PI2 = `6.28318530718` Two PI, PI * 2 (float) # PYCHOK expected
| PI_2 = `1.57079632679` Half PI, PI / 2 (float)
| R_M = `6371008.77141` Mean, spherical earth radius (meter).

Function Details

### anStr(name, OKd=`'``._-``'`, sub=`'``_``'`) |
Make string a valid name of alphanumeric and OKd characters. Parameters: `name` - The original name (str). `OKd` - Other acceptable characters (str). `sub` - Substitute for invalid charactes (str). Returns: The modified name (str). Note: Leading and trailing whitespace characters are removed and intermediate whitespace characters are coalesced and substituted.

### antipode(lat, lon) |
Return the antipode, the point diametrically opposite to the given lat- and longitude. Parameters: `lat` - Latitude (degrees). `lon` - Longitude (degrees). Returns: 2-Tuple (lat, lon) of the antipodal point (degrees, degrees180). See Also: Geosphere.

### degrees90(rad) |
Convert and wrap radians to degrees (-270..+90]. Parameters: `rad` - Angle (radians). Returns: Angle in degrees, wrapped (degrees90).

### degrees180(rad) |
Convert and wrap radians to degrees (-180..+180]. Parameters: `rad` - Angle (radians). Returns: Angle in degrees, wrapped (degrees180).

### degrees360(rad) |
Convert and wrap radians to degrees (0..+360]. Parameters: `rad` - Angle (radians). Returns: Angle in degrees, wrapped (degrees360).

### enStr2(easting, northing, prec, *extras) |
Return easting, northing string representations. Parameters: `easting` - Easting from false easting (meter). `northing` - Northing from from false northing (meter). `prec` - Precision in number of digits (int). `extras` - Optional leading items (strings). Returns: extras + 2-Tuple (eastingStr, northingStr). Raises: `ValueError` - Invalid prec.

### equirectangular(lat1, lon1, lat2, lon2, radius=6371008.77141, **options) |
Compute the distance between two points using the Equirectangular Approximation / Projection. See function equirectangular_ for more details, the available options and errors raised. Parameters: `lat1` - Start latitude (degrees). `lon1` - Start longitude (degrees). `lat2` - End latitude (degrees). `lon2` - End longitude (degrees). `radius` - Optional, mean earth radius (meter). `options` - Optional keyword arguments for function equirectangular_. Returns: Distance (meter, same units as radius). See Also: Local, flat earth approximation, function haversine, method Ellipsoid.distance2 and `LatLon` method `distanceTo*` for more accurate and/or larger distances.

### 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 smaller distance of several hundred Km or Miles, see the limit keyword argument and the LimitError. Parameters: `lat1` - Start latitude (degrees). `lon1` - Start longitude (degrees). `lat2` - End latitude (degrees). `lon2` - End longitude (degrees). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool). `limit` - Optional limit for the lat- and longitudinal deltas (degrees) or None or 0 for unlimited. `wrap` - Wrap and unroll180 longitudes and longitudinal delta (bool). Returns: 4-Tuple (distance2, delta_lat, delta_lon, lon2_unroll) with the distance in degrees squared, the latitudinal delta lat2-lat1, the wrapped, unrolled, and adjusted longitudinal delta lon2-lon1 and the unrollment for lon2. To convert distance2 to meter, use radians(sqrt(distance2)) * radius where radius is the mean earth radius in the desired units, for example R_M meter. 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 and haversine, method Ellipsoid.distance2 and `LatLon` method `distanceTo*` for more accurate and/or larger distances.

### false2f(value, name=`'``value``'`, false=True) |
Convert a false east-/northing to non-negative float. Parameters: `value` - Value to convert (scalar). `name` - Optional name of the value (string). `false` - Optionally, value includes false origin (bool). Returns: The value (float). Raises: `ValueError` - Invalid or negative value.

### ft2m(feet) |
Convert International feet to meter (m). Parameters: `feet` - Value in feet (scalar). Returns: Value in m (float).

### halfs(str2) |
Split a string in 2 halfs. Parameters: `str2` - String to split (string). Returns: 2-Tuple (1st, 2nd) half (strings). Raises: `ValueError` - Zero or odd len(str2).

### haversine(lat1, lon1, lat2, lon2, radius=6371008.77141, wrap=False) |
Compute the distance between two points using the Haversine formula. Parameters: `lat1` - Start latitude (degrees). `lon1` - Start longitude (degrees). `lat2` - End latitude (degrees). `lon2` - End longitude (degrees). `radius` - Optional, mean earth radius (meter). `wrap` - Wrap and unrollPI longitudes (bool). Returns: Distance (meter, same units as radius). See Also: Distance between two (spherical) points, function equirectangular. Ellipsoid.distance2 or LatLon methods distanceTo* and equirectangular.

### haversine_(a2, a1, b21) |
Compute the angular distance between two points using the Haversine formula. Parameters: `a2` - End latitude (radians). `a1` - Start latitude (radians). `b21` - Longitudinal delta, end-start (radians). Returns: Angular distance (radians). See Also: Function haversine.

### heightOf(angle, distance, radius=6371008.77141) |
Determine the height above the (spherical) earth after traveling along a straight line at a given tilt. Parameters: `angle` - Tilt angle above horizontal (degrees). `distance` - Distance along the line (meter or same units as radius). `radius` - Optional mean earth radius (meter). Returns: Height (meter, same units as distance and radius). Raises: `ValueError` - Invalid angle, distance or radius. See Also: MultiDop GeogBeamHt (Shapiro et al. 2009, JTECH and Potvin et al. 2012, JTECH).

### horizon(height, radius=6371008.77141, refraction=False) |
Determine the distance to the horizon from a given altitude above the (spherical) earth. Parameters: `height` - Altitude (meter or same units as radius). `radius` - Optional mean earth radius (meter). `refraction` - Consider atmospheric refraction (bool). Returns: Distance (meter, same units as height and radius). Raises: `ValueError` - Invalid height or radius. See Also: Distance to horizon.

### isantipode(lat1, lon1, lat2, lon2, eps=2.22044604925e-16) |
Check whether two points are anitpodal, on diametrically opposite sides of the earth. Parameters: `lat1` - Latitude of one point (degrees). `lon1` - Longitude of one point (degrees). `lat2` - Latitude of the other point (degrees). `lon2` - Longitude of the other point (degrees). `eps` - Tolerance for near-equality (degrees). Returns: True if points are antipodal within the given tolerance, False otherwise. See Also: Geosphere.

### isNumpy2(obj) |
Check for an Numpy2LatLon points wrapper. Parameters: `obj` - The object (any). Returns: True if obj is an Numpy2LatLon instance, False otherwise (bool).

### isPoints2(obj) |
Check for an LatLon2psxy points wrapper. Parameters: `obj` - The object (any). Returns: True if obj is an LatLon2psxy instance, False otherwise (bool).

### issequence(obj, *excluded) |
Check for sequence types. Parameters: `obj` - The object (any). `excluded` - Optional, exclusions (types). Returns: True if obj is a sequence (bool). Note: Excluding tuple implies namedtuple.

### isTuple2(obj) |
Check for an Tuple2LatLon points wrapper. Parameters: `obj` - The object (any). Returns: True if obj is an Tuple2LatLon instance, False otherwise (bool).

### iterNumpy2(obj) |
Iterate over Numpy2 wrappers or other sequences exceeding the threshold. Parameters: `obj` - Points array, list, sequence, set, etc. (any). Returns: True, do iterate (bool).

### iterNumpy2over(n=None) |
Get or set the iterNumpy2 threshold. Parameters: `n` - Optional, new threshold (integer). Returns: Previous threshold (integer). Raises: `ValueError` - Invalid n.

### limiterrors(raiser=None) |
Get/set the raising of limit errors. Parameters: `raiser` - Choose True to raise or False to not raise LimitError exceptions. Use None to leave the setting unchanged. Returns: Previous setting (bool).

### m2degrees(meter, radius=6371008.77141) |
Convert distance to angle along equator. Parameters: `meter` - Value in meter (scalar). Returns: Value in degrees (float). Raises: `ValueError` - Invalid radius.

### m2ft(meter) |
Convert meter to International feet (ft). Parameters: `meter` - Value in meter (scalar). Returns: Value in ft (float).

### m2km(meter) |
Convert meter to kilo meter (km). Parameters: `meter` - Value in meter (scalar). Returns: Value in km (float).

### m2NM(meter) |
Convert meter to nautical miles (NM). Parameters: `meter` - Value in meter (scalar). Returns: Value in NM (float).

### m2SM(meter) |
Convert meter to statute miles (SM). Parameters: `meter` - Value in meter (scalar). Returns: Value in SM (float).

### polygon(points, closed=True, base=None) |
Check a polygon given as an array, list, sequence, set or tuple of points. Parameters: `points` - The points of the polygon (LatLon[]) `closed` - Optionally, treat polygon as closed and remove any duplicate or closing final points (bool). `base` - Optional points base class (None). Returns: 2-Tuple (number, sequence) of points (int, sequence). Raises: `TypeError` - Some points are not LatLon. `ValueError` - Insufficient number of points.

### property_RO(method) |
Decorator for `Read_Only` property. Parameters: `method` - The callable to be decorated as `property.getter`. Note: Like standard Python `property` without a `property.setter` with a more descriptive error message when set.

### radiansPI(deg) |
Convert and wrap degrees to radians (-PI..+PI]. Parameters: `deg` - Angle (degrees). Returns: Radians, wrapped (radiansPI)

### radiansPI2(deg) |
Convert and wrap degrees to radians (0..+2PI]. Parameters: `deg` - Angle (degrees). Returns: Radians, wrapped (radiansPI2)

### radiansPI_2(deg) |
Convert and wrap degrees to radians (-3PI/2..+PI/2]. Parameters: `deg` - Angle (degrees). Returns: Radians, wrapped (radiansPI_2)

### tan_2(rad) |
Compute the tangent of half angle. Parameters: `rad` - Angle (radians). Returns: tan(rad / 2) (float).

### tanPI_2_2(rad) |
Compute the tangent of half angle, 90 degrees rotated. Parameters: `rad` - Angle (radians). Returns: tan((rad + PI/2) / 2) (float).

### unroll180(lon1, lon2, wrap=True) |
Unroll longitudinal delta and wrap longitude in degrees. Parameters: `lon1` - Start longitude (degrees). `lon2` - End longitude (degrees). `wrap` - Wrap and unroll to the (-180..+180] range (bool). Returns: 2-Tuple (delta lon2-lon1, lon2) unrolled (degrees, degrees). See Also: Capability LONG_UNROLL in GeographicLib.

### unrollPI(rad1, rad2, wrap=True) |
Unroll longitudinal delta and wrap longitude in radians. Parameters: `rad1` - Start longitude (radians). `rad2` - End longitude (radians). `wrap` - Wrap and unroll to the (-PI..+PI] range (bool). Returns: 2-Tuple (delta rad2-rad1, rad2) unrolled (radians, radians). See Also: Capability LONG_UNROLL in GeographicLib.

### unStr(name, *args, **kwds) |
Return the string representation of an invokation. Parameters: `name` - Function, method or class name (string). `args` - Optional positional arguments (tuple). `kwds` - Optional keyword arguments (dict). Returns: Representation (string).

### wrap90(deg) |
Wrap degrees to (-270..+90]. Parameters: `deg` - Angle (degrees). Returns: Degrees, wrapped (degrees90).

### wrap180(deg) |
Wrap degrees to (-180..+180]. Parameters: `deg` - Angle (degrees). Returns: Degrees, wrapped (degrees180).

### wrap360(deg) |
Wrap degrees to (0..+360]. Parameters: `deg` - Angle (degrees). Returns: Degrees, wrapped (degrees360).

### wrapPI(rad) |
Wrap radians to (-PI..+PI]. Parameters: `rad` - Angle (radians). Returns: Radians, wrapped (radiansPI).

### wrapPI2(rad) |
Wrap radians to (0..+2PI]. Parameters: `rad` - Angle (radians). Returns: Radians, wrapped (radiansPI2).

### wrapPI_2(rad) |
Wrap radians to (-3PI/2..+PI/2]. Parameters: `rad` - Angle (radians). Returns: Radians, wrapped (radiansPI_2).