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: 21.01.14

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))).
 
acre2ha(acres)
Convert acres to hectare.
 
acre2m2(acres)
Convert acres to square meter.
 
asin1(x)
Return math.asin(max(-1, min(1, x))).
 
atand(y_x)
Return atan(y_x) angle in degrees.
 
atan2b(y, x)
Return atan2(y, x) in degrees [0..+360].
 
atan2d(y, x)
Return atan2(y, x) in degrees [-180..+180].
 
chain2m(chains)
Convert UK chains to meter.
 
circle4(earth, lat)
Get the equatorial or a parallel circle of latitude.
 
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 an angle to a distance along the equator or along the parallel at an other (geodetic) latitude.
 
fathom2m(fathoms)
Convert UK fathom to meter.
 
ft2m(feet, usurvey=False)
Convert International or US Survey feet to meter.
 
furlong2m(furlongs)
Convert a UK furlong to meter.
 
isNumpy2(obj)
Check for an Numpy2LatLon points wrapper.
 
isPoints2(obj)
Check for an LatLon2psxy points wrapper.
 
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.
 
m2degrees(distance, radius=6371008.77141, lat=0)
Convert a distance to an angle along the equator or along the parallel at an other (geodetic) latitude.
 
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).
 
m2radians(distance, radius=6371008.77141, lat=0)
Convert a distance to an angle along the equator or along the parallel at an other (geodetic) latitude.
 
m2SM(meter)
Convert meter to statute miles (SM).
 
m2yard(meter)
Convert meter to UK yards.
 
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].
 
radians2m(rad, radius=6371008.77141, lat=0)
Convert an angle to a distance along the equator or along the parallel at an other (geodetic) latitude.
 
sincos2(*rad)
Return the sine and cosine of angle(s).
 
sincos2d(*deg)
Return the sine and cosine of angle(s) in degrees.
 
splice(iterable, n=2, **fill)
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.
 
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].
 
yard2m(yards)
Convert UK yards to meter.
Variables
  __all__ = _ALL_LAZY.utily
Function Details

acre2ha (acres)

 

Convert acres to hectare.

Arguments:
  • acres - Value in acres (scalar).
Returns:
Value in hectare (float).
Raises:
  • ValueError - Invalid acres.

acre2m2 (acres)

 

Convert acres to square meter.

Arguments:
  • acres - Value in acres (scalar).
Returns:
Value in meter^2 (float).
Raises:
  • ValueError - Invalid acres.

atand (y_x)

 

Return atan(y_x) angle in degrees.

See Also: Function atan2d.

atan2b (y, x)

 

Return atan2(y, x) in degrees [0..+360].

See Also: Function atan2d.

atan2d (y, x)

 

Return atan2(y, x) in degrees [-180..+180].

See Also: Karney's C++ function Math.atan2d.

chain2m (chains)

 

Convert UK chains to meter.

Arguments:
  • chains - Value in chains (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid chains.

circle4 (earth, lat)

 

Get the equatorial or a parallel circle of latitude.

Arguments:
Returns:
A Circle4Tuple(radius, height, lat, beta) instance.
Raises:
  • RangeError - Latitude lat outside valid range and rangerrors set to True.
  • TypeError - Invalid earth.
  • ValueError - earth or lat.

degrees90 (rad)

 

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

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

degrees180 (rad)

 

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

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

degrees360 (rad)

 

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

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

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

 

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

Arguments:
  • deg - The angle (degrees).
  • radius - Mean earth radius, ellipsoid or datum (meter, Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
  • lat - Parallel latitude (degrees90, str).
Returns:
Distance (meter, same units as radius or ellipsoidal and polar radii) or 0 for near-polar lat.
Raises:
  • RangeError - Latitude lat outside valid range and rangerrors set to True.
  • TypeError - Invalid radius.
  • ValueError - Invalid deg, radius or lat.

See Also: Function radians2m and m2degrees.

fathom2m (fathoms)

 

Convert UK fathom to meter.

Arguments:
  • fathoms - Value in fathoms (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid fathoms.

ft2m (feet, usurvey=False)

 

Convert International or US Survey feet to meter.

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

furlong2m (furlongs)

 

Convert a UK furlong to meter.

Arguments:
  • furlongs - Value in furlongs (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid furlongs.

isNumpy2 (obj)

 

Check for an Numpy2LatLon points wrapper.

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

isPoints2 (obj)

 

Check for an LatLon2psxy points wrapper.

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

isTuple2 (obj)

 

Check for an Tuple2LatLon points wrapper.

Arguments:
  • 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.

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

iterNumpy2over (n=None)

 

Get or set the iterNumpy2 threshold.

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

m2degrees (distance, radius=6371008.77141, lat=0)

 

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

Arguments:
  • distance - Distance (meter, same units as radius).
  • radius - Mean earth radius, ellipsoid or datum (meter, an Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
  • lat - Parallel latitude (degrees90, str).
Returns:
Angle (degrees) or INF for near-polar lat.
Raises:
  • RangeError - Latitude lat outside valid range and rangerrors set to True.
  • TypeError - Invalid radius.
  • ValueError - Invalid distance, radius or lat.

See Also: Function m2radians and degrees2m.

m2ft (meter, usurvey=False)

 

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

Arguments:
  • meter - Value in meter (scalar).
  • usurvery - Convert to US Survey feet (bool), International feet otherwise.
Returns:
Value in feet (float).
Raises:
  • ValueError - Invalid meter.

m2km (meter)

 

Convert meter to kilo meter (km).

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in km (float).
Raises:
  • ValueError - Invalid meter.

m2NM (meter)

 

Convert meter to nautical miles (NM).

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in NM (float).
Raises:
  • ValueError - Invalid meter.

m2radians (distance, radius=6371008.77141, lat=0)

 

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

Arguments:
  • distance - Distance (meter, same units as radius).
  • radius - Mean earth radius, ellipsoid or datum (meter, an Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
  • lat - Parallel latitude (degrees90, str).
Returns:
Angle (radians) or INF for near-polar lat.
Raises:
  • RangeError - Latitude lat outside valid range and rangerrors set to True.
  • TypeError - Invalid radius.
  • ValueError - Invalid distance, radius or lat.

See Also: Function m2degrees and radians2m.

m2SM (meter)

 

Convert meter to statute miles (SM).

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in SM (float).
Raises:
  • ValueError - Invalid meter.

m2yard (meter)

 

Convert meter to UK yards.

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in yards (float).
Raises:
  • ValueError - Invalid meter.

radiansPI (deg)

 

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

Arguments:
  • deg - Angle (degrees).
Returns:
Radians, wrapped (radiansPI)

radiansPI2 (deg)

 

Convert and wrap degrees to radians [0..+2PI).

Arguments:
  • deg - Angle (degrees).
Returns:
Radians, wrapped (radiansPI2)

radiansPI_2 (deg)

 

Convert and wrap degrees to radians [-3PI/2..+PI/2].

Arguments:
  • deg - Angle (degrees).
Returns:
Radians, wrapped (radiansPI_2)

radians2m (rad, radius=6371008.77141, lat=0)

 

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

Arguments:
  • rad - The angle (radians).
  • radius - Mean earth radius, ellipsoid or datum (meter, Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
  • lat - Parallel latitude (degrees90, str).
Returns:
Distance (meter, same units as radius or ellipsoidal and polar radii) or 0 for near-polar lat.
Raises:
  • RangeError - Latitude lat outside valid range and rangerrors set to True.
  • TypeError - Invalid radius.
  • ValueError - Invalid rad, radius or lat.

See Also: Function degrees2m and m2radians.

sincos2 (*rad)

 

Return the sine and cosine of angle(s).

Arguments:
  • 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 angle(s) in degrees.

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

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

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

 

Split an iterable into n slices.

Arguments:
  • iterable - Items to be spliced (list, tuple, ...).
  • n - Number of slices to generate (int).
  • fill - Optional fill value for missing items.
Returns:
A generator for each of n slices, iterable[i::n] for i=0..n.
Raises:
  • TypeError - Invalid 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))
>>> tuple(splice(list(range(9)), n=5))
([0, 5], [1, 6], [2, 7], [3, 8], [4])
>>> splice(range(9), n=1)
<generator object splice at 0x0...>

tan_2 (rad)

 

Compute the tangent of half angle.

Arguments:
  • rad - Angle (radians).
Returns:
tan(rad / 2) (float).

tanPI_2_2 (rad)

 

Compute the tangent of half angle, 90 degrees rotated.

Arguments:
  • rad - Angle (radians).
Returns:
tan((rad + PI/2) / 2) (float).

unroll180 (lon1, lon2, wrap=True)

 

Unroll longitudinal delta and wrap longitude in degrees.

Arguments:
  • lon1 - Start longitude (degrees).
  • lon2 - End longitude (degrees).
  • wrap - Wrap and unroll to the (-180..+180] range (bool).
Returns:
2-Tuple (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.

Arguments:
  • rad1 - Start longitude (radians).
  • rad2 - End longitude (radians).
  • wrap - Wrap and unroll to the (-PI..+PI] range (bool).
Returns:
2-Tuple (rad2 - rad1, rad2) unrolled (radians, radians).

See Also: Capability LONG_UNROLL in GeographicLib.

wrap90 (deg)

 

Wrap degrees to [-270..+90].

Arguments:
  • deg - Angle (degrees).
Returns:
Degrees, wrapped (degrees90).

wrap180 (deg)

 

Wrap degrees to [-180..+180].

Arguments:
  • deg - Angle (degrees).
Returns:
Degrees, wrapped (degrees180).

wrap360 (deg)

 

Wrap degrees to [0..+360).

Arguments:
  • deg - Angle (degrees).
Returns:
Degrees, wrapped (degrees360).

wrapPI (rad)

 

Wrap radians to [-PI..+PI].

Arguments:
  • rad - Angle (radians).
Returns:
Radians, wrapped (radiansPI).

wrapPI2 (rad)

 

Wrap radians to [0..+2PI).

Arguments:
  • rad - Angle (radians).
Returns:
Radians, wrapped (radiansPI2).

wrapPI_2 (rad)

 

Wrap radians to [-3PI/2..+PI/2].

Arguments:
  • rad - Angle (radians).
Returns:
Radians, wrapped (radiansPI_2).

yard2m (yards)

 

Convert UK yards to meter.

Arguments:
  • yards - Value in yards (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid yards.