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

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`. |
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, **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: `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 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`).

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

### 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, **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`.