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

Module utily

Geometric and other utility functions and constants.

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


Version: 19.10.29

Classes
  LimitError
Error raised for lat- 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 a valid name of alphanumeric and OKd characters.
 
clipStr(bstr, limit=50, white='')
Clip a string to the given length limit.
 
degrees90(rad)
Convert radians to degrees and wrap [-270..+90].
 
degrees180(rad)
Convert radians to degrees and wrap [-180..+180].
 
degrees360(rad)
Convert radians to degrees and wrap [0..+360).
 
degrees2m(deg, radius=6371008.77141, lat=0)
Convert angle to distance along the equator or along a parallel at an other latitude.
 
enStr2(easting, northing, prec, *extras)
Return easting, northing string representations.
 
false2f(value, name='value', false=True, Error=<type 'exceptions.ValueError'>)
Convert a false east-/northing to non-negative float.
 
ft2m(feet, usurvey=False)
Convert International or US Survey feet to meter.
 
halfs2(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.
 
issubclassof(sub, sup)
Check whether a class is a subclass of a super class.
 
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, usurvey=False)
Convert meter to International or US Survey 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).
 
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].
 
sincos2(*rad)
Return the sine and cosine of angle(s).
 
sincos2d(*deg)
Return the sine and cosine of an angle.
 
splice(iterable, n=2, fill=object())
Split an iterable into n slices.
 
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
  __all__ = _ALL_LAZY.utily
  OK = 'OK'
  PI2 = 6.28318530718
Two PI, PI * 2 aka Tau (float) # PYCHOK expected
  PI_2 = 1.57079632679
Half PI, PI / 2 (float)
  PI_4 = 0.785398163397
Quarter PI, PI / 4 (float)
  R_M = 6371008.77141
Mean, spherical earth radius (meter).
Function Details

anStr(name, OKd='._-', sub='_')

 

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

clipStr(bstr, limit=50, white='')

 

Clip a string to the given length limit.

Parameters:
  • bstr - String (bytes or str).
  • limit - Length limit (int).
  • white - Whitespace replacement (str).
Returns:
Un/-clipped bstr.

degrees90(rad)

 

Convert radians to degrees and wrap [-270..+90].

Parameters:
  • rad - Angle (radians).
Returns:
Angle in degrees, wrapped (degrees90).

degrees180(rad)

 

Convert radians to degrees and wrap [-180..+180].

Parameters:
  • rad - Angle (radians).
Returns:
Angle in degrees, wrapped (degrees180).

degrees360(rad)

 

Convert radians to degrees and wrap [0..+360).

Parameters:
  • rad - Angle (radians).
Returns:
Angle in degrees, wrapped (degrees360).

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

 

Convert angle to distance along the equator or along a parallel at an other latitude.

Parameters:
  • deg - Angle (degrees).
  • radius - Mean earth radius (meter).
  • lat - Parallel latitude (degrees90).
Returns:
Distance (meter, same units as radius).
Raises:

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, Error=<type 'exceptions.ValueError'>)

 

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).
  • Error - Exception to raise (ValueError).
Returns:
The value (float).
Raises:
  • Error - Invalid or negative value.

ft2m(feet, usurvey=False)

 

Convert International or US Survey feet to meter.

Parameters:
  • feet - Value in feet (scalar).
  • usurvery - Convert US Survey feet (bool), International feet otherwise.
Returns:
Value in meter (float).

halfs2(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.

issubclassof(sub, sup)

 

Check whether a class is a subclass of a super class.

Parameters:
  • sub - The sub class (class).
  • sup - The super class (class).
Returns:
True if sub is a subclass of sup.

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 throw 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, usurvey=False)

 

Convert meter to International or US Survey feet (ft).

Parameters:
  • meter - Value in meter (scalar).
  • usurvery - Convert to US Survey feet (bool), International feet otherwise.
Returns:
Value in feet (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).

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)

sincos2(*rad)

 

Return the sine and cosine of angle(s).

Parameters:
  • rad - One or more angles (radians).
Returns:
The sin(rad) and cos(rad) for each angle.

See Also: GeographicLib function sincosd and C++ sincosd.

sincos2d(*deg)

 

Return the sine and cosine of an angle.

Parameters:
  • deg - One or more angles (degrees).
Returns:
The sin(rad) and cos(rad) for each angle.

See Also: GeographicLib function sincosd and C++ sincosd.

splice(iterable, n=2, fill=object())

 

Split an iterable into n slices.

Parameters:
  • iterable - Items to be spliced (list, tuple, ...).
  • n - Number of slices to generate (int).
  • fill - Fill value for missing items.
Returns:
Generator of n slices iterable[i::n] for i=0..n.
Raises:
  • ValueError - Non-int or non-positive n.

Note: Each generated slice is a tuple or a list, the latter only if the iterable is a list.

Example:

>>> from pygeodesy import splice
>>> a, b = splice(range(10))
>>> a, b
((0, 2, 4, 6, 8), (1, 3, 5, 7, 9))
>>> a, b, c = splice(range(10), n=3)
>>> a, b, c
((0, 3, 6, 9), (1, 4, 7], [2, 5, 8))
>>> a, b, c = splice(range(10), n=3, fill=-1)
>>> a, b, c
((0, 3, 6, 9), (1, 4, 7, -1), (2, 5, 8, -1))
>>> list(splice(range(12), n=5))
[(0, 5, 10), (1, 6, 11), (2, 7), (3, 8), (4, 9)]
>>> splice(range(9), n=1)
<generator object splice at 0x0...>

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