Package pygeodesy :: Module utily

Module utily

Various utility functions.

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

Version: 24.10.12

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

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.

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 (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, **error_kwds)
Return the cotangent of an angle in radians.

cot_(*rads, **error_kwds)
Return the cotangent of angle(s) in radiansresection.

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

cotd_(*degs, **error_kwds)
Return 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, radius=6371008.771415, lat=0)
Convert an angle to a distance along the equator or along the parallel at an other (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.

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.

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

m2chain(meter)
Convert meter to UK chains.

m2degrees(distance, radius=6371008.771415, lat=0)
Convert a distance to an angle along the equator or along the parallel at an other (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.

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

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

m2radians(distance, radius=6371008.771415, 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).

m2toise(meter)
Convert meter to French toises.

m2yard(meter)
Convert meter to UK yards.

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

radians2m(rad, radius=6371008.771415, lat=0)
Convert an angle to a distance along the equator or along the parallel at an other (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)
Return the sine and cosine of angle(s) in radians.

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

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

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

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

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

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

tand_(*degs, **error_kwds)
Return 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.

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.

atan2b (y, x)

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

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, ellipsoid or datum (meter, Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
lat - Geodetic latitude (degrees90, str).

Returns:

A Circle4Tuple

(radius, height, lat, 
          beta)

instance.

Raises:

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

cot (rad, **error_kwds)

Return the cotangent of an angle in radians.

Arguments:

rad - Angle (radians).
error_kwds - Error to raise (ValueError).

Returns:

cot(rad).

Raises:

ValueError - pygeodesy.isnear0(sin(rad).

cot_ (*rads, **error_kwds)

Return the cotangent of angle(s) in radiansresection.

Arguments:

rads - One or more angles (radians).
error_kwds - Error to raise (ValueError).

Returns:

Yield the cot(rad) for each angle.

Raises:

ValueError - See pygeodesy.cot.

cotd (deg, **error_kwds)

Return the cotangent of an angle in degrees.

Arguments:

deg - Angle (degrees).
error_kwds - Error to raise (ValueError).

Returns:

cot(deg).

Raises:

ValueError - pygeodesy.isnear0(sin(deg).

cotd_ (*degs, **error_kwds)

Return the cotangent of angle(s) in degrees.

Arguments:

degs - One or more angles (degrees).
error_kwds - Error to raise (ValueError).

Returns:

Yield the cot(deg) for each angle.

Raises:

ValueError - See pygeodesy.cotd.

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, radius=6371008.771415, 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 equatorial and polar radii) or 0.0 for near-polar lat.

Raises:

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

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

km2m (km)

Convert kilo meter to meter (m).

Arguments:

km - Value in kilo meter (scalar).

Returns:

Value in meter (float).

Raises:

ValueError - Invalid km.

m2chain (meter)

Convert meter to UK chains.

Arguments:

meter - Value in meter (scalar).

Returns:

Value in chains (float).

Raises:

ValueError - Invalid meter.

m2degrees (distance, radius=6371008.771415, 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 is True.
TypeError - Invalid radius.
ValueError - Invalid distance, radius 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.

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.771415, 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 is 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.

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, radius=6371008.771415, 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 equatorial and polar radii) or 0.0 for near-polar lat.

Raises:

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

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

Arguments:

rads - One or more angles (radians).

Returns:

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

See Also: function sincos2.

sincos2d (deg, **adeg)

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_),

deg_ = deg + 
          adeg

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

sincos2d_ (*degs)

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

Arguments:

degs - One or more angles (degrees).

Returns:

Yield the sin(deg) and cos(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.

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.

tand (deg, **error_kwds)

Return the tangent of an angle in degrees.

Arguments:

deg - Angle (degrees).
error_kwds - Error to raise (ValueError).

Returns:

tan(deg).

Raises:

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

tand_ (*degs, **error_kwds)

Return the tangent of angle(s) in degrees.

Arguments:

degs - One or more angles (degrees).
error_kwds - Error to raise (ValueError).

Returns:

Yield the tan(deg) for each angle.

Raises:

ValueError - See pygeodesy.tand.

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. Do not supply any value to get the current setting.

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.