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

Module utils

Utility and mathematical functions and constants.

After (C) Chris Veness 2011-2015 published under the same MIT Licence**, see http://www.movable-type.co.uk/scripts/latlong.html and http://www.movable-type.co.uk/scripts/latlong-vectors.html.


Version: 17.11.30

Classes
  CrossError
Error for zero cross product or coincident or colinear points or paths.
Functions
 
degrees(x)
Convert angle x from radians to degrees.
 
hypot(x, y)
Return the Euclidean distance, sqrt(x*x + y*y).
 
radians(x)
Convert angle x from degrees to radians.
 
cbrt(x)
Compute the cubic root x**(1/3).
 
cbrt2(x)
Compute the cubic root squared x**(2/3).
 
classname(obj)
Build module.class name of this object.
 
crosserrors(raiser=None)
Get/set cross product exceptions.
 
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.
 
equirectangular(lat1, lon1, lat2, lon2, radius=6371008.77141, **options)
Compute the distance between two points using the Equirectangular Approximation/Projection.
 
equirectangular3(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.
 
favg(v1, v2, f=0.5)
Return the weighted average of two values.
 
fdot(a, *b)
Return the precision dot product sum(a[i] * b[i] for i in range(len(a))).
 
fdot3(a, b, c, start=0)
Return the precision dot product sum(a[i] * b[i] * c[i] for i in range(len(a))) + start.
 
fmean(floats)
Compute the mean of float values.
 
fpolynomial(x, *cs)
Evaluate the polynomial sum(cs[i] * x**i), i=0..len(cs)).
 
fStr(floats, prec=6, sep=', ', fmt='%.*f', ints=False)
Convert floats to string, optionally with trailing zero decimals stripped.
 
fStrzs(fstr)
Strip trailing zero decimals from a float string.
 
fsum(iterable)
Return an accurate floating point sum of values in the iterable.
 
ft2m(feet)
Convert feet to meter (m).
 
halfs(str2)
Split a string in 2 halfs.
 
haversine(lat1, lon1, lat2, lon2, radius=6371008.77141)
Compute the distance between two points using the Haversine formula.
 
haversine_(a2, a1, b21)
Compute the angular distance using the Haversine formula.
 
hypot1(x)
Compute the norm sqrt(1 + x**2).
 
hypot3(x, y, z)
Compute the norm sqrt(x**2 + y**2 + z**2).
 
inStr(inst, *args, **kwds)
Return the string representation of an instance.
 
isfinite(obj)
Check for Inf and NaN values.
 
isint(obj, both=False)
Check for integer type or integer value.
 
isNumpy2(obj)
Check for Numpy2LatLon points wrapper.
 
isscalar(obj)
Check for scalar types.
 
issequence(obj, *excluded)
Check for sequence types.
 
isTuple2(obj)
Check for Tuple2LatLon points wrapper.
 
iterNumpy2(obj)
Iterate over Numpy2 wrappers or other sequences exceeding the threshold.
 
iterNumpy2over(n=None)
Get or set the iterNumpy2 threshold.
 
len2(seq)
Make built-in function len work for generators, iterators, etc.
 
m2ft(meter)
Convert meter to 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).
 
map1(func, *args)
Apply each argument to a single-argument function and return a tuple of results.
 
map2(func, *args)
Apply arguments to a function and return a tuple of results.
 
polygon(points, closed=True, base=None)
Check a polygon given as an array, list, sequence, set or tuple of points.
 
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.
 
scalar(value, low=2.22044604925e-16, high=1.0, name='scalar')
Validate a scalar.
 
tan_2(rad)
Compute the tangent of half angle.
 
tanPI_2_2(rad)
Compute the tangent of half angle, 90 degrees rotated.
 
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
  EPS = 2.22044604925e-16
Approximate epsilon (float)
  EPS1 = 1.0
1.0 - EPS (float), about 0.9999999999999998
  EPS2 = 1.49011611938e-08
sqrt(EPS) (float)
  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

cbrt(x)

 

Compute the cubic root x**(1/3).

Parameters:
  • x - Value (scalar).
Returns:
Cubic root (float).

cbrt2(x)

 

Compute the cubic root squared x**(2/3).

Parameters:
  • x - Value (scalar).
Returns:
Cubic root squared (float).

classname(obj)

 

Build module.class name of this object.

Parameters:
  • obj - The object (any type).
Returns:
Name of module and class (string).

crosserrors(raiser=None)

 

Get/set cross product exceptions.

Parameters:
  • raiser - New on or off setting (bool).
Returns:
Previous setting (bool).

degrees90(rad)

 

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

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

degrees180(rad)

 

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

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

degrees360(rad)

 

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

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

equirectangular(lat1, lon1, lat2, lon2, radius=6371008.77141, **options)

 

Compute the distance between two points using the Equirectangular Approximation/Projection.

See function equirectangular3 for details and options.

Parameters:
  • lat1 - Latitude1 (degrees).
  • lon1 - Longitude1 (degrees).
  • lat2 - Latitude2 (degrees).
  • lon2 - Longitude2 (degrees).
  • radius - Optional, mean earth radius (meter).
  • options - Optional keyword arguments for function equirectangular3.
Returns:
Distance (meter), rather the units of radius.
Raises:

See Also: Function haversine for more accurate or larger distances.

equirectangular3(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 ValueError.

Parameters:
  • lat1 - Latitude1 (degrees).
  • lon1 - Longitude1 (degrees).
  • lat2 - Latitude2 (degrees).
  • lon2 - Longitude2 (degrees).
  • adjust - Optionally, adjust longitudinal delta by the cosine of the mean of the latitudes (bool).
  • limit - Optional limit for the deltas (degrees) or 0 for unlimited.
  • wrap - Optionally, keep the longitudinal delta within the -180..+180 range (bool).
Returns:
3-Tuple (distance2, delta_lat, delta_lon) with the distance in degrees squared, the latitudinal delta lat2-lat1 and the adjusted, wrapped longitudinal delta lon2-lon1. 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 in meter.
Raises:
  • ValueError - The lat- and/or longitudinal delta exceeds the limit. Use limit=0 to avoid the delta check and ValueError.

See Also: Function equirectangular for distance only and function haversine for more accurate 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.

favg(v1, v2, f=0.5)

 

Return the weighted average of two values.

Parameters:
  • v1 - One value (scalar).
  • v2 - Other value (scalar).
  • f - Optional fraction (scalar).
Returns:
v1 + f * (v2 - v1) (float).

fdot(a, *b)

 

Return the precision dot product sum(a[i] * b[i] for i in range(len(a))).

Parameters:
  • a - List, sequence, tuple, etc. (scalars).
  • b - List, sequence, tuple, etc. (scalars).
Returns:
Dot product (float).
Raises:
  • ValueError - Unequal len(a) and len(b).

fdot3(a, b, c, start=0)

 

Return the precision dot product sum(a[i] * b[i] * c[i] for i in range(len(a))) + start.

Parameters:
  • a - List, sequence, tuple, etc. (scalars).
  • b - List, sequence, tuple, etc. (scalars).
  • c - List, sequence, tuple, etc. (scalars).
  • start - Optional bias (scalar).
Returns:
Dot product (float).
Raises:
  • ValueError - Unequal len(a), len(b) and/or len(c).

fmean(floats)

 

Compute the mean of float values.

Parameters:
  • floats - Values (float).
Returns:
Mean value (float).
Raises:
  • ValueError - No floats.

fpolynomial(x, *cs)

 

Evaluate the polynomial sum(cs[i] * x**i), i=0..len(cs)).

Parameters:
  • x - Polynomial argument (scalar).
  • cs - Polynomial coeffients (scalars).
Returns:
Polynomial value (float).
Raises:
  • TypeError - Argument not scalar.
  • ValueError - No coefficients.

fStr(floats, prec=6, sep=', ', fmt='%.*f', ints=False)

 

Convert floats to string, optionally with trailing zero decimals stripped.

Parameters:
  • floats - List, sequence, tuple, etc. (scalars).
  • prec - Optional precision, number of decimal digits (0..9). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
  • sep - Optional, separator to join (string).
  • fmt - Optional, float format (string).
  • ints - Optionally, remove decimal dot (bool).
Returns:
The floats as 'f, f, ... f' (string).

fStrzs(fstr)

 

Strip trailing zero decimals from a float string.

Parameters:
  • fstr - Float (string).
Returns:
Float (string).

fsum(iterable)

 

Return an accurate floating point sum of values in the iterable. Assumes IEEE-754 floating point arithmetic.

ft2m(feet)

 

Convert 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) halfs (strings).
Raises:
  • ValueError - Zero or odd len(str2).

haversine(lat1, lon1, lat2, lon2, radius=6371008.77141)

 

Compute the distance between two points using the Haversine formula.

Parameters:
  • lat1 - Latitude1 (degrees).
  • lon1 - Longitude1 (degrees).
  • lat2 - Latitude2 (degrees).
  • lon2 - Longitude2 (degrees).
  • radius - Optional, mean earth radius (meter).
Returns:
Distance (meter, same units as radius).

See Also: Distance between two points and function equirectangular3 for an approximation.

haversine_(a2, a1, b21)

 

Compute the angular distance using the Haversine formula.

Parameters:
  • a2 - Latitude2 (radians).
  • a1 - Latitude1 (radians).
  • b21 - Longitudinal delta (radians).
Returns:
Angular distance (radians).

See Also: This Distance between two points, function haversine.

hypot1(x)

 

Compute the norm sqrt(1 + x**2).

Parameters:
  • x - Argument (scalar).
Returns:
Norm (float).

hypot3(x, y, z)

 

Compute the norm sqrt(x**2 + y**2 + z**2).

Parameters:
  • x - X argument (scalar).
  • y - Y argument (scalar).
  • z - Z argument (scalar).
Returns:
Norm (float).

inStr(inst, *args, **kwds)

 

Return the string representation of an instance.

Parameters:
  • inst - The instance (any type).
  • args - Optional positional arguments (tuple).
  • kwds - Optional keyword arguments (dict).
Returns:
Representation (string).

isfinite(obj)

 

Check for Inf and NaN values.

Parameters:
  • obj - Value (scalar).
Returns:
False if Inf or NaN, True otherwise (bool).
Raises:
  • TypeError - Value not scalar.

isint(obj, both=False)

 

Check for integer type or integer value.

Parameters:
  • obj - The object (any).
  • both - Optionally, check both type and value (bool).
Returns:
True if obj is integer (bool).

isNumpy2(obj)

 

Check for Numpy2LatLon points wrapper.

Parameters:
  • obj - The object (any).
Returns:
True if obj is Numpy2 (bool).

isscalar(obj)

 

Check for scalar types.

Parameters:
  • obj - The object (any).
Returns:
True if obj is scalar (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 Tuple2LatLon points wrapper.

Parameters:
  • obj - The object (any).
Returns:
True if obj is Tuple2 (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).

len2(seq)

 

Make built-in function len work for generators, iterators, etc. since those can only be started once.

Parameters:
  • seq - Generator, iterator, list, range, tuple, etc.
Returns:
2-Tuple (number, list) of items (int, list).

m2ft(meter)

 

Convert meter to 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).

map1(func, *args)

 

Apply each argument to a single-argument function and return a tuple of results.

Parameters:
  • func - Function to apply (callable).
  • args - Arguments to apply (any).
Returns:
Function results (tuple).

map2(func, *args)

 

Apply arguments to a function and return a tuple of results.

Unlike Python 2 built-in map, Python 3+ map returns a map object, an iterator-like object which generates the results only once. Converting the map object to a tuple maintains Python 2 behavior.

Parameters:
  • func - Function to apply (callable).
  • args - Arguments to apply (list, tuple, ...).
Returns:
N-Tuple of function results (tuple).

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 - Too few points.

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)

scalar(value, low=2.22044604925e-16, high=1.0, name='scalar')

 

Validate a scalar.

Parameters:
  • value - The value (scalar).
  • low - Optional lower bound (scalar).
  • high - Optional upper bound (scalar).
  • name - Optional name of value (string).
Returns:
New value (type(low)).
Raises:
  • TypeError - Value not scalar.
  • ValueError - Value out of bounds.

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

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