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

Module utily

Various utility functions.

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


Version: 21.06.27

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, reverse=False)
Return atan2(y, x) in degrees [-180..+180], optionally reversed (for azi2).
 
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).
 
degrees2grades(deg)
Convert degrees to grades (aka gradians or gons).
 
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.
 
grades(rad)
Convert radians to grades (aka gradians or gons).
 
grades400(rad)
Convert radians to grades (aka gradians or gons) and wrap [0..+400).
 
grades2degrees(gon)
Convert grades (aka gradians or gons) to degrees.
 
grades2radians(gon)
Convert grades (aka gradians or gons) to radians.
 
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.
 
tan_2(rad, **semi)
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, reverse=False)

 

Return atan2(y, x) in degrees [-180..+180], optionally reversed (for azi2).

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, wrapped (degrees90).

degrees180 (rad)

 

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

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

degrees360 (rad)

 

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

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

degrees2grades (deg)

 

Convert degrees to grades (aka gradians or gons).

Arguments:
  • deg - Angle (degrees).
Returns:
Angle (grades).

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

grades (rad)

 

Convert radians to grades (aka gradians or gons).

Arguments:
  • rad - Angle (radians).
Returns:
Angle (grades).

grades400 (rad)

 

Convert radians to grades (aka gradians or gons) and wrap [0..+400).

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

grades2degrees (gon)

 

Convert grades (aka gradians or gons) to degrees.

Arguments:
  • gon - Angle (grades).
Returns:
Angle (degrees).

grades2radians (gon)

 

Convert grades (aka gradians or gons) to radians.

Arguments:
  • gon - Angle (grades).
Returns:
Angle (radians).

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

tan_2 (rad, **semi)

 

Compute the tangent of half angle.

Arguments:
  • rad - Angle (radians).
  • semi - Angle or edge name and index for semi-circular error.
Returns:
tan(rad / 2) (float).
Raises:
  • ValueError - If rad is semi-circular and semi is given.

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.