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

Classes
  CrossError
Error for zero cross product or coincident or colinear points.
Functions
 
fsum(iterable)
Return an accurate floating point sum of values in the iterable.
 
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.
 
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.
 
ft2m(feet)
Convert feet to meter (m).
 
halfs(str2)
Split a string in 2 halfs.
 
hsin(rad)
Compute the Haversine value of an angle.
 
hsin3(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.
 
isint(obj, both=False)
Check for integer type or integer value.
 
isNumpy2(obj)
Check for Numpy2 wrapper.
 
isscalar(obj)
Check for scalar types.
 
issequence(obj, *excluded)
Check for sequence types.
 
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)
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

fsum(iterable)

 

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

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

false2f(value, name='value', false=True)

 

Convert a false east-/northing to non-negative float.

Parameters:
  • value - Value to convert (scalar).
  • name - Name of the value (string).
  • false - Value must include 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 - 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).

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

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

hsin(rad)

 

Compute the Haversine value of an angle.

Parameters:
  • rad - Angle (radians).
Returns:
sin(rad / 2)**2 (float).

hsin3(a2, a1, b21)

 

Compute the angular distance using the Haversine formula.

Parameters:
  • a2 - Latitude2 (radians).
  • a1 - Latitude1 (radians).
  • b21 - Longitude delta (radians).
Returns:
3-Tuple (angle, cos(a2), cos(a1)).

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

isint(obj, both=False)

 

Check for integer type or integer value.

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

isNumpy2(obj)

 

Check for Numpy2 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.

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 - Treat polygon as closed and remove any duplicate or closing final points (bool).
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)

 

Validate a scalar.

Parameters:
  • value - The value (scalar).
  • low - Optional lower bound (scalar).
  • high - Optional upper bound (scalar).
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).