Package pygeodesy :: Module utily

Module utily

Various utility functions.

After Karney's C++ Math class and Veness' Latitude/Longitude and Vector-based geodesy and published under the same MIT Licence**.

Version: 25.09.09

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.

agdf(phi)
Inverse Gudermannian function.

asin1(x)
Return math.asin(max(-1, min(1, x))).

atan1(y, x=1.0)
Return atan(y / x) angle in radians [-PI/2..+PI/2] using atan2 for consistency and to avoid ZeroDivisionError.

atan1d(y, x=1.0)
Return atan(y / x) angle in degrees [-90..+90] using atan2d for consistency and to avoid ZeroDivisionError.

atan2(y, x)
Return atan2(y, x) in radians [-PI..+PI].

atan2b(y, x)
Return atan2(y, x) in degrees [0..+360], counter-clockwise.

atan2d(y, x, reverse=False)
Return atan2(y, x) in degrees [-180..+180], optionally reversed (by 180 degrees for azimuths).

chain2m(chains)
Convert UK chains to meter.

circle4(earth, lat)
Get the equatorial or a parallel circle of latitude.

cot(rad, **raiser_kwds)
Return the cotangent of an angle in radians.

cot_(*rads, **raiser_kwds)
Yield the cotangent of angle(s) in radians.

cotd(deg, **raiser_kwds)
Return the cotangent of an angle in degrees.

cotd_(*degs, **raiser_kwds)
Yield the cotangent of angle(s) in degrees.

degrees90(rad)
Convert radians to degrees and wrap [-90..+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 gons or gradians).

degrees2m(deg, earth=6371008.771415, lat=0, **radius)
Convert an angle to a distance along the equator or along a parallel at (geodetic) latitude.

fathom2m(fathoms)
Convert Imperial fathom to meter.

ft2m(feet, usurvey=False, pied=False, fuss=False)
Convert International, US Survey, French or German feet to meter.

furlong2m(furlongs)
Convert a furlong to meter.

gdf(psi)
Gudermannian function.

grades(rad)
Convert radians to grades (aka gons or gradians).

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

grades2degrees(gon)
Convert grades (aka gons or gradians) to degrees.

grades2radians(gon)
Convert grades (aka gons or gradians) to radians.

ha2acre(ha)
Convert hectare to acre.

ha2m2(ha)
Convert hectare to square meter.

hav(rad)
Return the haversine of an angle.

km2m(km)
Convert kilo meter to meter (m).

m2acre(meter2)
Convert square meter to acres.

m2chain(meter)
Convert meter to UK chains.

m2degrees(distance, earth=6371008.771415, lat=0, **radius)
Convert a distance to an angle along the equator or along a parallel at (geodetic) latitude.

m2fathom(meter)
Convert meter to Imperial fathoms.

m2ft(meter, usurvey=False, pied=False, fuss=False)
Convert meter to International, US Survey, French or or German feet (ft).

m2furlong(meter)
Convert meter to furlongs.

m2ha(meter2)
Convert square meter to hectare.

m2km(meter)
Convert meter to kilo meter (Km).

m2NM(meter)
Convert meter to nautical miles (NM).

m2radians(distance, earth=6371008.771415, lat=0, **radius)
Convert a distance to an angle along the equator or along a parallel at (geodetic) latitude.

m2SM(meter)
Convert meter to statute miles (SM).

m2toise(meter)
Convert meter to French toises.

m2yard(meter)
Convert meter to UK yards.

NM2m(nm)
Convert nautical miles to meter (m).

radians2m(rad, earth=6371008.771415, lat=0, **radius)
Convert an angle to a distance along the equator or along a parallel at (geodetic) latitude.

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(x)
Get sin and cos of typed angle.

sincos2(rad)
Return the sine and cosine of an angle in radians.

sincos2_(*rads)
Yield the sine and cosine of angle(s) in radians.

sincos2d(deg, adeg=0.0)
Return the sine and cosine of an angle in degrees.

sincos2d_(*degs)
Yield the sine and cosine of angle(s) in degrees.

sincostan3(rad)
Return the sine, cosine and tangent of an angle in radians.

sincostan3d(deg)
Return the sine, cosine and tangent of an angle in degrees.

SM2m(sm)
Convert statute miles to meter (m).

tan_2(rad, **semi)
Compute the tangent of half angle.

tan(rad, **raiser_kwds)
Return the tangent of an angle in radians.

tan_(*rads, **raiser_kwds)
Yield the tangent of angle(s) in radians.

tand(deg, **raiser_kwds)
Return the tangent of an angle in degrees.

tand_(*degs, **raiser_kwds)
Yield the tangent of angle(s) in degrees.

tanPI_2_2(rad)
Compute the tangent of half angle, 90 degrees rotated.

toise2m(toises)
Convert French toises to meter.

truncate(x, ndigits=None)
Truncate to the given number of digits.

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 [-90..+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 [-PI/2..+PI/2].

wrap_normal(*normal)
Define the operation for the keyword argument wrap=True, across pygeodesy: wrap, normalize or no-op.

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.

agdf (phi)

Inverse Gudermannian function.

Arguments:

phi - Angle (radians).

Returns:

Gudermannian (psi, float).

See Also: Function gdf.

atan1d (y, x=1.0)

Return atan(y / x) angle in degrees [-90..+90] using atan2d for consistency and to avoid ZeroDivisionError.

See Also: Function pygeodesy.atan2d.

atan2 (y, x)

Return atan2(y, x) in radians [-PI..+PI].

atan2b (y, x)

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

See Also: Function pygeodesy.atan2d.

atan2d (y, x, reverse=False)

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

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:

earth - The earth radius (meter) or an ellipsoid or datum (Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
lat - Geodetic latitude (degrees90, str).

Returns:

A Circle4Tuple

(radius, height, lat, 
          beta)

Raises:

RangeError - Latitude lat outside valid range and rangerrors is True.
TypeError - Invalid earth.
ValueError - invalid earth or lat.

cot (rad, **raiser_kwds)

Return the cotangent of an angle in radians.

Arguments:

rad - Angle (radians).
raiser_kwds - Use raiser=False to avoid ValueErrors and optional, additional ValueError keyword argments.

Returns:

cot(rad).

Raises:

Error - If pygeodesy.isnear0(sin(rad).

cot_ (*rads, **raiser_kwds)

Yield the cotangent of angle(s) in radians.

Arguments:

rads - One or more angles (each in radians).

Returns:

Yield cot(rad) for each angle.

See Also: Function pygeodesy.cot for further details.

cotd (deg, **raiser_kwds)

Return the cotangent of an angle in degrees.

Arguments:

deg - Angle (degrees).
raiser_kwds - Use raiser=False to avoid ValueErrors and optional, additional ValueError keyword argments.

Returns:

cot(deg).

Raises:

Error - If pygeodesy.isnear0(sin(deg).

cotd_ (*degs, **raiser_kwds)

Yield the cotangent of angle(s) in degrees.

Arguments:

degs - One or more angles (each in degrees).

Returns:

Yield cotd(deg) for each angle.

See Also: Function pygeodesy.cotd for further details.

degrees90 (rad)

Convert radians to degrees and wrap [-90..+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 gons or gradians).

Arguments:

deg - Angle (degrees).

Returns:

Angle (grades).

degrees2m (deg, earth=6371008.771415, lat=0, **radius)

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

Arguments:

deg - The angle (degrees).
earth - The earth radius (meter) or an ellipsoid or datum (Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
lat - Parallel latitude (degrees90, str).
radius - For backward compatibility radius=earth.

Returns:

Distance (meter, same units as earth or polar and equatorial radii) or 0.0 for near-polar lat.

Raises:

RangeError - Latitude lat outside valid range and rangerrors is True.
TypeError - Invalid earth or radius.
ValueError - Invalid deg, earth or lat.

See Also: Function radians2m and m2degrees.

fathom2m (fathoms)

Convert Imperial fathom to meter.

Arguments:

fathoms - Value in fathoms (scalar).

Returns:

Value in meter (float).

Raises:

ValueError - Invalid fathoms.

See Also: Function toise2m, Fathom and Klafter.

ft2m (feet, usurvey=False, pied=False, fuss=False)

Convert International, US Survey, French or German feet to meter.

Arguments:

feet - Value in feet (scalar).
usurvey - If True, convert US Survey foot else ...
pied - If True, convert French pied-du-Roi else ...
fuss - If True, convert German Fuss, otherwise International foot to meter.

Returns:

Value in meter (float).

Raises:

ValueError - Invalid feet.

furlong2m (furlongs)

Convert a furlong to meter.

Arguments:

furlongs - Value in furlongs (scalar).

Returns:

Value in meter (float).

Raises:

ValueError - Invalid furlongs.

gdf (psi)

Gudermannian function.

Arguments:

psi - Gudermannian (float).

Returns:

Angle (radians).

See Also: Function agdf.

grades (rad)

Convert radians to grades (aka gons or gradians).

Arguments:

rad - Angle (radians).

Returns:

Angle (grades).

grades400 (rad)

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

Arguments:

rad - Angle (radians).

Returns:

Angle, wrapped (grades).

grades2degrees (gon)

Convert grades (aka gons or gradians) to degrees.

Arguments:

gon - Angle (grades).

Returns:

Angle (degrees).

grades2radians (gon)

Convert grades (aka gons or gradians) to radians.

Arguments:

gon - Angle (grades).

Returns:

Angle (radians).

ha2acre (ha)

Convert hectare to acre.

Arguments:

ha - Value in hectare (scalar).

Returns:

Value in acres (float).

Raises:

ValueError - Invalid ha.

ha2m2 (ha)

Convert hectare to square meter.

Arguments:

ha - Value in hectare (scalar).

Returns:

Value in meter^2 (float).

Raises:

ValueError - Invalid ha.

hav (rad)

Return the haversine of an angle.

Arguments:

rad - Angle (radians).

Returns:

sin(rad / 2)**2.

km2m (km)

Convert kilo meter to meter (m).

Arguments:

km - Value in kilo meter (scalar).

Returns:

Value in meter (float).

Raises:

ValueError - Invalid km.

m2acre (meter2)

Convert square meter to acres.

Arguments:

meter2 - Value in meter^2 (scalar).

Returns:

Value in acres (float).

Raises:

ValueError - Invalid meter2.

m2chain (meter)

Convert meter to UK chains.

Arguments:

meter - Value in meter (scalar).

Returns:

Value in chains (float).

Raises:

ValueError - Invalid meter.

m2degrees (distance, earth=6371008.771415, lat=0, **radius)

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

Arguments:

distance - Distance (meter, same units as radius).
earth - Mean earth radius (meter) or an ellipsoid or datum (Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
lat - Parallel latitude (degrees90, str).
radius - For backward compatibility radius=earth.

Returns:

Angle (degrees) or INF or NINF for near-polar lat.

Raises:

RangeError - Latitude lat outside valid range and rangerrors is True.
TypeError - Invalid earth or radius.
ValueError - Invalid distance, earth or lat.

See Also: Function m2radians and degrees2m.

m2fathom (meter)

Convert meter to Imperial fathoms.

Arguments:

meter - Value in meter (scalar).

Returns:

Value in fathoms (float).

Raises:

ValueError - Invalid meter.

See Also: Function m2toise, Fathom and Klafter.

m2ft (meter, usurvey=False, pied=False, fuss=False)

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

Arguments:

meter - Value in meter (scalar).
usurvey - If True, convert to US Survey foot else ...
pied - If True, convert to French pied-du-Roi else ...
fuss - If True, convert to German Fuss, otherwise to International foot.

Returns:

Value in feet (float).

Raises:

ValueError - Invalid meter.

m2furlong (meter)

Convert meter to furlongs.

Arguments:

meter - Value in meter (scalar).

Returns:

Value in furlongs (float).

Raises:

ValueError - Invalid meter.

m2ha (meter2)

Convert square meter to hectare.

Arguments:

meter2 - Value in meter^2 (scalar).

Returns:

Value in hectare (float).

Raises:

ValueError - Invalid meter2.

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, earth=6371008.771415, lat=0, **radius)

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

Arguments:

distance - Distance (meter, same units as radius).
earth - Mean earth radius (meter) or an ellipsoid or datum (Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
lat - Parallel latitude (degrees90, str).
radius - For backward compatibility radius=earth.

Returns:

Angle (radians) or INF or NINF for near-polar lat.

Raises:

RangeError - Latitude lat outside valid range and rangerrors is True.
TypeError - Invalid earth or radius.
ValueError - Invalid distance, earth 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.

m2toise (meter)

Convert meter to French toises.

Arguments:

meter - Value in meter (scalar).

Returns:

Value in toises (float).

Raises:

ValueError - Invalid meter.

See Also: Function m2fathom.

m2yard (meter)

Convert meter to UK yards.

Arguments:

meter - Value in meter (scalar).

Returns:

Value in yards (float).

Raises:

ValueError - Invalid meter.

NM2m (nm)

Convert nautical miles to meter (m).

Arguments:

nm - Value in nautical miles (scalar).

Returns:

Value in meter (float).

Raises:

ValueError - Invalid nm.

radians2m (rad, earth=6371008.771415, lat=0, **radius)

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

Arguments:

rad - The angle (radians).
earth - Mean earth radius (meter) or an ellipsoid or datum (Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
lat - Parallel latitude (degrees90, str).
radius - For backward compatibility radius=earth.

Returns:

Distance (meter, same units as earth or polar and equatorial radii) or 0.0 for near-polar lat.

Raises:

RangeError - Latitude lat outside valid range and rangerrors is True.
TypeError - Invalid earth or radius.
ValueError - Invalid rad, earth or lat.

See Also: Function degrees2m and m2radians.

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)

SinCos2 (x)

Get sin and cos of typed angle.

Arguments:

x - Angle (Degrees, Radians or scalar radians).

Returns:

2-Tuple (sin(x), cos(x)).

sincos2 (rad)

Return the sine and cosine of an angle in radians.

Arguments:

rad - Angle (radians).

Returns:

2-Tuple (sin(rad), cos(rad)).

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

sincos2_ (*rads)

Yield the sine and cosine of angle(s) in radians.

Arguments:

rads - One or more angles (radians).

Returns:

Yield sin(rad) and cos(rad) for each angle.

See Also: Function sincos2.

sincos2d (deg, adeg=0.0)

Return the sine and cosine of an angle in degrees.

Arguments:

deg - Angle (degrees).
adeg - Optional correction (degrees).

Returns:

2-Tuple (sin(deg_), cos(deg_) with

deg_ = deg
          + adeg

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

sincos2d_ (*degs)

Yield the sine and cosine of angle(s) in degrees.

Arguments:

degs - One or more angles (degrees).

Returns:

Yield sind(deg) and cosd(deg) for each angle.

See Also: Function sincos2d.

sincostan3 (rad)

Return the sine, cosine and tangent of an angle in radians.

Arguments:

rad - Angle (radians).

Returns:

3-Tuple (sin(rad), cos(rad), tan(rad)).

See Also: Function sincos2.

sincostan3d (deg)

Return the sine, cosine and tangent of an angle in degrees.

Arguments:

deg - Angle (degrees).

Returns:

3-Tuple (sind(deg), cosd(deg), tand(deg)).

See Also: Function sincos2d.

SM2m (sm)

Convert statute miles to meter (m).

Arguments:

sm - Value in statute miles (scalar).

Returns:

Value in meter (float).

Raises:

ValueError - Invalid sm.

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.

tan (rad, **raiser_kwds)

Return the tangent of an angle in radians.

Arguments:

rad - Angle (radians).
raiser_kwds - Use raiser=False to avoid ValueErrors and optional, additional ValueError keyword argments.

Returns:

tan(rad).

Raises:

Error - If pygeodesy.isnear0(cos(rad).

tan_ (*rads, **raiser_kwds)

Yield the tangent of angle(s) in radians.

Arguments:

rads - One or more angles (each in radians).

Returns:

Yield tan(rad) for each angle.

See Also: Function pygeodesy.tan for futher details.

tand (deg, **raiser_kwds)

Return the tangent of an angle in degrees.

Arguments:

deg - Angle (degrees).
raiser_kwds - Use raiser=False to avoid ValueErrors and optional, additional ValueError keyword argments.

Returns:

tan(deg).

Raises:

Error - If pygeodesy.isnear0(cos(deg).

tand_ (*degs, **raiser_kwds)

Yield the tangent of angle(s) in degrees.

Arguments:

degs - One or more angles (each in degrees).

Returns:

Yield tand(deg) for each angle.

See Also: Function pygeodesy.tand for futher details.

tanPI_2_2 (rad)

Compute the tangent of half angle, 90 degrees rotated.

Arguments:

rad - Angle (radians).

Returns:

tan((rad + PI/2) / 2) (float).

toise2m (toises)

Convert French toises to meter.

Arguments:

toises - Value in toises (scalar).

Returns:

Value in meter (float).

Raises:

ValueError - Invalid toises.

See Also: Function fathom2m.

truncate (x, ndigits=None)

Truncate to the given number of digits.

Arguments:

x - Value to truncate (scalar).
ndigits - Number of digits (int), aka precision.

Returns:

Truncated x (float).

See Also: Python function round.

unroll180 (lon1, lon2, wrap=True)

Unroll longitudinal delta and wrap longitude in degrees.

Arguments:

lon1 - Start longitude (degrees).
lon2 - End longitude (degrees).
wrap - If True, 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 - If True, 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 [-90..+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 [-PI/2..+PI/2].

Arguments:

rad - Angle (radians).

Returns:

Radians, wrapped (radiansPI_2).

wrap_normal (*normal)

Define the operation for the keyword argument wrap=True, across pygeodesy: wrap, normalize or no-op. For backward compatibility, the default is wrap.

Arguments:

normal - If True, normalize lat- and longitude using normal or normal_, if False, wrap the lat- and longitude individually by wrap90 or wrapPI_2 respectively wrap180, wrapPI or if None, leave lat- and longitude unchanged. To get the current setting, do not specify.

Returns:

The previous wrap_normal setting (bool or None).

yard2m (yards)

Convert UK yards to meter.

Arguments:

yards - Value in yards (scalar).

Returns:

Value in meter (float).

Raises:

ValueError - Invalid yards.