Coverage for pygeodesy/utily.py : 96%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# -*- coding: utf-8 -*-
After I{(C) Chris Veness 2011-2015} published under the same MIT Licence**, see U{Latitude/Longitude<https://www.Movable-Type.co.UK/scripts/latlong.html>} and U{Vector-based geodesy<https://www.Movable-Type.co.UK/scripts/latlong-vectors.html>}. ''' # make sure int/int division yields float quotient, see .basics
_edge_, _radians_, _semi_circular_, _SPACE_, \ _0_0, _0_5, _1_0, _90_0, _180_0, _360_0, _400_0
# <https://Numbers.Computation.Free.FR/Constants/Miscellaneous/digits.html> # sqrt(2) + 1 <https://WikiPedia.org/wiki/Square_root_of_2> # _1sqrt2 = 2.41421356237309504880 # _16887_24209_69807_85696_71875_37694_80731_76679_73799
'''Return C{math.acos(max(-1, min(1, B{x})))}. '''
'''Convert acres to hectare.
@arg acres: Value in acres (C{scalar}).
@return: Value in C{hectare} (C{float}).
@raise ValueError: Invalid B{C{acres}}. ''' # 0.40468564224 == acre2m2(1) / 10_000
'''Convert acres to I{square} meter.
@arg acres: Value in acres (C{scalar}).
@return: Value in C{meter^2} (C{float}).
@raise ValueError: Invalid B{C{acres}}. ''' # 4046.8564224 == chain2m(1) * furlong2m(1)
'''Return C{math.asin(max(-1, min(1, B{x})))}. '''
'''Return C{atan(B{y_x})} angle in C{degrees}.
@see: Function L{atan2d}. '''
'''Return C{atan2(B{y}, B{x})} in degrees M{[0..+360]}.
@see: Function L{atan2d}. '''
'''Return C{atan2(B{y}, B{x})} in degrees M{[-180..+180]}.
@see: I{Karney}'s C++ function U{Math.atan2d <https://GeographicLib.SourceForge.io/html/classGeographicLib_1_1Math.html>}. ''' else: # q = 2 else:
'''Convert I{UK} chains to meter.
@arg chains: Value in chains (C{scalar}).
@return: Value in C{meter} (C{float}).
@raise ValueError: Invalid B{C{chains}}. ''' # 20.1168 = 22 * yard2m(1)
'''Get the equatorial or a parallel I{circle of latitude}.
@arg earth: The earth radius, ellipsoid or datum (C{meter}, L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or L{a_f2Tuple}). @arg lat: Geodetic latitude (C{degrees90}, C{str}).
@return: A L{Circle4Tuple}C{(radius, height, lat, beta)} instance.
@raise RangeError: Latitude B{C{lat}} outside valid range and L{rangerrors} set to C{True}.
@raise TypeError: Invalid B{C{earth}}.
@raise ValueError: B{C{earth}} or B{C{lat}}. '''
'''Convert radians to degrees and wrap M{[-270..+90]}.
@arg rad: Angle (C{radians}).
@return: Angle, wrapped (C{degrees90}). '''
'''Convert radians to degrees and wrap M{[-180..+180]}.
@arg rad: Angle (C{radians}).
@return: Angle, wrapped (C{degrees180}). '''
'''Convert radians to degrees and wrap M{[0..+360)}.
@arg rad: Angle (C{radians}).
@return: Angle, wrapped (C{degrees360}). '''
'''Convert degrees to I{grades} (aka I{gradians} or I{gons}).
@arg deg: Angle (C{degrees}).
@return: Angle (C{grades}). '''
'''Convert an angle to a distance along the equator or along the parallel at an other (geodetic) latitude.
@arg deg: The angle (C{degrees}). @kwarg radius: Mean earth radius, ellipsoid or datum (C{meter}, L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or L{a_f2Tuple}). @kwarg lat: Parallel latitude (C{degrees90}, C{str}).
@return: Distance (C{meter}, same units as B{C{radius}} or ellipsoidal and polar radii) or C{0} for near-polar B{C{lat}}.
@raise RangeError: Latitude B{C{lat}} outside valid range and L{rangerrors} set to C{True}.
@raise TypeError: Invalid B{C{radius}}.
@raise ValueError: Invalid B{C{deg}}, B{C{radius}} or B{C{lat}}.
@see: Function L{radians2m} and L{m2degrees}. '''
'''Convert I{UK} fathom to meter.
@arg fathoms: Value in fathoms (C{scalar}).
@return: Value in C{meter} (C{float}).
@raise ValueError: Invalid B{C{fathoms}}. ''' # 1.8288 == 2 * yard2m(1)
'''Convert I{International} or I{US Survey} feet to meter.
@arg feet: Value in feet (C{scalar}). @kwarg usurvey: Convert I{US Survey} feet (C{bool}), I{International} feet otherwise.
@return: Value in C{meter} (C{float}).
@raise ValueError: Invalid B{C{feet}}. ''' # US Survey 1200 / 3937 == 0.3048006096012192 # Int'l 0.3048 == 254 * 12 / 10_000
'''Convert a I{UK} furlong to meter.
@arg furlongs: Value in furlongs (C{scalar}).
@return: Value in C{meter} (C{float}).
@raise ValueError: Invalid B{C{furlongs}}. ''' # 201.168 = 220 * yard2m(1)
'''Convert radians to I{grades} (aka I{gradians} or I{gons}).
@arg rad: Angle (C{radians}).
@return: Angle (C{grades}). '''
'''Convert radians to I{grades} (aka I{gradians} or I{gons}) and wrap M{[0..+400)}.
@arg rad: Angle (C{radians}).
@return: Angle, wrapped (C{grades}). '''
'''Convert I{grades} (aka I{gradians} or I{gons}) to C{degrees}.
@arg gon: Angle (C{grades}).
@return: Angle (C{degrees}). '''
'''Convert I{grades} (aka I{gradians} or I{gons}) to C{radians}.
@arg gon: Angle (C{grades}).
@return: Angle (C{radians}). '''
'''Check for an B{C{Numpy2LatLon}} points wrapper.
@arg obj: The object (any C{type}).
@return: C{True} if B{C{obj}} is an B{C{Numpy2LatLon}} instance, C{False} otherwise. ''' # isinstance(self, (Numpy2LatLon, ...))
'''Check for an B{C{LatLon2psxy}} points wrapper.
@arg obj: The object (any C{type}).
@return: C{True} if B{C{obj}} is an B{C{LatLon2psxy}} instance, C{False} otherwise. ''' # isinstance(self, (LatLon2psxy, ...))
'''Check for an B{C{Tuple2LatLon}} points wrapper.
@arg obj: The object (any).
@return: C{True} if B{C{obj}} is an B{C{Tuple2LatLon}} instance, C{False} otherwise. ''' # isinstance(self, (Tuple2LatLon, ...))
'''Iterate over Numpy2 wrappers or other sequences exceeding the threshold.
@arg obj: Points array, list, sequence, set, etc. (any).
@return: C{True} do, C{False} don't iterate. ''' try: return isNumpy2(obj) or len(obj) > _iterNumpy2len except TypeError: return False
'''Get or set the L{iterNumpy2} threshold.
@kwarg n: Optional, new threshold (C{int}).
@return: Previous threshold (C{int}).
@raise ValueError: Invalid B{C{n}}. ''' global _iterNumpy2len else: raise ValueError except (TypeError, ValueError): raise _ValueError(n=n)
'''Convert a distance to an angle along the equator or along the parallel at an other (geodetic) latitude.
@arg distance: Distance (C{meter}, same units as B{C{radius}}). @kwarg radius: Mean earth radius, ellipsoid or datum (C{meter}, an L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or L{a_f2Tuple}). @kwarg lat: Parallel latitude (C{degrees90}, C{str}).
@return: Angle (C{degrees}) or C{INF} for near-polar B{C{lat}}.
@raise RangeError: Latitude B{C{lat}} outside valid range and L{rangerrors} set to C{True}.
@raise TypeError: Invalid B{C{radius}}.
@raise ValueError: Invalid B{C{distance}}, B{C{radius}} or B{C{lat}}.
@see: Function L{m2radians} and L{degrees2m}. '''
'''Convert meter to I{International} or I{US Survey} feet (C{ft}).
@arg meter: Value in meter (C{scalar}). @kwarg usurvey: Convert to I{US Survey} feet (C{bool}), I{International} feet otherwise.
@return: Value in C{feet} (C{float}).
@raise ValueError: Invalid B{C{meter}}. ''' # US Survey == 3937 / 1200 == 3.2808333333333333 # Int'l 10_000 / (254 * 12) == 3.2808398950131235
'''Convert meter to kilo meter (km).
@arg meter: Value in meter (C{scalar}).
@return: Value in km (C{float}).
@raise ValueError: Invalid B{C{meter}}. '''
'''Convert meter to nautical miles (NM).
@arg meter: Value in meter (C{scalar}).
@return: Value in NM (C{float}).
@raise ValueError: Invalid B{C{meter}}. '''
'''Convert a distance to an angle along the equator or along the parallel at an other (geodetic) latitude.
@arg distance: Distance (C{meter}, same units as B{C{radius}}). @kwarg radius: Mean earth radius, ellipsoid or datum (C{meter}, an L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or L{a_f2Tuple}). @kwarg lat: Parallel latitude (C{degrees90}, C{str}).
@return: Angle (C{radians}) or C{INF} for near-polar B{C{lat}}.
@raise RangeError: Latitude B{C{lat}} outside valid range and L{rangerrors} set to C{True}.
@raise TypeError: Invalid B{C{radius}}.
@raise ValueError: Invalid B{C{distance}}, B{C{radius}} or B{C{lat}}.
@see: Function L{m2degrees} and L{radians2m}. '''
'''Convert meter to statute miles (SM).
@arg meter: Value in meter (C{scalar}).
@return: Value in SM (C{float}).
@raise ValueError: Invalid B{C{meter}}. '''
'''Convert meter to I{UK} yards.
@arg meter: Value in meter (C{scalar}).
@return: Value in yards (C{float}).
@raise ValueError: Invalid B{C{meter}}. ''' # 1.0936132983377078 == 10_000 / (254 * 12 * 3)
'''Convert and wrap degrees to radians M{[-PI..+PI]}.
@arg deg: Angle (C{degrees}).
@return: Radians, wrapped (C{radiansPI}) '''
'''Convert and wrap degrees to radians M{[0..+2PI)}.
@arg deg: Angle (C{degrees}).
@return: Radians, wrapped (C{radiansPI2}) '''
'''Convert and wrap degrees to radians M{[-3PI/2..+PI/2]}.
@arg deg: Angle (C{degrees}).
@return: Radians, wrapped (C{radiansPI_2}) '''
'''Convert an angle to a distance along the equator or along the parallel at an other (geodetic) latitude.
@arg rad: The angle (C{radians}). @kwarg radius: Mean earth radius, ellipsoid or datum (C{meter}, L{Ellipsoid}, L{Ellipsoid2}, L{Datum} or L{a_f2Tuple}). @kwarg lat: Parallel latitude (C{degrees90}, C{str}).
@return: Distance (C{meter}, same units as B{C{radius}} or ellipsoidal and polar radii) or C{0} for near-polar B{C{lat}}.
@raise RangeError: Latitude B{C{lat}} outside valid range and L{rangerrors} set to C{True}.
@raise TypeError: Invalid B{C{radius}}.
@raise ValueError: Invalid B{C{rad}}, B{C{radius}} or B{C{lat}}.
@see: Function L{degrees2m} and L{m2radians}. '''
'''(INTERNAL) 2-tuple (C{sin(r), cos(r)}) in quadrant M{0 <= q <= 3}. ''' else: # r == PI_2 # q &= 3
'''Return the C{sine} and C{cosine} of angle(s).
@arg rad: One or more angles (C{radians}).
@return: The C{sin(rad)} and C{cos(rad)} for each angle.
@see: U{GeographicLib<https://GeographicLib.SourceForge.io/html/ classGeographicLib_1_1Math.html#sincosd>} function U{sincosd <https://SourceForge.net/p/geographiclib/code/ci/release/tree/ python/geographiclib/geomath.py#l155>} and C++ U{sincosd <https://SourceForge.net/p/geographiclib/code/ci/release/tree/ include/GeographicLib/Math.hpp#l558>}. '''
'''Return the C{sine} and C{cosine} of angle(s) in C{degrees}.
@arg deg: One or more angles (C{degrees}).
@return: The C{sin(deg)} and C{cos(deg)} for each angle.
@see: U{GeographicLib<https://GeographicLib.SourceForge.io/html/ classGeographicLib_1_1Math.html#sincosd>} function U{sincosd <https://SourceForge.net/p/geographiclib/code/ci/release/tree/ python/geographiclib/geomath.py#l155>} and C++ U{sincosd <https://SourceForge.net/p/geographiclib/code/ci/release/tree/ include/GeographicLib/Math.hpp#l558>}. '''
'''Split an iterable into C{n} slices.
@arg iterable: Items to be spliced (C{list}, C{tuple}, ...). @kwarg n: Number of slices to generate (C{int}). @kwarg fill: Optional fill value for missing items.
@return: A generator for each of B{C{n}} slices, M{iterable[i::n] for i=0..n}.
@raise TypeError: Invalid B{C{n}}.
@note: Each generated slice is a C{tuple} or a C{list}, the latter only if the B{C{iterable}} is a C{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...> ''' raise _TypeError(n=n)
# XXX t[i::n] chokes PyChecker else: yield t
'''Compute the tangent of half angle.
@arg rad: Angle (C{radians}). @kwarg semi: Angle or edge name and index for semi-circular error.
@return: M{tan(rad / 2)} (C{float}).
@raise ValueError: If B{C{rad}} is semi-circular and B{C{semi}} is given. ''' # .formy.excessKarney_, .sphericalTrigonometry.areaOf else: n = _SPACE_(n, _radians_) raise _ValueError(n, rad, txt=_semi_circular_)
'''Compute the tangent of half angle, 90 degrees rotated.
@arg rad: Angle (C{radians}).
@return: M{tan((rad + PI/2) / 2)} (C{float}). '''
'''Unroll longitudinal delta and wrap longitude in degrees.
@arg lon1: Start longitude (C{degrees}). @arg lon2: End longitude (C{degrees}). @kwarg wrap: Wrap and unroll to the M{(-180..+180]} range (C{bool}).
@return: 2-Tuple C{(B{lon2}-B{lon1}, B{lon2})} unrolled (C{degrees}, C{degrees}).
@see: Capability C{LONG_UNROLL} in U{GeographicLib <https://GeographicLib.SourceForge.io/html/python/interface.html#outmask>}. '''
'''Unroll longitudinal delta and wrap longitude in radians.
@arg rad1: Start longitude (C{radians}). @arg rad2: End longitude (C{radians}). @kwarg wrap: Wrap and unroll to the M{(-PI..+PI]} range (C{bool}).
@return: 2-Tuple C{(B{rad2}-B{rad1}, B{rad2})} unrolled (C{radians}, C{radians}).
@see: Capability C{LONG_UNROLL} in U{GeographicLib <https://GeographicLib.SourceForge.io/html/python/interface.html#outmask>}. '''
'''(INTERNAL) Angle wrapper M{((wrap-modulo)..+wrap]}.
@arg angle: Angle (C{degrees}, C{radians} or C{grades}). @arg wrap: Range (C{degrees}, C{radians} or C{grades}). @arg modulo: Upper limit (360 C{degrees}, PI2 C{radians} or 400 C{grades}).
@return: The B{C{angle}}, wrapped (C{degrees}, C{radians} or C{grades}). ''' else: # math.fmod(-1.5, 3.14) == -1.5, but -1.5 % 3.14 == 1.64 # math.fmod(-1.5, 360) == -1.5, but -1.5 % 360 == 358.5
'''Wrap degrees to M{[-270..+90]}.
@arg deg: Angle (C{degrees}).
@return: Degrees, wrapped (C{degrees90}). '''
'''Wrap degrees to M{[-180..+180]}.
@arg deg: Angle (C{degrees}).
@return: Degrees, wrapped (C{degrees180}). '''
'''Wrap degrees to M{[0..+360)}.
@arg deg: Angle (C{degrees}).
@return: Degrees, wrapped (C{degrees360}). '''
'''Wrap radians to M{[-PI..+PI]}.
@arg rad: Angle (C{radians}).
@return: Radians, wrapped (C{radiansPI}). '''
'''Wrap radians to M{[0..+2PI)}.
@arg rad: Angle (C{radians}).
@return: Radians, wrapped (C{radiansPI2}). '''
'''Wrap radians to M{[-3PI/2..+PI/2]}.
@arg rad: Angle (C{radians}).
@return: Radians, wrapped (C{radiansPI_2}). '''
'''Convert I{UK} yards to meter.
@arg yards: Value in yards (C{scalar}).
@return: Value in C{meter} (C{float}).
@raise ValueError: Invalid B{C{yards}}. ''' # 0.9144 == 254 * 12 * 3 / 10_000 == 3 * ft2m(1) Int'l
# **) MIT License # # Copyright (C) 2016-2021 -- mrJean1 at Gmail -- All Rights Reserved. # # Permission is hereby granted, free of charge, to any person obtaining a # copy of this software and associated documentation files (the "Software"), # to deal in the Software without restriction, including without limitation # the rights to use, copy, modify, merge, publish, distribute, sublicense, # and/or sell copies of the Software, and to permit persons to whom the # Software is furnished to do so, subject to the following conditions: # # The above copyright notice and this permission notice shall be included # in all copies or substantial portions of the Software. # # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS # OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL # THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR # OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, # ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR # OTHER DEALINGS IN THE SOFTWARE. |