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

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.
 
anStr(name, OKd='._-', sub='_')
Make string a valid name of alphanumeric and OKd characters.
 
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].
 
degrees2m(deg, radius=6371008.77141, lat=0)
Convert angle to distance along equator.
 
enStr2(easting, northing, prec, *extras)
Return easting, northing string representations.
 
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.
 
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).
 
points2(points, closed=True, base=None)
Check a polygon represented by points.
 
polygon(points, closed=True, base=None)
DEPRECATED, use function points2.
 
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.

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

degrees2m(deg, radius=6371008.77141, lat=0)

 

Convert angle to distance along equator.

Parameters:
  • deg - Angle (degrees).
  • radius - Mean earth radius (meter).
  • lat - Latitude adjusting the distance (degrees90).
Returns:
Distance (meter, same units as radius).
Raises:
  • RangeError - Latitude lat outside valid range and rangerrrors set to True.

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.

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 (str).
  • 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 (str).
Returns:
2-Tuple (1st, 2nd) half (str).
Raises:
  • ValueError - Zero or odd len(str2).

isNumpy2(obj)

 

Check for an Numpy2LatLon points wrapper.

Parameters:
  • obj - The object (any type).
Returns:
True if obj is an Numpy2LatLon instance, False otherwise.

isPoints2(obj)

 

Check for an LatLon2psxy points wrapper.

Parameters:
  • obj - The object (any type).
Returns:
True if obj is an LatLon2psxy instance, False otherwise.

issequence(obj, *excluded)

 

Check for sequence types.

Parameters:
  • obj - The object (any type).
  • excluded - Optional, exclusions (type).
Returns:
True if obj is a sequence, False otherwise.

Note: Excluding tuple implies excluding namedtuple.

isTuple2(obj)

 

Check for an Tuple2LatLon points wrapper.

Parameters:
  • obj - The object (any).
Returns:
True if obj is an Tuple2LatLon instance, False otherwise.

iterNumpy2(obj)

 

Iterate over Numpy2 wrappers or other sequences exceeding the threshold.

Parameters:
  • obj - Points array, list, sequence, set, etc. (any).
Returns:
True do, False don't iterate.

iterNumpy2over(n=None)

 

Get or set the iterNumpy2 threshold.

Parameters:
  • n - Optional, new threshold (int).
Returns:
Previous threshold (int).
Raises:
  • ValueError - Invalid n.

limiterrors(raiser=None)

 

Get/set the raising of limit errors.

Parameters:
  • raiser - Choose True to raise or False to ignore 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 - Distance (meter, same units as radius).
  • radius - Mean earth radius (meter).
Returns:
Angle (degrees).
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).

points2(points, closed=True, base=None)

 

Check a polygon represented by points.

Parameters:
  • points - The polygon points (LatLon[])
  • closed - Optionally, consider the polygon closed, ignoring any duplicate or closing final points (bool).
  • base - Optionally, check the points against this base class None.
Returns:
2-Tuple (n, points) with the number (int) of points and the points list or tuple.
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 (str).
  • args - Optional positional arguments.
  • kwds - Optional keyword arguments.
Returns:
Representation (str).

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