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

Module utils

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

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

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, method Ellipsoid.distance2 or function haversine 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, method Ellipsoid.distance2, function equirectangular for distance only and function haversine for 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 and function equirectangular or method Ellipsoid.distance2 for distance approximations.

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.

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