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

Classes
| LimitError Error raised for lat- or longitudinal deltas exceeding the limit in functions equirectangular and equirectangular_.

Functions
degrees(x) Convert angle x from radians to degrees. |
radians(x) Convert angle x from degrees to radians. |
anStr(name, OKd=`'``._-``'`, sub=`'``_``'`) Make a valid name of alphanumeric and OKd characters. |
clipStr(bstr, limit=50, white=`'````'`) Clip a string to the given length limit. |
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 angle to distance along equator or at other latitude. |
enStr2(easting, northing, prec, *extras) Return easting, northing string representations. |
false2f(value, name=`'``value``'`, false=True) Convert a false east-/northing to non-negative float. |
ft2m(feet) Convert International feet to meter (m). |
halfs2(str2) Split a string in 2 halfs. |
isNumpy2(obj) Check for an Numpy2LatLon points wrapper. |
isPoints2(obj) Check for an LatLon2psxy points wrapper. |
issequence(obj, *excluded) Check for sequence types. |
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. |
limiterrors(raiser=None) Get/set the raising of limit errors. |
m2degrees(meter, radius=6371008.77141) Convert distance to angle along equator. |
m2ft(meter) Convert meter to International feet (ft). |
m2km(meter) Convert meter to kilo meter (km). |
m2NM(meter) Convert meter to nautical miles (NM). |
m2SM(meter) Convert meter to statute miles (SM). |
points2(points, closed=True, base=None) Check a polygon represented by points. |
polygon(points, closed=True, base=None) DEPRECATED, use function points2. |
property_RO(method) Decorator for `Read_Only` property. |
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(*rad) Return the `sine` and `cosine` of angle(s). |
sincos2d(*deg) Return the `sine` and `cosine` of an angle. |
splice(iterable, n=2, fill=object()) 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. |
unStr(name, *args, **kwds) Return the string representation of an invokation. |
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]. |

Variables
| PI = `3.14159265359`
| __all__ = `_ALL_LAZY.utily`
| PI2 = `6.28318530718` Two PI, PI * 2 aka Tau (`float`) # PYCHOK expected
| PI_2 = `1.57079632679` Half PI, PI / 2 (`float`)
| PI_4 = `0.785398163397` Quarter PI, PI / 4 (`float`)
| R_M = `6371008.77141` Mean, spherical earth radius (`meter`).

Function Details

### anStr(name, OKd=`'``._-``'`, sub=`'``_``'`) |
Make a valid name of alphanumeric and OKd characters. Parameters: `name` - The original name (`str`). `OKd` - Other acceptable characters (`str`). `sub` - Substitute for invalid charactes (`str`). Returns: The modified name (`str`). Note: Leading and trailing whitespace characters are removed and intermediate whitespace characters are coalesced and substituted.

### clipStr(bstr, limit=50, white=`'````'`) |
Clip a string to the given length limit. Parameters: `bstr` - String (`bytes` or `str`). `limit` - Length limit (`int`). `white` - Whitespace replacement (`str`). Returns: Clipped `bytes` or `str`.

### degrees90(rad) |
Convert radians to degrees and wrap (-270..+90]. Parameters: `rad` - Angle (`radians`). Returns: Angle in degrees, wrapped (`degrees90`).

### degrees180(rad) |
Convert radians to degrees and wrap (-180..+180]. Parameters: `rad` - Angle (`radians`). Returns: Angle in degrees, wrapped (`degrees180`).

### degrees360(rad) |
Convert radians to degrees and wrap (0..+360]. Parameters: `rad` - Angle (`radians`). Returns: Angle in degrees, wrapped (`degrees360`).

### degrees2m(deg, radius=6371008.77141, lat=0) |
Convert angle to distance along equator or at other latitude. Parameters: `deg` - Angle (`degrees`). `radius` - Mean earth radius (`meter`). `lat` - Latitude adjusting the distance (`degrees90`). Returns: Distance (`meter`, same units as radius). Raises: `RangeError` - Latitude lat outside valid range and rangerrrors set to `True`.

### enStr2(easting, northing, prec, *extras) |
Return easting, northing string representations. Parameters: `easting` - Easting from false easting (`meter`). `northing` - Northing from from false northing (`meter`). `prec` - Precision in number of digits (`int`). `extras` - Optional leading items (strings). Returns: extras + 2-Tuple (eastingStr, northingStr). Raises: `ValueError` - Invalid prec.

### false2f(value, name=`'``value``'`, false=True) |
Convert a false east-/northing to non-negative float. Parameters: `value` - Value to convert (`scalar`). `name` - Optional name of the value (`str`). `false` - Optionally, value includes false origin (`bool`). Returns: The value (`float`). Raises: `ValueError` - Invalid or negative value.

### ft2m(feet) |
Convert International feet to meter (m). Parameters: `feet` - Value in feet (`scalar`). Returns: Value in m (`float`).

### halfs2(str2) |
Split a string in 2 halfs. Parameters: `str2` - String to split (`str`). Returns: 2-Tuple (1st, 2nd) half (`str`). Raises: `ValueError` - Zero or odd `len`(str2).

### isNumpy2(obj) |
Check for an Numpy2LatLon points wrapper. Parameters: `obj` - The object (any `type`). Returns: `True` if obj is an Numpy2LatLon instance, `False` otherwise.

### isPoints2(obj) |
Check for an LatLon2psxy points wrapper. Parameters: `obj` - The object (any `type`). Returns: `True` if obj is an LatLon2psxy instance, `False` otherwise.

### issequence(obj, *excluded) |
Check for sequence types. Parameters: `obj` - The object (any `type`). `excluded` - Optional, exclusions (`type`). Returns: `True` if obj is a sequence, `False` otherwise. Note: Excluding `tuple` implies excluding `namedtuple`.

### isTuple2(obj) |
Check for an Tuple2LatLon points wrapper. Parameters: `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. Parameters: `obj` - Points array, list, sequence, set, etc. (any). Returns: `True` do, `False` don't iterate.

### iterNumpy2over(n=None) |
Get or set the iterNumpy2 threshold. Parameters: `n` - Optional, new threshold (`int`). Returns: Previous threshold (`int`). Raises: `ValueError` - Invalid n.

### limiterrors(raiser=None) |
Get/set the raising of limit errors. Parameters: `raiser` - Choose `True` to raise or `False` to ignore LimitError exceptions. Use `None` to leave the setting unchanged. Returns: Previous setting (`bool`).

### m2degrees(meter, radius=6371008.77141) |
Convert distance to angle along equator. Parameters: `meter` - Distance (`meter`, same units as radius). `radius` - Mean earth radius (`meter`). Returns: Angle (`degrees`). Raises: `ValueError` - Invalid radius.

### m2ft(meter) |
Convert meter to International feet (ft). Parameters: `meter` - Value in meter (`scalar`). Returns: Value in ft (`float`).

### m2km(meter) |
Convert meter to kilo meter (km). Parameters: `meter` - Value in meter (`scalar`). Returns: Value in km (`float`).

### m2NM(meter) |
Convert meter to nautical miles (NM). Parameters: `meter` - Value in meter (`scalar`). Returns: Value in NM (`float`).

### m2SM(meter) |
Convert meter to statute miles (SM). Parameters: `meter` - Value in meter (`scalar`). Returns: Value in SM (`float`).

### points2(points, closed=True, base=None) |
Check a polygon represented by points. Parameters: `points` - The polygon points (`LatLon`[]) `closed` - Optionally, consider the polygon closed, ignoring any duplicate or closing final points (`bool`). `base` - Optionally, check the points against this base class `None`. Returns: 2-Tuple (n, points) with the number (`int`) of points and the points `list` or `tuple`. Raises: `TypeError` - Some points are not `LatLon`. `ValueError` - Insufficient number of points.

### property_RO(method) |
Decorator for `Read_Only` property. Parameters: `method` - The callable to be decorated as `property.getter`. Note: Like standard Python `property` without a `property.setter` with a more descriptive error message when set.

### radiansPI(deg) |
Convert and wrap degrees to radians (-PI..+PI]. Parameters: `deg` - Angle (`degrees`). Returns: Radians, wrapped (`radiansPI`)

### radiansPI2(deg) |
Convert and wrap degrees to radians (0..+2PI]. Parameters: `deg` - Angle (`degrees`). Returns: Radians, wrapped (`radiansPI2`)

### radiansPI_2(deg) |
Convert and wrap degrees to radians (-3PI/2..+PI/2]. Parameters: `deg` - Angle (`degrees`). Returns: Radians, wrapped (`radiansPI_2`)

### sincos2(*rad) |
Return the `sine` and `cosine` of angle(s). Parameters: `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 an angle. Parameters: `deg` - One or more angles (`degrees`). Returns: The `sin(rad)` and `cos(rad)` for each angle. See Also: GeographicLib function sincosd and C++ sincosd.

### splice(iterable, n=2, fill=object()) |
Split an iterable into `n` slices. Parameters: `iterable` - Items to be spliced (`list`, `tuple`, ...). `n` - Number of slices to generate (`int`). `fill` - Fill value for missing items. Returns: Generator of n slices iterable[i::n] for i=0..n. Raises: `ValueError` - Non-`int` or non-positive 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))
    >>> list(splice(range(12), n=5))
    [(0, 5, 10), (1, 6, 11), (2, 7), (3, 8), (4, 9)]
    >>> splice(range(9), n=1)
    <generator object splice at 0x0...>

### tan_2(rad) |
Compute the tangent of half angle. Parameters: `rad` - Angle (`radians`). Returns: tan(rad / 2) (`float`).

### tanPI_2_2(rad) |
Compute the tangent of half angle, 90 degrees rotated. Parameters: `rad` - Angle (`radians`). Returns: tan((rad + PI/2) / 2) (`float`).

### unroll180(lon1, lon2, wrap=True) |
Unroll longitudinal delta and wrap longitude in degrees. Parameters: `lon1` - Start longitude (`degrees`). `lon2` - End longitude (`degrees`). `wrap` - Wrap and unroll to the (-180..+180] range (`bool`). Returns: 2-Tuple (delta 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. Parameters: `rad1` - Start longitude (`radians`). `rad2` - End longitude (`radians`). `wrap` - Wrap and unroll to the (-PI..+PI] range (`bool`). Returns: 2-Tuple (delta rad2-rad1, rad2) unrolled (`radians`, `radians`). See Also: Capability LONG_UNROLL in GeographicLib.

### unStr(name, *args, **kwds) |
Return the string representation of an invokation. Parameters: `name` - Function, method or class name (`str`). `args` - Optional positional arguments. `kwds` - Optional keyword arguments. Returns: Representation (`str`).

### wrap90(deg) |
Wrap degrees to (-270..+90]. Parameters: `deg` - Angle (`degrees`). Returns: Degrees, wrapped (`degrees90`).

### wrap180(deg) |
Wrap degrees to (-180..+180]. Parameters: `deg` - Angle (`degrees`). Returns: Degrees, wrapped (`degrees180`).

### wrap360(deg) |
Wrap degrees to (0..+360]. Parameters: `deg` - Angle (`degrees`). Returns: Degrees, wrapped (`degrees360`).

### wrapPI(rad) |
Wrap radians to (-PI..+PI]. Parameters: `rad` - Angle (`radians`). Returns: Radians, wrapped (`radiansPI`).

### wrapPI2(rad) |
Wrap radians to (0..+2PI]. Parameters: `rad` - Angle (`radians`). Returns: Radians, wrapped (`radiansPI2`).

### wrapPI_2(rad) |
Wrap radians to (-3PI/2..+PI/2]. Parameters: `rad` - Angle (`radians`). Returns: Radians, wrapped (`radiansPI_2`).