Package pygeodesy |
[frames] | no frames]

# Package pygeodesy

A pure Python implementation of geodesy tools for various ellipsoidal and spherical earth models using precision trigonometric, vector-based, elliptic and approximate methods for geodetic (lat-/longitude) and geocentric cartesian (x/y/z) coordinates.

Transcribed from JavaScript originals by Chris Veness (C) 2005-2016 and several C++ classes by Charles Karney (C) 2008-2017 and published under the same MIT License**.

There are three modules for ellipsoidal earth models, ellipsoidalKarney, -Vincenty and -Nvector and two for spherical ones, sphericalTrigonometry and -Nvector. Each module provides a LatLon class with methods and functions to compute distance, initial and final bearing, intermediate and nearest points, area, perimeter, conversions and unrolling, among other things. For more information and further details see the documentation, the descriptions of Latitude/Longitude, Vincenty and Vector-based geodesy, the original JavaScript source or docs and the Python GeographicLib.

Also included are modules for conversions to and from Cassini-Soldner, UPS (Universal Polar Stereographic), UTM (Exact and Universal Transverse Mercator) and Web Mercator (Pseudo-Mercator) coordinates, MGRS (NATO Military Grid Reference System) and OSGR (British Ordinance Survery Grid Reference) grid references, TRF (Terrestrial Reference Frames) and modules to encode and decode EPSG, Geohashes, Georefs (WGRS) and Garefs (GARS).

Other modules provide Lambert conformal conic projections and positions (from John P. Snyder, "Map Projections -- A Working Manual", 1987, pp 107-109), functions to clip a path or polygon of `LatLon` points using the Cohen–Sutherland and the Sutherland-Hodgman methods, functions to simplify or linearize a path of `LatLon` points (or a NumPy array), including implementations of the Ramer-Douglas-Peucker the Visvalingam-Whyatt and Reumann-Witkam the algorithms and modified versions of the former. Other classes interpolate the height of `LatLon` points and several `Geoid` models or compute various Fréchet or Hausdorff distances.

# Installation

To install PyGeodesy, type `pip install PyGeodesy` or `easy_install PyGeodesy` in a terminal or command window. Alternatively, download `PyGeodesy-yy.m.d.zip` from PyPI or GitHub, `unzip` the downloaded file, `cd` to directory `Pygeodesy-yy.m.d` and type `python setup.py install`. To run all PyGeodesy tests, type `python setup.py test` before installation.

Installation of GeographicLib, NumPy and SciPy is optional. However, the former is required for module css classes CassiniSoldner and Css and function toCss, for module ellipsoidalKarney classes `LatLon` and `Cartesian` and functions `areaOf` and `perimeterOf` and for the HeightIDWkarney interpolator. The latter are needed for the `Geoid...` and `Height...` interpolator classes, except GeoidKarney and all `HeightIDW...`.

# Documentation

In addition to the `pygeodesy` package, the PyGeodesy distribution files contain the tests, the test results (on macOS only) and the complete documentation (generated by Epydoc using command line: `epydoc --html --no-private --no-source --name=PyGeodesy --url=... -v pygeodesy`).

# Tests

The tests have been run with Python 2.7.16 and 3.7.4 (both with geographiclib 1.49, numpy 1.16.4 and scipy 1.2.2 respectively 1.3.0) and with PyPy 6.0.0 (Python 2.7.13 and 3.5.3) on macOS 10.13.6 High Sierra, all in 64-bit only. The results of those tests are included in the distribution files.

The tests also run with Python 2.7.14, 3.5.6 and 3.6.3 (and geographiclib 1.49) on Ubuntu 14.04 and with Python 3.7.3 (and geographiclib 1.49) on Debian 9 all in 64-bit only and with Python 2.7.15, 3.6.8 and 3.7.2 (all with geographiclib 1.49) on Windows Server 2012R2 in both 32- and 64-bit.

with Python 3.7+, the tests run with and without `lazy import`.

A single-File and single-Directory application with `pygeodesy` has been bundled using PyInstaller 3.4 and 64-bit Python 3.7.3 on macOS 10.13.6 High Sierra.

Previously, the tests were run with Python 2.6.9 (and numpy 1.6.2), 2.7.10 (and numpy 1.8.0rc1), 2.7.13, 2.7.14, 2.7.15 (and numpy 1.13.1, 1.14.0, 1.15.2 or 1.16.2), 3.5.3, 3.6.2, 3.6.3, 3.6.4, 3.6.5, 3.7.0, 3.7.2, 3.7.3 and Intel-Python 3.5.3 (and numpy 1.11.3) on MacOS X 10.10 Yosemite, MacOS X 10.11 El Capitan, macOS 10.12 Sierra, macOS 10.13.5 High Sierra and macOS 10.14 Mojave, with Pythonista 3.1 on iOS 10.3.3, 11.0.3, 11.1.2 and 11.3 on iPad4, with Pythonista 3.2 (with geographiclib 1.49 and numpy 1.8.0) on iOS 11.4.1, 12.0, 12.2 and 12.3 on iPad4, iPhone6 and/or iPhone10, all in 64-bit only and with 32-bit Python 2.6.6 on Windows XP SP3 and with 32-bit Python 2.7.14 on Windows 10 Pro.

# Notes

All Python source code has been statically checked with PyChecker, PyFlakes, PyCodeStyle (formerly Pep8) and McCabe using Python 2.7.16 and with Flake8 using Python 3.7.4, both in 64-bit on macOS 10.13.6 High Sierra.

Some function and method names differ from the JavaScript version. In such cases documentation tag JS name: shows the original JavaScript name.

# License

**) Copyright (C) 2016-2019 -- mrJean1 at Gmail dot com

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

Version: 19.09.16

Submodules
pygeodesy.__main__: Print pygeodesy version, etc. pygeodesy.bases: (INTERNAL) Common base classes. pygeodesy.clipy: Functions to clip a path or polygon of `LatLon` points against a rectangular box or clip region. pygeodesy.css: Cassini-Soldner projection classes CassiniSoldner, Css and CSSError requiring Charles Karney's geographiclib package to be installed. pygeodesy.datum: Classes Datum, Ellipsoid and Transform and registries thereof Datums, Ellipsoids and Transforms, respectively. pygeodesy.deprecated: DEPRECATED classes, functions, etc. pygeodesy.dms: Functions to parse and format bearing, compass, lat- and longitudes in various forms of degrees, minutes and seconds. pygeodesy.elevations: Functions to obtain elevations and geoid heights thru web services, for (lat, lon) locations, currently limited to the Conterminous US (CONUS), see also module geoids and classes GeoidG2012B, GeoidKarney and GeoidPGM and USGS10mElev.py. pygeodesy.ellipsoidalBase: (INTERNAL) Ellipsoidal base classes. pygeodesy.ellipsoidalKarney: Ellipsoidal geodetic (lat-/longitude) and cartesian (x/y/z) classes LatLon and Cartesian and functions areaOf and perimeterOf based on Charles Karney's Python implementation of GeographicLib. pygeodesy.ellipsoidalNvector: N-vector-based ellipsoidal geodetic (lat-/longitude) and cartesion (x/y/z) classes LatLon, Ned, Nvector and Cartesian and functions meanOf and toNed. pygeodesy.ellipsoidalVincenty: Vincenty's ellipsoidal geodetic (lat-/longitude) and cartesian (x/y/z) classes LatLon, Cartesian and VincentyError and functions areaOf and perimeterOf. pygeodesy.elliptic: Elliptic integrals and functions transcribed from Charles Karney's C++ class EllipticFunction into pure Python class Elliptic. pygeodesy.epsg: Classes Epsg and EPSGError and functions to encode and decode2 European Petroleum Survey Group (EPSG) codes from and to UTM and UPS zones. pygeodesy.etm: Classes ETMError and Etm, a pure Python implementation of Charles Karney's C++ class TransverseMercatorExact, abbreviated as `TMExact` below. pygeodesy.fmath: Precision floating point functions, utilities and constants. pygeodesy.formy: Formulary of basic geodesy functions and approximations. pygeodesy.frechet: Classes Frechet, FrechetDegrees, FrechetRadians, FrechetEquirectangular, FrechetEuclidean, FrechetHaversine, and FrechetVincentys to compute discrete Fréchet distances between two sets of `LatLon`, `NumPy`, `tuples` or other types of points. pygeodesy.gars: Classes Garef and GARSError and several functions to encode, decode and inspect Global Area Reference System (GARS) references. pygeodesy.geohash: Classes Geohash and GeohashError and several functions to encode, decode and inspect geohashes. pygeodesy.geoids: Classes GeoidG2012B, GeoidKarney and GeoidPGM to interpolate the height of various geoids at `LatLon` locations or separate lat-/longitudes using different interpolation methods and `geoid` files. pygeodesy.hausdorff: Classes Hausdorff, HausdorffDegrees, HausdorffRadians, HausdorffEquirectangular, HausdorffEuclidean, HausdorffHaversine, HausdorffKarney and HausdorffVincentys to compute Hausdorff distances between two sets of `LatLon`, `NumPy`, `tuples` or other types of points. pygeodesy.heights: Classes HeightCubic, HeightIDWequirectangular, HeightIDWeuclidean, HeightIDWhaversine, HeightIDWkarney, HeightIDWvincentys, HeightLinear, HeightLSQBiSpline and HeightSmoothBiSpline to interpolate the height of `LatLon` locations or separate lat-/longitudes from a set of `LatLon` points with known heights. pygeodesy.lazily: Lazily import `pygeodesy` modules and attributes, based on lazy_import from Brett Cannon's modutil. pygeodesy.lcc: Lambert conformal conic projection for 1- or 2-Standard Parallels classes Conic, Conics registry, LCCError and position class Lcc. pygeodesy.mgrs: Military Grid Reference System (MGRS/NATO) classes Mgrs and MGRSError and functions parseMGRS and toMgrs. pygeodesy.named: (INTERNAL) Classes `_Named`, `_NamedDict`, `_NamedInt`, `_NamedStr` and `_NamedTuple` with nameable instances and several subclasses thereof. pygeodesy.nvector: N-vector base class Nvector and function sumOf. pygeodesy.osgr: Ordinance Survey Grid References (OSGR) classes Osgr an OSGRError and functions parseOSGR and toOsgr. pygeodesy.points: Functions to handle collections and sequences of `LatLon` points specified as 2-d NumPy, `arrays` or tuples as `LatLon` or as `pseudo-x/-y` pairs. pygeodesy.simplify: Seven functions to simplify or linearize a path of `LatLon` points. pygeodesy.sphericalBase: (INTERNAL) Spherical base classes. pygeodesy.sphericalNvector: N-vector-based spherical geodetic (lat-/longitude) classes LatLon and Nvector and functions areaOf, intersection, meanOf, nearestOn2, triangulate and trilaterate. pygeodesy.sphericalTrigonometry: Trigonometric spherical geodetic (lat-/longitude) class LatLon and functions areaOf, intersection, isPoleEnclosedBy, meanOf, nearestOn2 and perimeterOf. pygeodesy.trf: Terrestrial Reference Frame (TRF) classes RefFrame, registry RefFrames and TRFError. pygeodesy.ups: Universal Polar Stereographic (UPS) classes Ups and UPSError and functions parseUPS5, toUps8 and upsZoneBand5. pygeodesy.utily: Geometric and other utility functions and constants. pygeodesy.utm: Universal Transverse Mercator (UTM) classes Utm and UTMError and functions parseUTM5, toUtm8 and utmZoneBand5. pygeodesy.utmups: Functions parseUTMUPS5, toUtmUps8, UtmUps and utmupsZoneBand5 to handle both Universal Transverse Mercator (UTM) and Universal Polar Stereographic (UPS) coordinates. pygeodesy.utmupsBase: (INTERNAL) Some UTM, UPS, Mgrs and Epsg functions. pygeodesy.vector3d: Generic 3-D vector base class Vector3d and function sumOf. pygeodesy.webmercator: Web Mercator (WM) classes Wm and WebMercatorError and functions parseWM and toWm. pygeodesy.wgrs: Classes Georef and WGRSError and several functions to encode, decode and inspect World Geographic Reference System (WGRS) references.

Classes
| LazyImportError Lazy import is not supported, disabled or failed some other way.
| VincentyError Error raised from Vincenty's direct and inverse methods for coincident points or lack of convergence.
| Epsg EPSG class, a `_NamedInt`.
| EPSGError European Petroleum Survey Group (EPSG) encode, decode or other Epsg issue.
| Garef Garef class, a `_NamedStr`.
| GARSError Global Area Reference System (GARS) encode, decode or other Garef issue.
| Geohash Geohash class, a _NamedStr.
| GeohashError Geohash encode, decode or other Geohash issue.
| CrossError Error raised for zero or near-zero vectorial cross products, occurring for coincident or colinear points, paths or bearings.
| VectorError Vector3d or `*Nvector` issue.
| Georef Georef class, a `_NamedStr`.
| WGRSError World Geographic Reference System (WGRS) encode, decode or other Georef issue.
| CSSError Cassini-Soldner (CSS) conversion or other Css issue.
| CassiniSoldner A Python version of Karney's C++ class CassiniSoldner.
| Conic Lambert conformal conic projection (1- or 2-SP).
| Css Cassini-Soldner East-/Northing location.
| Datum Ellipsoid and transform parameters for an earth model.
| ETMError Exact Transverse Mercator (ETM) parse, projection or other Etm issue.
| Ellipsoid Ellipsoid with major and minor radius, semi-axis, (inverse) flattening and other pre-computed, frequently used attributes.
| Elliptic Elliptic integrals and functions.
| EllipticError Elliptic integral, function, convergence or other Elliptic issue.
| Etm Exact Transverse Mercator (ETM) coordinate, a sub-class of Utm, a Universal Transverse Mercator (UTM) coordinate using the ExactTransverseMercator projection for highest accuracy.
| ExactTransverseMercator A Python version of Karney's TransverseMercatorExact C++ class, a numerically exact transverse mercator projection, referred to as `TMExact` here.
| Fdot Precision dot product.
| Fhorner Precision polynomial evaluation using the Horner form.
| Fpolynomial Precision polynomial evaluation.
| Frechet Frechet base class, requires method Frechet.distance to be overloaded.
| FrechetDegrees Frechet base class for distances in `degrees` from `LatLon` points in `degrees`.
| FrechetEquirectangular Compute the `Frechet` distance based on the `equirectangular` distance (in radians squared) like function equirectangular_.
| FrechetError Fréchet issue.
| FrechetEuclidean Compute the `Frechet` distance based on the `Euclidean` distance (in radians) from function euclidean_.
| FrechetHaversine Compute the `Frechet` distance based on the angular `Haversine` distance (in radians) from function haversine_.
| FrechetRadians Frechet base class for distances in `radians` from `LatLon` points converted from `degrees` to `radians`.
| FrechetVincentys Compute the `Frechet` distance based on the angular `Vincenty` distance (in radians) from function vincentys_.
| Fsum Precision summation similar to standard Python function `math.fsum`.
| GeoidError Geoid interpolator `Geoid...` or interpolation issue.
| GeoidG2012B Geoid height interpolator for GEOID12B Model grids CONUS, Alaska, Hawaii, Guam and Northern Mariana Islands, Puerto Rico and U.S. Virgin Islands and American Samoa based on `SciPy` RectBivariateSpline or interp2d interpolation.
| GeoidKarney Geoid height interpolator for Charles Karney's GeographicLib Earth Gravitational Model (EGM) geoid egm*.pgm datasets using bilinear or cubic interpolation and caching in pure Python transcribed from Karney's C++ class Geoid.
| GeoidPGM Geoid height interpolator for Charles Karney's GeographicLib Earth Gravitational Model (EGM) geoid egm*.pgm datasets but based on `SciPy` RectBivariateSpline or interp2d interpolation.
| Hausdorff Hausdorff base class, requires method Hausdorff.distance to be overloaded.
| HausdorffDegrees Hausdorff base class for distances in `degrees` from `LatLon` points in `degrees`.
| HausdorffEquirectangular Compute the `Hausdorff` distance based on the `equirectangular` distance (in radians squared) like function equirectangular_.
| HausdorffError Hausdorff issue.
| HausdorffEuclidean Compute the `Hausdorff` distance based on the `Euclidean` distance (in radians) from function euclidean_.
| HausdorffHaversine Compute the `Hausdorff` distance based on the angular `Haversine` distance (in radians) from function haversine_.
| HausdorffKarney Compute the `Hausdorff` distance based on the angular distance (in degrees) from Charles Karney's GeographicLib Geodesic Inverse method.
| HausdorffRadians Hausdorff base class for distances in `radians` from `LatLon` points converted from `degrees` to `radians`.
| HausdorffVincentys Compute the `Hausdorff` distance based on the angular `Vincenty` distance (in radians) from function vincentys_.
| HeightCubic Height interpolator based on `SciPy` interp2d `kind='cubic'`.
| HeightError Height interpolator `Height...` or interpolation issue.
| HeightIDW Height interpolator using Inverse Distance Weighting (IDW) and the `Euclidean` distance from function euclidean_.
| HeightIDW2 Height interpolator using Inverse Distance Weighting (IDW) and the `equirectangular` distance (in radians squared) like function equirectangular_.
| HeightIDW3 Height interpolator using Inverse Distance Weighting (IDW) and the angular `Haversine` distance from function haversine_.
| HeightIDWequirectangular Height interpolator using Inverse Distance Weighting (IDW) and the `equirectangular` distance (in radians squared) like function equirectangular_.
| HeightIDWeuclidean Height interpolator using Inverse Distance Weighting (IDW) and the `Euclidean` distance from function euclidean_.
| HeightIDWhaversine Height interpolator using Inverse Distance Weighting (IDW) and the angular `Haversine` distance from function haversine_.
| HeightIDWkarney Height interpolator using Inverse Distance Weighting (IDW) and the angular distance from Charles F. F. Karney's GeographicLib Geodesic Inverse method.
| HeightIDWvincentys Height interpolator using Inverse Distance Weighting (IDW) and the angular `Vincenty` distance from function vincentys_.
| HeightLSQBiSpline Height interpolator using `SciPy` LSQSphereBivariateSpline.
| HeightLinear Height interpolator based on `SciPy` interp2d `kind='linear`.
| HeightSmoothBiSpline Height interpolator using `SciPy` SmoothSphereBivariateSpline.
| LCCError Lambert Conformal Conic `LCC` or other Lcc issue.
| LatLon2psxy Wrapper for `LatLon` points as "on-the-fly" pseudo-xy coordinates.
| LatLonHeightBase (INTERNAL) Base class for `LatLon` points on spherical or ellipsiodal earth models.
| LatLon_ Low-overhead `LatLon` class for Numpy2LatLon and Tuple2LatLon.
| Lcc Lambert conformal conic East-/Northing location.
| LimitError Error raised for lat- or longitudinal deltas exceeding the `limit` in functions equirectangular and equirectangular_.
| MGRSError Military Grid Reference System (MGRS) parse or other Mgrs issue.
| Mgrs Military Grid Reference System (MGRS/NATO) references, with method to convert to UTM coordinates.
| Numpy2LatLon Wrapper for `NumPy` arrays as "on-the-fly" `LatLon` points.
| OSGRError Ordinance Survey Grid References (OSGR) parse or other Osgr issue.
| Osgr Ordinance Survey Grid References (OSGR) coordinate.
| PGMError Issue parsing or cropping an `egm*.pgm` geoid dataset.
| RangeError Error raised for lat- or longitude values outside the `clip`, `clipLat`, `clipLon` or `limit` range in function clipDMS, parse3llh, parseDMS or parseDMS2.
| RefFrame Terrestrial Reference Frame (TRF) parameters.
| RefFrameError Terrestrial Reference Frame (TRF) or RefFrame conversion issue.
| SciPyError Error raised for `SciPy` errors.
| SciPyWarning Exception thrown for `SciPy` warnings.
| TRFError Terrestrial Reference Frame (TRF) or RefFrame conversion issue.
| Transform Helmert transformation.
| Tuple2LatLon Wrapper for tuple sequences as "on-the-fly" `LatLon` points.
| UPSError Universal Polar Stereographic (UPS) parse or other Ups issue.
| UTMError Universal Transverse Mercator (UTM parse or other Utm issue.
| UTMUPSError Universal Transverse Mercator/Universal Polar Stereographic (UTM/UPS) parse, validate or other issue.
| Ups Universal Polar Stereographic (UPS) coordinate.
| Utm Universal Transverse Mercator (UTM) coordinate.
| WebMercatorError Web Mercator (WM) parse or Wm issue.
| Wm Web Mercator (WM) coordinate.

Functions
crosserrors(raiser=None) Get/set raising of vectorial cross product errors. |
UtmUps(zone, hemipole, easting, northing, band=`'````'`, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, falsed=True, name=`'````'`) Class-like function to create a UTM/UPS coordinate. |
acos1(x) Return math.acos(max(-1, min(1, x))). |
anStr(name, OKd=`'``._-``'`, sub=`'``_``'`) Make a valid name of alphanumeric and OKd characters. |
antipode(lat, lon) Return the antipode, the point diametrically opposite to a given point. |
areaOf(points, adjust=True, radius=6371008.77141, wrap=True) Approximate the area of a polygon. |
areaof(points, adjust=True, radius=_R_M, wrap=True) DEPRECATED, use function areaOf. |
bearing(lat1, lon1, lat2, lon2, **options) Compute the initial or final bearing (forward or reverse azimuth) between a (spherical) start and end point. |
bearingDMS(bearing, form=`'``d``'`, prec=None, sep=`'````'`) Convert bearing to a string. |
bearing_(a1, b1, a2, b2, final=False, wrap=False) Compute the initial or final bearing (forward or reverse azimuth) between a (spherical) start and end point. |
bounds(points, wrap=True, LatLon=None) DEPRECATED, use function boundsOf. |
boundsOf(points, wrap=True, LatLon=None) Determine the lower-left SW and upper-right NE corners of a path or polygon. |
cbrt(x) Compute the cubic root x**(1/3). |
cbrt2(x) Compute the cubic root squared x**(2/3). |
centroidOf(points, wrap=True, LatLon=None) Determine the centroid of a polygon. |
classname(inst, prefixed=None) Return the instance' class name optionally prefixed with the module name. |
classnaming(prefixed=None) Get/set the default naming for `[module.]class` names. |
clipCS3(points, lowerleft, upperright, closed=False, inull=False) Clip a path against a rectangular clip box using the Cohen-Sutherland algorithm. |
clipDMS(deg, limit) Clip a lat- or longitude to the given range. |
clipSH(points, corners, inull=False, closed=False) Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm. |
clipSH3(points, corners, inull=False, closed=False) Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm. |
clipStr(bstr, limit=50, white=`'````'`) Clip a string to the given length limit. |
compassAngle(lat1, lon1, lat2, lon2, adjust=True, wrap=False) Return the angle from North for the direction vector (lon2 - lon1, lat2 - lat1) between two points. |
compassDMS(bearing, form=`'``d``'`, prec=None, sep=`'````'`) Convert bearing to a string suffixed with compass point. |
compassPoint(bearing, prec=3) Convert bearing to a compass point. |
date2epoch(year, month, day) Return the reference frame `epoch` for a calendar day. |
decodeEPSG2(arg) DEPRECATED, use function epsg.decode2. |
degDMS(deg, prec=6, s_D=`'``°``'`, s_M=`'``′``'`, s_S=`'``″``'`, neg=`'``-``'`, pos=`'````'`) Convert degrees to a string in degrees, minutes or seconds. |
degrees(x) Convert angle x from radians to degrees. |
degrees180(rad) Convert radians to degrees and wrap [-180..+180]. |
degrees2m(deg, radius=6371008.77141, lat=0) Convert angle to distance along the equator or along a parallel at an other latitude. |
degrees360(rad) Convert radians to degrees and wrap [0..+360). |
degrees90(rad) Convert radians to degrees and wrap [-270..+90]. |
egmGeoidHeights(GeoidHeights_dat) Generate geoid egm*.pgm height tests from GeoidHeights.dat Test data for Geoids. |
elevation2(lat, lon, timeout=2.0) Get the geoid elevation at an `NAD83` to `NAVD88` location. |
enStr2(easting, northing, prec, *extras) Return easting, northing string representations. |
encodeEPSG(zone, hemipole=`'````'`, band=`'````'`) DEPRECATED, use function epsg.encode. |
equirectangular(lat1, lon1, lat2, lon2, radius=6371008.77141, **options) Compute the distance between two points using the Equirectangular Approximation / Projection. |
equirectangular3(lat1, lon1, lat2, lon2, **options) DEPRECATED, use function `equirectangular_`. |
equirectangular_(lat1, lon1, lat2, lon2, adjust=True, limit=45, wrap=False) Compute the distance between two points using the Equirectangular Approximation / Projection. |
euclidean(lat1, lon1, lat2, lon2, radius=6371008.77141, adjust=True, wrap=False) Approximate the `Euclidian` distance between two (spherical) points. |
euclidean_(a2, a1, b21, adjust=True) Approximate the angular `Euclidean` distance between two (spherical) points. |
fStr(floats, prec=6, sep=`'``,` `'`, fmt=`'``%.*f``'`, ints=False) Convert floats to string, optionally with trailing zero decimals stripped. |
fStrzs(fstr) Strip trailing zero decimals from a float string. |
false2f(value, name=`'``value``'`, false=True, Error=<type 'exceptions.ValueError'>) Convert a false east-/northing to non-negative float. |
favg(v1, v2, f=0.5) Return the weighted average of two values. |
fdot(a, *b) Return the precision dot product sum(a[i] * b[i] for i=0..len(a)). |
fdot3(a, b, c, start=0) Return the precision dot product start + sum(a[i] * b[i] * c[i] for i=0..len(a)). |
fhorner(x, *cs) Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)) using the Horner form. |
fidw(xs, ds, beta=2) Interpolate using using Inverse Distance Weighting (IDW). |
fmean(xs) Compute the accurate mean sum(xs[i] for i=0..len(xs)) / len(xs). |
fpolynomial(x, *cs) Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)). |
fpowers(x, n, alts=0) Return a series of powers [x**i for i=1..n]. |
fprod(iterable, start=1.0) Iterable product, like `math.prod` or `numpy.prod`. |
fractional(points, fi, LatLon=None) Return the point at a given fractional index. |
frange(start, number, step=1) Generate a range of `float`s. |
frechet_(points1, points2, distance=None, units=`'````'`) Compute the discrete Fréchet distance between two paths given as sets of points. |
value |
freduce(function, sequence, initial=...) Apply a function of two arguments cumulatively to the items of a sequence, from left to right, so as to reduce the sequence to a single value. |
fsum(iterable) Return an accurate floating point sum of values in the iterable. |
fsum_(*xs) Precision summation of the positional argument vulues. |
ft2m(feet, usurvey=False) Convert International or US Survey feet to meter. |
geoidHeight2(lat, lon, model=0, timeout=2.0) Get the `NAVD88` geoid height at an `NAD83` location. |
halfs2(str2) Split a string in 2 halfs. |
hausdorff_(model, target, both=False, early=True, seed=None, units=`'````'`, distance=None, point=<function _point at 0x10970b050>) Compute the `directed` or `symmetric` Hausdorff distance between 2 sets of points with or without early breaking and random sampling. |
haversine(lat1, lon1, lat2, lon2, radius=6371008.77141, wrap=False) Compute the distance between two (spherical) points using the Haversine formula. |
haversine_(a2, a1, b21) Compute the angular distance between two (spherical) points using the Haversine formula. |
heightOf(angle, distance, radius=6371008.77141) Determine the height above the (spherical) earth after traveling along a straight line at a given tilt. |
horizon(height, radius=6371008.77141, refraction=False) Determine the distance to the horizon from a given altitude above the (spherical) earth. |
hypot(x, y) Return the Euclidean distance, sqrt(x*x + y*y). |
hypot1(x) Compute the norm sqrt(1 + x**2). |
hypot3(x, y, z) (DEPRECATED), use function hypot_. |
hypot_(*xs) Compute the norm sqrt(sum(xs[i]**2)) for i=0..len(xs). |
inStr(inst, *args, **kwds) Return the string representation of an instance. |
isNumpy2(obj) Check for an `Numpy2LatLon` points wrapper. |
isPoints2(obj) Check for an `LatLon2psxy` points wrapper. |
isTuple2(obj) Check for an `Tuple2LatLon` points wrapper. |
isantipode(lat1, lon1, lat2, lon2, eps=2.22044604925e-16) Check whether two points are antipodal, on diametrically opposite sides of the earth. |
isclockwise(points, adjust=False, wrap=True) Determine the direction of a path or polygon. |
isconvex(points, adjust=False, wrap=True) Determine whether a polygon is convex. |
isconvex_(points, adjust=False, wrap=True) Determine whether a polygon is convex and clockwise. |
isenclosedBy(point, points, wrap=False) Determine whether a point is enclosed by a polygon. |
isenclosedby(point, points, wrap=False) DEPRECATED, use function isenclosedBy. |
isfinite(obj) Check for `Inf` and `NaN` values. |
bool |
isinf(x) Check if float x is infinite (positive or negative). |
isint(obj, both=False) Check for integer type or integer value. |
bool |
isnan(x) Check if float x is not a number (NaN). |
isneg0(obj) Check for NEG0, negative 0.0. |
ispolar(points, wrap=False) Check whether a polygon encloses a pole. |
isscalar(obj) Check for scalar types. |
issequence(obj, *excluded) Check for sequence types. |
issubclassof(sub, sup) Check whether a class is a subclass of a super class. |
iterNumpy2(obj) Iterate over Numpy2 wrappers or other sequences exceeding the threshold. |
iterNumpy2over(n=None) Get or set the iterNumpy2 threshold. |
latDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`) Convert latitude to a string, optionally suffixed with N or S. |
len2(seq) Make built-in function `len` work for generators, iterators, etc. |
limiterrors(raiser=None) Get/set the raising of limit errors. |
lonDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`) Convert longitude to a string, optionally suffixed with E or W. |
m2NM(meter) Convert meter to nautical miles (NM). |
m2SM(meter) Convert meter to statute miles (SM). |
m2degrees(meter, radius=6371008.77141) Convert distance to angle along equator. |
m2ft(meter, usurvey=False) Convert meter to International or US Survey feet (`ft`). |
m2km(meter) Convert meter to kilo meter (km). |
map1(func, *xs) Apply each argument to a single-argument function and return a tuple of results. |
map2(func, *xs) Apply arguments to a function and return a tuple of results. |
nameof(inst) Get the name of an instance. |
nearestOn3(point, points, closed=False, wrap=False, **options) DEPRECATED, use function nearestOn5. |
nearestOn4(point, points, closed=False, wrap=False, **options) DEPRECATED, use function nearestOn5. |
nearestOn5(point, points, closed=False, wrap=False, LatLon=None, **options) Locate the point on a path or polygon closest to an other point. |
normDMS(strDMS, norm=`'````'`) Normalize all degree ˚, minute ' and second " symbols in a string to the default symbols °, ′ and ″. |
parse3llh(strll, height=0, sep=`'``,``'`, clipLat=90, clipLon=180) Parse a string representing lat-, longitude and height point. |
parseDMS(strDMS, suffix=`'``NSEW``'`, sep=`'````'`, clip=0) Parse a string representing deg°min′sec″ to degrees. |
parseDMS2(strLat, strLon, sep=`'````'`, clipLat=90, clipLon=180) Parse lat- and longitude representions. |
parseETM5(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, name=`'````'`) Parse a string representing a UTM coordinate, consisting of `"zone[band] hemisphere easting northing"`. |
parseMGRS(strMGRS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>, name=`'````'`) Parse a string representing a MGRS grid reference, consisting of zoneBand, grid, easting and northing. |
parseOSGR(strOSGR, Osgr=<class 'pygeodesy.osgr.Osgr'>, name=`'````'`) Parse an OSGR coordinate string to an Osgr instance. |
parseUPS5(strUPS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Ups=<class 'pygeodesy.ups.Ups'>, falsed=True, name=`'````'`) Parse a string representing a UPS coordinate, consisting of `"[zone][band] pole easting northing"` where `zone` is pseudo zone `"00"|"0"|""` and `band` is `'A'|'B'|'Y'|'Z'|''`. |
parseUTM(strUTM, datum=_R_M, Utm=_R_M, name=`'````'`) DEPRECATED, use function parseUTM5. |
parseUTM5(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, name=`'````'`) Parse a string representing a UTM coordinate, consisting of `"zone[band] hemisphere easting northing"`. |
parseUTMUPS5(strUTMUPS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Utm=<class 'pygeodesy.utm.Utm'>, Ups=<class 'pygeodesy.ups.Ups'>, name=`'````'`) Parse a string representing a UTM or UPS coordinate, consisting of `"zone[band] hemisphere/pole easting northing"`. |
parseWM(strWM, radius=6378137.0, Wm=<class 'pygeodesy.webmercator.Wm'>, name=`'````'`) Parse a string representing a WM coordinate, consisting of easting, northing and an optional radius. |
perimeterOf(points, closed=False, adjust=True, radius=6371008.77141, wrap=True) Approximate the perimeter of a path or polygon. |
perimeterof(points, closed=False, adjust=True, radius=_R_M, wrap=True) DEPRECATED, use function perimeterOf. |
points2(points, closed=True, base=None, Error=<type 'exceptions.ValueError'>) Check a polygon represented by points. |
polygon(points, closed=True, base=None) DEPRECATED, use function points2. |
precision(form, prec=None) Set the default precison for a given F_ form. |
property_RO(method) Decorator for `Read_Only` property. |
radians(x) Convert angle x from degrees to radians. |
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]. |
randomrangenerator(seed) Return a `seed`ed random range function generator. |
rangerrors(raiser=None) Gert/set raising of range errors. |
scalar(value, low=2.22044604925e-16, high=1.0, name=`'``scalar``'`, Error=<type 'exceptions.ValueError'>) Validate a scalar. |
simplify1(points, distance, radius=6371008.77141, indices=False, **options) Basic simplification of a path of `LatLon` points. |
simplify2(points, pipe, radius=_R_M, shortest=False, indices=False, **options) DEPRECATED, use function simplifyRW. |
simplifyRDP(points, distance, radius=6371008.77141, shortest=False, indices=False, **options) Ramer-Douglas-Peucker (RDP) simplification of a path of `LatLon` points. |
simplifyRDPm(points, distance, radius=6371008.77141, shortest=False, indices=False, **options) Modified Ramer-Douglas-Peucker (RDPm) simplification of a path of `LatLon` points. |
simplifyRW(points, pipe, radius=6371008.77141, shortest=False, indices=False, **options) Reumann-Witkam (RW) simplification of a path of `LatLon` points. |
simplifyVW(points, area, radius=6371008.77141, attr=None, indices=False, **options) Visvalingam-Whyatt (VW) simplification of a path of `LatLon` points. |
simplifyVWm(points, area, radius=6371008.77141, attr=None, indices=False, **options) Modified Visvalingam-Whyatt (VWm) simplification of a path of `LatLon` points. |
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. |
sqrt3(x) Compute the square root cubed sqrt(x)**3 or sqrt(x**3). |
tanPI_2_2(rad) Compute the tangent of half angle, 90 degrees rotated. |
tan_2(rad) Compute the tangent of half angle. |
toCss(latlon, cs0=None, height=None, Css=<class 'pygeodesy.css.Css'>, name=`'````'`) Convert an (ellipsoidal) geodetic point to a Cassini-Soldner location. |
toDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`, ddd=2, neg=`'``-``'`, pos=`'````'`) Convert signed degrees to string, without suffix. |
toEtm8(latlon, lon=None, datum=None, Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, name=`'````'`, zone=None, **cmoff) Convert a lat-/longitude point to an ETM coordinate. |
toLcc(latlon, conic=Conic(name='WRF_Lb', lat0=40, lon0=-97, par1=33, par2=45, E0=0`...`, height=None, Lcc=<class 'pygeodesy.lcc.Lcc'>, name=`'````'`) Convert an (ellipsoidal) geodetic point to a Lambert location. |
toMgrs(utm, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>, name=`'````'`) Convert a UTM coordinate to an MGRS grid reference. |
toOsgr(latlon, lon=None, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Osgr=<class 'pygeodesy.osgr.Osgr'>, name=`'````'`) Convert a lat-/longitude point to an OSGR coordinate. |
toUps8(latlon, lon=None, datum=None, Ups=<class 'pygeodesy.ups.Ups'>, pole=`'````'`, falsed=True, strict=True, name=`'````'`) Convert a lat-/longitude point to a UPS coordinate. |
toUtm(latlon, lon=None, datum=None, Utm=_R_M, cmoff=True, name=`'````'`) DEPRECATED, use function toUtm8. |
toUtm8(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, name=`'````'`, zone=None, **cmoff) Convert a lat-/longitude point to a UTM coordinate. |
toUtmUps8(latlon, lon=None, datum=None, falsed=True, Utm=<class 'pygeodesy.utm.Utm'>, Ups=<class 'pygeodesy.ups.Ups'>, pole=`'````'`, name=`'````'`, **cmoff) Convert a lat-/longitude point to a UTM or UPS coordinate. |
toWm(latlon, lon=None, radius=6378137.0, Wm=<class 'pygeodesy.webmercator.Wm'>, name=`'````'`) Convert a lat-/longitude point to a WM coordinate. |
unStr(name, *args, **kwds) Return the string representation of an invokation. |
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. |
upsZoneBand5(lat, lon, strict=True) Return the UTM/UPS zone number, (polar) Band letter, pole and clipped lat- and longitude for a given location. |
utmZoneBand2(lat, lon) DEPRECATED, use function utmZoneBand5. |
utmZoneBand5(lat, lon, cmoff=False) Return the UTM zone number, Band letter, hemisphere and (clipped) lat- and longitude for a given location. |
utmupsValidate(coord, falsed=False, MGRS=False) Check a UTM or UPS coordinate. |
utmupsValidateOK(coord, falsed=False, ok=`'``OK``'`) Check a UTM or UPS coordinate. |
utmupsZoneBand5(lat, lon, cmoff=False) Return the UTM/UPS zone number, Band letter, hemisphere/pole and clipped lat- and longitude for a given location. |
vincentys(lat1, lon1, lat2, lon2, radius=6371008.77141, wrap=False) Compute the distance between two (spherical) points using Vincenty's spherical formula. |
vincentys_(a2, a1, b21) Compute the angular distance between two (spherical) points using Vincenty's spherical formula. |
wrap180(deg) Wrap degrees to [-180..+180]. |
wrap360(deg) Wrap degrees to [0..+360). |
wrap90(deg) Wrap degrees to [-270..+90]. |
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
| pygeodesy_abspath = ``'``..../PyGe``...`` Fully qualified `pygeodesy` directory name (`str`).
| version = ``'``19.9.16``'`` Normalized `PyGeodesy` version (`str`).
| Conics = `Conics.Be08Lb: Conic(name='Be08Lb', lat0=50.797815, l`...`` Registered conics (`enum-like`).
| Datums = `Datums.BD72: Datum(name='BD72', ellipsoid=Ellipsoids.`...`` Registered datums (`enum-like`).
| EPS = `2.22044604925e-16` System's epsilon ≈2.22e-16 (`float`).
| EPS1 = `1.0` 1 - EPS ≈0.9999999999999998 (`float`).
| EPS1_2 = `1.0` 1 - EPS_2 ≈0.9999999999999999 (`float`).
| EPS_2 = `1.11022302463e-16` Half system's epsilon ≈1.11e-16 (`float`).
| Ellipsoids = `Ellipsoids.Airy1830: Ellipsoid(name='Airy1830', a`...`` Registered ellipsoids (`enum-like`).
| F_D = ``'``d``'`` Format degrees as unsigned "deg°" plus suffix (`str`).
| F_DEG = ``'``deg``'`` Format degrees as unsigned "[D]DD" plus suffix without symbol (`str`).
| F_DEG_ = ``'``-deg``'`` Format degrees as signed "-/[D]DD" without suffix and symbol (`str`).
| F_DEG__ = ``'``+deg``'`` Format degrees as signed "-/+[D]DD" without suffix and symbol (`str`).
| F_DM = ``'``dm``'`` Format degrees as unsigned "deg°min′" plus suffix (`str`).
| F_DMS = ``'``dms``'`` Format degrees as unsigned "deg°min′sec″" plus suffix (`str`).
| F_DMS_ = ``'``-dms``'`` Format degrees as signed "-/deg°min′sec″" without suffix (`str`).
| F_DMS__ = ``'``+dms``'`` Format degrees as signed "-/+deg°min′sec″" without suffix (`str`).
| F_DM_ = ``'``-dm``'`` Format degrees as signed "-/deg°min′" without suffix (`str`).
| F_DM__ = ``'``+dm``'`` Format degrees as signed "-/+deg°min′" without suffix (`str`).
| F_D_ = ``'``-d``'`` Format degrees as signed "-/deg°" without suffix (`str`).
| F_D__ = ``'``+d``'`` Format degrees as signed "-/+deg°" without suffix (`str`).
| F_MIN = ``'``min``'`` Format degrees as unsigned "[D]DDMM" plus suffix without symbols (`str`).
| F_MIN_ = ``'``-min``'`` Format degrees as signed "-/[D]DDMM" without suffix and symbols (`str`).
| F_MIN__ = ``'``+min``'`` Format degrees as signed "-/+[D]DDMM" without suffix and symbols (`str`).
| F_RAD = ``'``rad``'`` Convert degrees to radians and format as unsigned "RR" plus suffix (`str`).
| F_RAD_ = ``'``-rad``'`` Convert degrees to radians and format as signed "-/RR" without suffix (`str`).
| F_RAD__ = ``'``+rad``'`` Convert degrees to radians and format as signed "-/+RR" without suffix (`str`).
| F_SEC = ``'``sec``'`` Format degrees as unsigned "[D]DDMMSS" plus suffix without symbols (`str`).
| F_SEC_ = ``'``-sec``'`` Format degrees as signed "-/[D]DDMMSS" without suffix and symbols (`str`).
| F_SEC__ = ``'``+sec``'`` Format degrees as signed "-/+[D]DDMMSS" without suffix and symbols (`str`).
| INF = `inf` Infinity (`float`), see `isinf`, `isfinite`.
| MANTIS = `53` System's mantissa bits ≈53 (`int`).
| MAX = `1.79769313486e+308` System's float max ≈1.798e+308 (`float`).
| MIN = `2.22507385851e-308` System's float min ≈2.225e-308 (`float`).
| NAN = `nan` Not-A-Number (`float`), see `isnan`.
| NEG0 = `-0.0` Negative 0.0 (`float`), see `isneg0`.
| OK = ``'``OK``'`` Unique OK object (`str`).
| PI = `3.14159265359` Constant math.pi (`float`).
| PI2 = `6.28318530718` Two PI, math.pi * 2 (`float`).
| PI_2 = `1.57079632679` Half PI, math.pi / 2 (`float`).
| PI_4 = `0.785398163397` Quarter PI, PI / 4 (`float`).
| R_FM = `6371000.0` Former FAI Sphere earth radius (`meter`).
| R_KM = `6371.00877142` Mean (spherical) earth radius (`km`, kilometer).
| R_M = `6371008.77141` Mean (spherical) earth radius (`meter`).
| R_MA = `6378137.0` Major (equatorial) earth radius (`meter`) WGS84, EPSG:3785.
| R_MB = `6356752.0` Minor (polar) earth radius (`meter`) WGS84, EPSG:3785.
| R_NM = `3440.06953447` Mean (spherical) earth radius (`NM`, nautical miles).
| R_SM = `3958.75339537` Mean (spherical) earth radius (`SM`, statute miles).
| R_VM = `6366707.01949` Aviation/Navigation earth radius (`meter`).
| RefFrames = `RefFrames.ETRF2000: RefFrame(name='ETRF2000', epoc`...`` Registered reference frames (`enum-like`).
| S_DEG = ``'``°``'`` Degrees symbol "°" (`str`).
| S_MIN = ``'``′``'`` Minutes symbol "′" (`str`).
| S_RAD = ``'````'`` Radians symbol "" (`str`).
| S_SEC = ``'``″``'`` Seconds symbol "″" (`str`).
| S_SEP = ``'````'`` Separator between deg°, min′ and sec″ "" (`str`).
| Transforms = `Transforms.BD72: Transform(name='BD72', tx=106.86`...`` Registered transforms (`enum-like`).
| isLazy = `None` hash(x)

Function Details

### crosserrors(raiser=None) |
Get/set raising of vectorial cross product errors. Parameters: `raiser` - Use `True` to raise or `False` to ignore CrossError exceptions. Use `None` to leave the setting unchanged. Returns: Previous setting (`bool`).

### UtmUps(zone, hemipole, easting, northing, band=`'````'`, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, falsed=True, name=`'````'`) |
Class-like function to create a UTM/UPS coordinate. Parameters: `zone` - The UTM (longitudinal) zone with/-out Band letter for UTM or for UPS zone `"00"` or `0` (`str` or `int`). `hemipole` - UTM hemisphere or UPS top/center of projection (`str`, `'N[orth]'` or `'S[outh]'`). `easting` - Easting, see `falsed` (`meter`). `northing` - Northing, see `falsed` (`meter`). `band` - Optional, UTM (latitudinal) Band letter `'C'|'D'..'W'|'X'` or UPS (polar) Band letter `'A'|'B'|'Y'|'Z'` (`str`). `datum` - Optional, the coordinate's datum (Datum). `falsed` - Both `easting` and `northing` are falsed (`bool`). `name` - Optional name (`str`). Returns: New UTM or UPS instance (Utm or Ups). Raises: `UTMUPSError` - UTM or UPS validation failed. See Also: Classes Utm and Ups and Karney's UTMUPS.

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

### antipode(lat, lon) |
Return the antipode, the point diametrically opposite to a given point. Parameters: `lat` - Latitude (`degrees`). `lon` - Longitude (`degrees`). Returns: A LatLon2Tuple`(lat, lon)`. See Also: Geosphere.

### areaOf(points, adjust=True, radius=6371008.77141, wrap=True) |
Approximate the area of a polygon. Parameters: `points` - The polygon points (`LatLon`[]). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `radius` - Optional, mean earth radius (`meter`). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: Approximate area (`meter`, same units as `radius`, squared). Raises: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. Note: This area approximation has limited accuracy and is ill-suited for regions exceeding several hundred Km or Miles or with near-polar latitudes. See Also: sphericalNvector.areaOf, sphericalTrigonometry.areaOf and ellipsoidalKarney.areaOf.

### bearing(lat1, lon1, lat2, lon2, **options) |
Compute the initial or final bearing (forward or reverse azimuth) between a (spherical) start and end point. Parameters: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `options` - Optional keyword arguments for function bearing_. Returns: Initial or final bearing (compass `degrees360`) or zero if start and end point coincide.

### bearingDMS(bearing, form=`'``d``'`, prec=None, sep=`'````'`) |
Convert bearing to a string. Parameters: `bearing` - Bearing from North (compass `degrees360`). `form` - Optional `bearing` format (`str` or F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC, F_RAD, F_D_, F_DM_, F_DMS_, F_DEG_, F_MIN_, F_SEC_, F_RAD_, F_D__, F_DM__, F_DMS__, F_DEG__, F_MIN__, F_SEC__ or F_RAD__). `prec` - Optional number of decimal digits (0..9 or `None` for default). Trailing zero decimals are stripped for `prec` values of 1 and above, but kept for negative `prec`. `sep` - Optional separator (`str`). Returns: Compass degrees per the specified `form` (`str`). JS name: toBrng.

### bearing_(a1, b1, a2, b2, final=False, wrap=False) |
Compute the initial or final bearing (forward or reverse azimuth) between a (spherical) start and end point. Parameters: `a1` - Start latitude (`radians`). `b1` - Start longitude (`radians`). `a2` - End latitude (`radians`). `b2` - End longitude (`radians`). `final` - Return final bearing if `True`, initial otherwise (`bool`). `wrap` - Wrap and unrollPI longitudes (`bool`). Returns: Initial or final bearing (compass `radiansPI2`) or zero if start and end point coincide.

### bounds(points, wrap=True, LatLon=None) |
DEPRECATED, use function boundsOf. Returns: 2-Tuple `(latlonSW, latlonNE)` as `LatLon` or 4-Tuple `(latS, lonW, latN, lonE)` if `LatLon` is `None`.

### boundsOf(points, wrap=True, LatLon=None) |
Determine the lower-left SW and upper-right NE corners of a path or polygon. Parameters: `points` - The path or polygon points (`LatLon`[]). `wrap` - Wrap lat- and longitudes (`bool`). `LatLon` - Optional (sub-)class to return the `bounds` corners (`LatLon`) or `None`. Returns: A Bounds2Tuple`(latlonSW, latlonNE)` as `LatLon` or a Bounds4Tuple`(latS, lonW, latN, lonE)` if `LatLon` is `None`. Raises: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. Example:
    >>> b = LatLon(45,1), LatLon(45,2), LatLon(46,2), LatLon(46,1)
    >>> boundsOf(b)  # False
    >>> 45.0, 1.0, 46.0, 2.0

### cbrt(x) |
Compute the cubic root x**(1/3). Parameters: `x` - Value (`scalar`). Returns: Cubic root (`float`). See Also: Functions cbrt2 and sqrt3.

### cbrt2(x) |
Compute the cubic root squared x**(2/3). Parameters: `x` - Value (`scalar`). Returns: Cubic root squared (`float`). See Also: Functions cbrt and sqrt3.

### centroidOf(points, wrap=True, LatLon=None) |
Determine the centroid of a polygon. Parameters: `points` - The polygon points (`LatLon`[]). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). `LatLon` - Optional (sub-)class to return the centroid (`LatLon`) or `None`. Returns: Centroid location (`LatLon`) or a LatLon2Tuple`(lat, lon)` if `LatLon` is `None`. Raises: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points` or `points` enclose a pole or zero area. See Also: Centroid and Calculating The Area And Centroid Of A Polygon.

### classname(inst, prefixed=None) |
Return the instance' class name optionally prefixed with the module name. Parameters: `inst` - The object (any `type`). `prefixed` - Include the module name (`bool`), see function classnaming. Returns: The `inst`'s `[module.]class` name (`str`).

### classnaming(prefixed=None) |
Get/set the default naming for `[module.]class` names. Parameters: `prefixed` - Include the module name (`bool`). Returns: Previous class naming setting (`bool`).

### clipCS3(points, lowerleft, upperright, closed=False, inull=False) |
Clip a path against a rectangular clip box using the Cohen-Sutherland algorithm. Parameters: `points` - The points (`LatLon`[]). `lowerleft` - Bottom-left corner of the clip box (`LatLon`). `upperright` - Top-right corner of the clip box (`LatLon`). `closed` - Optionally, close the path (`bool`). `inull` - Optionally, include null edges if inside (`bool`). Returns: Yield a ClipCS3Tuple`(start, end, index)` for each edge of the clipped path. Raises: `ValueError` - The `lowerleft` corner is not below and/or not to the left of the `upperright` corner.

### clipDMS(deg, limit) |
Clip a lat- or longitude to the given range. Parameters: `deg` - Unclipped lat- or longitude (`degrees`). `limit` - Valid `-limit..+limit` range (`degrees`). Returns: Clipped value (`degrees`). Raises: `RangeError` - If `abs(deg)` beyond `limit` and rangerrors set to `True`.

### clipSH(points, corners, inull=False, closed=False) |
Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm. Parameters: `points` - The polygon points (`LatLon`[]). `corners` - Three or more points defining a convex clip region (`LatLon`[]) or two points to specify a rectangular clip box. `inull` - Optionally, include null edges (`bool`). `closed` - Close the clipped points (`bool`). Returns: Yield the clipped points (`LatLon`[]). Raises: `ValueError` - Insufficient number of `points` or the `corners` specify a polar, zero-area, non-convex or otherwise invalid clip region.

### clipSH3(points, corners, inull=False, closed=False) |
Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm. Parameters: `points` - The polygon points (`LatLon`[]). `corners` - Three or more points defining a convex clip region (`LatLon`[]) or two points to specify a rectangular clip box. `inull` - Optionally, include null edges (`bool`). `closed` - Close the clipped points (`bool`). Returns: Yield a ClipSH3Tuple`(start, end, original)` for each edge of the clipped polygon. Raises: `ValueError` - Insufficient number of `points` or the `corners` specify a polar, zero-area, non-convex or otherwise invalid clip region.

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

### compassAngle(lat1, lon1, lat2, lon2, adjust=True, wrap=False) |
Return the angle from North for the direction vector (lon2 - lon1, lat2 - lat1) between two points. Suitable only for short, non-near-polar vectors up to a few hundred Km or Miles. Use function bearing for longer vectors. Parameters: `lat1` - From latitude (`degrees`). `lon1` - From longitude (`degrees`). `lat2` - To latitude (`degrees`). `lon2` - To longitude (`degrees`). `adjust` - Adjust the longitudinal delta by the cosine of the mean latitude (`bool`). `wrap` - Wrap and unroll180 longitudes (`bool`). Returns: Compass angle from North (`degrees360`). Note: Courtesy Martin Schultz. See Also: Local, flat earth approximation.

### compassDMS(bearing, form=`'``d``'`, prec=None, sep=`'````'`) |
Convert bearing to a string suffixed with compass point. Parameters: `bearing` - Bearing from North (compass `degrees360`). `form` - Optional `bearing` format (`str` or F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC, F_RAD, F_D_, F_DM_, F_DMS_, F_DEG_, F_MIN_, F_SEC_, F_RAD_, F_D__, F_DM__, F_DMS__, F_DEG__, F_MIN__, F_SEC__ or F_RAD__). `prec` - Optional number of decimal digits (0..9 or `None` for default). Trailing zero decimals are stripped for `prec` values of 1 and above, but kept for negative `prec`. `sep` - Optional separator (`str`). Returns: Compass degrees and point in the specified form (`str`).

### compassPoint(bearing, prec=3) |
Convert bearing to a compass point. Parameters: `bearing` - Bearing from North (compass `degrees360`). `prec` - Optional precision (1 for cardinal or basic winds, 2 for intercardinal or ordinal or principal winds, 3 for secondary-intercardinal or half-winds or 4 for quarter-winds). Returns: Compass point (1-, 2-, 3- or 4-letter `str`). Raises: `ValueError` - Invalid `prec`. See Also: Dms.compassPoint and Compass rose. Example:
    >>> p = compassPoint(24, 1)  # 'N'
    >>> p = compassPoint(24, 2)  # 'NE'
    >>> p = compassPoint(24, 3)  # 'NNE'
    >>> p = compassPoint(24)     # 'NNE'
    >>> p = compassPoint(11, 4)  # 'NbE'
    >>> p = compassPoint(30, 4)  # 'NEbN'
    >>> p = compassPoint(11.249)  # 'N'
    >>> p = compassPoint(11.25)   # 'NNE'
    >>> p = compassPoint(-11.25)  # 'N'
    >>> p = compassPoint(348.749) # 'NNW'

### date2epoch(year, month, day) |
Return the reference frame `epoch` for a calendar day. Parameters: `year` - Year of the date (`scalar`). `month` - Month in the `year` (`scalar`, 1..12). `day` - Day in the `month` (`scalar`, 1..31). Returns: Epoch, the fractional year (`float`). Raises: `TRFError` - Invalid `year`, `month` or `day`. Note: Any `year` is considered a leap year, i.e. having 29 days in February.

### decodeEPSG2(arg) |
DEPRECATED, use function epsg.decode2. Returns: 2-Tuple `(zone, hemipole)`

### degDMS(deg, prec=6, s_D=`'``°``'`, s_M=`'``′``'`, s_S=`'``″``'`, neg=`'``-``'`, pos=`'````'`) |
Convert degrees to a string in degrees, minutes or seconds. Parameters: `deg` - Value in degrees (`scalar`). `prec` - Optional number of decimal digits (0..9 or `None` for default). Trailing zero decimals are stripped for `prec` values of 1 and above, but kept for negative `prec`. `s_D` - Symbol for degrees (`str`). `s_M` - Symbol for minutes (`str`) or `""`. `s_S` - Symbol for seconds (`str`) or `""`. `neg` - Optional sign for negative ('-'). `pos` - Optional sign for positive (''). Returns: Either degrees, minutes or seconds (`str`).

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

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

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

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

### egmGeoidHeights(GeoidHeights_dat) |
Generate geoid egm*.pgm height tests from GeoidHeights.dat Test data for Geoids. Parameters: `GeoidHeights_dat` - The un-gz-ed `GeoidHeights.dat` file (`str` or `file` handle). Returns: For each test, yield a GeoidHeight5Tuple`(lat, lon, egm84, egm96, egm2008)`. Raises: `GeoidError` - Invalid `GeoidHeights_dat`. Note: Function egmGeoidHeights is used to test the geoids GeoidKarney and GeoidPGM, see PyGeodesy module `test/testGeoids.py`.

### elevation2(lat, lon, timeout=2.0) |
Get the geoid elevation at an `NAD83` to `NAVD88` location. Parameters: `lat` - Latitude (`degrees`). `lon` - Longitude (`degrees`). `timeout` - Optional, query timeout (seconds). Returns: An Elevation2Tuple`(elevation, data_source)` or (`None, error`) in case of errors. Note: The returned `elevation` is `None` if `lat` or `lon` is invalid or outside the `Conterminous US (CONUS)`, if conversion failed or if the query timed out. The `error` is the `HTTP-, IO-, SSL-, Type-, URL-` or `ValueError` as a string (`str`). See Also: USGS National Map, the FAQ, geoid.py, module geoids, classes GeoidG2012B, GeoidKarney and GeoidPGM.

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

### encodeEPSG(zone, hemipole=`'````'`, band=`'````'`) |
DEPRECATED, use function epsg.encode. Returns: `EPSG` code (`int`).

### equirectangular(lat1, lon1, lat2, lon2, radius=6371008.77141, **options) |
Compute the distance between two points using the Equirectangular Approximation / Projection. Parameters: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `radius` - Optional, mean earth radius (`meter`). `options` - Optional keyword arguments for function equirectangular_. Returns: Distance (`meter`, same units as `radius`). See Also: Function equirectangular_ for more details, the available `options`, errors, restrictions and other, approximate or accurate distance functions.

### equirectangular3(lat1, lon1, lat2, lon2, **options) |
DEPRECATED, use function `equirectangular_`. Returns: 3-Tuple `(distance2, delta_lat, delta_lon)`.

### equirectangular_(lat1, lon1, lat2, lon2, adjust=True, limit=45, wrap=False) |
Compute the distance between two points using the Equirectangular Approximation / Projection. This approximation is valid for short distance of several hundred Km or Miles, see the `limit` keyword argument and the LimitError. Parameters: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `limit` - Optional limit for lat- and longitudinal deltas (`degrees`) or `None` or `0` for unlimited. `wrap` - Wrap and unroll180 longitudes (`bool`). Returns: A Distance4Tuple`(distance2, delta_lat, delta_lon, unroll_lon2)`. Raises: `LimitError` - If the lat- and/or longitudinal delta exceeds the `-limit..+limit` range and limiterrors set to `True`. See Also: Local, flat earth approximation, functions equirectangular, euclidean, haversine and vincentys and methods Ellipsoid.distance2, `LatLon.distanceTo*` and `LatLon.equirectangularTo`.

### euclidean(lat1, lon1, lat2, lon2, radius=6371008.77141, adjust=True, wrap=False) |
Approximate the `Euclidian` distance between two (spherical) points. Parameters: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `radius` - Optional, mean earth radius (`meter`). `adjust` - Adjust the longitudinal delta by the cosine of the mean latitude (`bool`). `wrap` - Wrap and unroll180 longitudes (`bool`). Returns: Distance (`meter`, same units as `radius`). See Also: Distance between two (spherical) points, functions equirectangular, haversine and vincentys and methods Ellipsoid.distance2, `LatLon.distanceTo*` and `LatLon.equirectangularTo`.

### euclidean_(a2, a1, b21, adjust=True) |
Approximate the angular `Euclidean` distance between two (spherical) points. Parameters: `a2` - End latitude (`radians`). `a1` - Start latitude (`radians`). `b21` - Longitudinal delta, end-start (`radians`). `adjust` - Adjust the longitudinal delta by the cosine of the mean latitude (`bool`). Returns: Angular distance (`radians`). See Also: Functions euclidean, equirectangular_, haversine_ and vincentys_.

### fStr(floats, prec=6, sep=`'``,` `'`, fmt=`'``%.*f``'`, ints=False) |
Convert floats to string, optionally with trailing zero decimals stripped. Parameters: `floats` - List, sequence, tuple, etc. (`scalar`s). `prec` - Optional precision, number of decimal digits (0..9). Trailing zero decimals are stripped for `prec` values of 1 and above, but kept for negative `prec` values. `sep` - Optional, separator to join (string). `fmt` - Optional, float format (string). `ints` - Optionally, remove decimal dot (`bool`). Returns: The floats as 'f, f, ... f' (string).

### fStrzs(fstr) |
Strip trailing zero decimals from a float string. Parameters: `fstr` - Float (string). Returns: Float (string).

### false2f(value, name=`'``value``'`, false=True, Error=<type 'exceptions.ValueError'>) |
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`). `Error` - Exception to raise (`ValueError`). Returns: The value (`float`). Raises: `Error` - Invalid or negative `value`.

### favg(v1, v2, f=0.5) |
Return the weighted average of two values. Parameters: `v1` - One value (`scalar`). `v2` - Other value (`scalar`). `f` - Optional fraction (`float`). Returns: v1 + f * (v2 - v1) (`float`).

### fdot(a, *b) |
Return the precision dot product sum(a[i] * b[i] for i=0..len(a)). Parameters: `a` - List, sequence, tuple, etc. (`scalar`s). `b` - All positional arguments (`scalar`s). Returns: Dot product (`float`). Raises: `ValueError` - Unequal `len(a)` and `len(b)`. See Also: Class Fdot.

### fdot3(a, b, c, start=0) |
Return the precision dot product start + sum(a[i] * b[i] * c[i] for i=0..len(a)). Parameters: `a` - List, sequence, tuple, etc. (`scalar`[]). `b` - List, sequence, tuple, etc. (`scalar`[]). `c` - List, sequence, tuple, etc. (`scalar`[]). `start` - Optional bias (`scalar`). Returns: Dot product (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `ValueError` - Unequal `len(a)`, `len(b)` and/or `len(c)`.

### fhorner(x, *cs) |
Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)) using the Horner form. Parameters: `x` - Polynomial argument (`scalar`). `cs` - Polynomial coeffients (`scalar`[]). Returns: Horner value (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - Non-scalar `x`. `ValueError` - No `cs` coefficients or `x` is not finite. See Also: Function fpolynomial and class Fhorner.

### fidw(xs, ds, beta=2) |
Interpolate using using Inverse Distance Weighting (IDW). Parameters: `xs` - Known values (`scalar`[]). `ds` - Non-negative distances (`scalar`[]). `beta` - Inverse distance power (`int`, 0, 1, 2, or 3). Returns: Interpolated value `x` (`float`). Raises: `ValueError` - Invalid `beta`, negative `ds` value, weighted `ds` below EPS or unequal `len(ds)` and `len(xs)`. Note: Using `beta=0` returns the mean of `xs`.

### fmean(xs) |
Compute the accurate mean sum(xs[i] for i=0..len(xs)) / len(xs). Parameters: `xs` - Values (`scalar`s). Returns: Mean value (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `ValueError` - No `xs` values.

### fpolynomial(x, *cs) |
Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)). Parameters: `x` - Polynomial argument (`scalar`). `cs` - Polynomial coeffients (`scalar`[]). Returns: Polynomial value (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - Non-scalar `x`. `ValueError` - No `cs` coefficients or `x` is not finite. See Also: Function fhorner and class Fpolynomial.

### fpowers(x, n, alts=0) |
Return a series of powers [x**i for i=1..n]. Parameters: `x` - Value (`scalar`). `n` - Highest exponent (`int`). `alts` - Only alternating powers, starting with this exponent (`int`). Returns: Powers of `x` (`float`[]). Raises: `TypeError` - Non-scalar `x` or `n` not `int`. `ValueError` - Non-finite `x` or non-positive `n`.

### fprod(iterable, start=1.0) |
Iterable product, like `math.prod` or `numpy.prod`. Parameters: `iterable` - Values to be multiplied (`scalar`[]). `start` - Initial product, also the value returned for an empty iterable (`scalar`). Returns: The product (`float`). See Also: NumPy.prod.

### fractional(points, fi, LatLon=None) |
Return the point at a given fractional index. Parameters: `points` - The points (`LatLon`[], `Numpy2LatLon`[], `Tuple2LatLon`[] or `other`[]). `fi` - The fractional index (`float` or `int`). `LatLon` - Optional (sub-)class to return the intermediate point (`LatLon`) or `None`. Returns: A `LatLon` or a LatLon2Tuple`(lat, lon)` if `LatLon` is `None` with `points`[`fi`] if fractional index `fi` is `int`, otherwise the intermediate point between `points`[`int(fi)`] and `points`[`int(fi)+1`] for `float` fractional index `fi`. Raises: `IndexError` - Fractional index `fi` invalid or `points` not subscriptable.

### frange(start, number, step=1) |
Generate a range of `float`s. Parameters: `start` - First value (`float`). `number` - The number of `float`s to generate (`int`). `step` - Increment value (`float`). Returns: A generator (`float`s). See Also: NumPy.prod.

### frechet_(points1, points2, distance=None, units=`'````'`) |
Compute the discrete Fréchet distance between two paths given as sets of points. Parameters: `points1` - First set of points (`LatLon`[], `Numpy2LatLon`[], `Tuple2LatLon`[] or `other`[]). `points2` - Second set of points (`LatLon`[], `Numpy2LatLon`[], `Tuple2LatLon`[] or `other`[]). `distance` - Callable returning the distance between a `points1` and a `points2` point (signature `(point1, point2)`). `units` - Optional, name of the distance units (`str`). Returns: A Frechet6Tuple`(fd, fi1, fi2, r, n, units)` where `fi1` and `fi2` are type `int` indices into `points1` respectively `points2`. Raises: `FrechetError` - Insufficient number of `points1` or `points2`. `RecursionError` - Recursion depth exceeded, see sys.getrecursionlimit(). `TypeError` - If `distance` is not a callable. Note: Keyword `fraction`, intermediate `points1` and `points2` and fractional indices are not supported in this frechet_ function.

### freduce(function, sequence, initial=...) |
Apply a function of two arguments cumulatively to the items of a sequence, from left to right, so as to reduce the sequence to a single value. For example, reduce(lambda x, y: x+y, [1, 2, 3, 4, 5]) calculates ((((1+2)+3)+4)+5). If initial is present, it is placed before the items of the sequence in the calculation, and serves as a default when the sequence is empty. Returns: value

### fsum(iterable) |
Return an accurate floating point sum of values in the iterable. Assumes IEEE-754 floating point arithmetic.

### fsum_(*xs) |
Precision summation of the positional argument vulues. Parameters: `xs` - Values to be added (`scalar`[]). Returns: Accurate fsum (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `TypeError` - Non-scalar `xs` value. `ValueError` - Invalid or non-finite `xs` value.

### ft2m(feet, usurvey=False) |
Convert International or US Survey feet to meter. Parameters: `feet` - Value in feet (`scalar`). `usurvery` - Convert US Survey feet (`bool`), International feet otherwise. Returns: Value in `meter` (`float`).

### geoidHeight2(lat, lon, model=0, timeout=2.0) |
Get the `NAVD88` geoid height at an `NAD83` location. Parameters: `lat` - Latitude (`degrees`). `lon` - Longitude (`degrees`). `model` - Optional, geoid model ID (`int`). `timeout` - Optional, query timeout (seconds). Returns: An GeoidHeight2Tuple`(height, model_name)` or `(None, error`) in case of errors. Note: The returned `height` is `None` if `lat` or `lon` is invalid or outside the `Conterminous US (CONUS)`, if the `model` was invalid, if conversion failed or if the query timed out. The `error` is the `HTTP-, IO-, SSL-, Type-, URL-` or `ValueError` as a string (`str`). See Also: NOAA National Geodetic Survey, Geoid, USGS10mElev.py, module geoids, classes GeoidG2012B, GeoidKarney and GeoidPGM.

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

### hausdorff_(model, target, both=False, early=True, seed=None, units=`'````'`, distance=None, point=<function _point at 0x10970b050>) |
Compute the `directed` or `symmetric` Hausdorff distance between 2 sets of points with or without early breaking and random sampling. Parameters: `model` - First set of points (`LatLon`[], `Numpy2LatLon`[], `Tuple2LatLon`[] or `other`[]). `target` - Second set of points (`LatLon`[], `Numpy2LatLon`[], `Tuple2LatLon`[] or `other`[]). `both` - Return the `directed` (forward only) or the `symmetric` (combined forward and reverse) `Hausdorff` distance (`bool`). `early` - Enable or disable early breaking (`bool`). `seed` - Random sampling seed (`any`) or `None`, `0` or `False` for no random sampling. `units` - Optional, name of the distance units (`str`). `distance` - Callable returning the distance between a `model` and `target` point (signature `(point1, point2)`). `point` - Callable returning the `model` or `target` point suitable for `distance` (signature `(point)`). Returns: A Hausdorff6Tuple`(hd, i, j, mn, md, units)`. Raises: `HausdorffError` - Insufficient number of `model` or `target` points. `TypeError` - If `distance` or `point` is not callable.

### haversine(lat1, lon1, lat2, lon2, radius=6371008.77141, wrap=False) |
Compute the distance between two (spherical) points using the Haversine formula. Parameters: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `radius` - Optional, mean earth radius (`meter`). `wrap` - Wrap and unroll180 longitudes (`bool`). Returns: Distance (`meter`, same units as `radius`). See Also: Distance between two (spherical) points, functions equirectangular, euclidean and vincentys and methods Ellipsoid.distance2, `LatLon.distanceTo*` and `LatLon.equirectangularTo`. Note: See note under vincentys_.

### haversine_(a2, a1, b21) |
Compute the angular distance between two (spherical) points using the Haversine formula. Parameters: `a2` - End latitude (`radians`). `a1` - Start latitude (`radians`). `b21` - Longitudinal delta, end-start (`radians`). Returns: Angular distance (`radians`). See Also: Functions haversine, equirectangular_, euclidean_ and vincentys_. Note: See note under vincentys_.

### heightOf(angle, distance, radius=6371008.77141) |
Determine the height above the (spherical) earth after traveling along a straight line at a given tilt. Parameters: `angle` - Tilt angle above horizontal (`degrees`). `distance` - Distance along the line (`meter` or same units as `radius`). `radius` - Optional mean earth radius (`meter`). Returns: Height (`meter`, same units as `distance` and `radius`). Raises: `ValueError` - Invalid `angle`, `distance` or `radius`. See Also: MultiDop geog_lib.GeogBeamHt (Shapiro et al. 2009, JTECH and Potvin et al. 2012, JTECH).

### horizon(height, radius=6371008.77141, refraction=False) |
Determine the distance to the horizon from a given altitude above the (spherical) earth. Parameters: `height` - Altitude (`meter` or same units as `radius`). `radius` - Optional mean earth radius (`meter`). `refraction` - Consider atmospheric refraction (`bool`). Returns: Distance (`meter`, same units as `height` and `radius`). Raises: `ValueError` - Invalid `height` or `radius`. See Also: Distance to horizon.

### hypot1(x) |
Compute the norm sqrt(1 + x**2). Parameters: `x` - Argument (`scalar`). Returns: Norm (`float`).

### hypot_(*xs) |
Compute the norm sqrt(sum(xs[i]**2)) for i=0..len(xs). Parameters: `xs` - X arguments, positional (`scalar`[]). Returns: Norm (`float`). Raises: `OverflowError` - Partial `2sum` overflow. `ValueError` - Invalid or no `xs` value. See Also: Similar to Python 3.8+ math.hypot, but handling of exceptions, `nan` and `infinite` values is different. Note: The Python 3.8+ math.dist Euclidian distance between 2 n-dimensional points p1 and p2 can be computed as hypot_(*((c1 - c2) for c1, c2 in zip(p1, p2))), provided p1 and p2 have the same, non-zero length n.

### inStr(inst, *args, **kwds) |
Return the string representation of an instance. Parameters: `inst` - The instance (any `type`). `args` - Optional positional arguments. `kwds` - Optional keyword arguments. Returns: The `inst`'s representation (`str`).

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

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

### isantipode(lat1, lon1, lat2, lon2, eps=2.22044604925e-16) |
Check whether two points are antipodal, on diametrically opposite sides of the earth. Parameters: `lat1` - Latitude of one point (`degrees`). `lon1` - Longitude of one point (`degrees`). `lat2` - Latitude of the other point (`degrees`). `lon2` - Longitude of the other point (`degrees`). `eps` - Tolerance for near-equality (`degrees`). Returns: `True` if points are antipodal within the `eps` tolerance, `False` otherwise. See Also: Geosphere.

### isclockwise(points, adjust=False, wrap=True) |
Determine the direction of a path or polygon. Parameters: `points` - The path or polygon points (`LatLon`[]). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: `True` if `points` are clockwise, `False` otherwise. Raises: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points` or the `points` enclose a pole or zero area. Example:
    >>> f = LatLon(45,1), LatLon(45,2), LatLon(46,2), LatLon(46,1)
    >>> isclockwise(f)  # False
    >>> isclockwise(reversed(f))  # True

### isconvex(points, adjust=False, wrap=True) |
Determine whether a polygon is convex. Parameters: `points` - The polygon points (`LatLon`[]). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: `True` if `points` are convex, `False` otherwise. Raises: `CrossError` - Some `points` are colinear. `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. Example:
    >>> t = LatLon(45,1), LatLon(46,1), LatLon(46,2)
    >>> isconvex(t)  # True
    >>> f = LatLon(45,1), LatLon(46,2), LatLon(45,2), LatLon(46,1)
    >>> isconvex(f)  # False

### isconvex_(points, adjust=False, wrap=True) |
Determine whether a polygon is convex and clockwise. Parameters: `points` - The polygon points (`LatLon`[]). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: `+1` if `points` are convex clockwise, `-1` for convex counter-clockwise `points`, `0` otherwise. Raises: `CrossError` - Some `points` are colinear. `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. Example:
    >>> t = LatLon(45,1), LatLon(46,1), LatLon(46,2)
    >>> isconvex_(t)  # +1
    >>> f = LatLon(45,1), LatLon(46,2), LatLon(45,2), LatLon(46,1)
    >>> isconvex_(f)  # 0

### isenclosedBy(point, points, wrap=False) |
Determine whether a point is enclosed by a polygon. Parameters: `point` - The point (`LatLon` or 2-tuple `(lat, lon)`). `points` - The polygon points (`LatLon`[]). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: `True` if `point` is inside the polygon, `False` otherwise. Raises: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points` or invalid `point`. See Also: sphericalNvector.LatLon.isEnclosedBy, sphericalTrigonometry.LatLon.isEnclosedBy and MultiDop GeogContainPt (Shapiro et al. 2009, JTECH and Potvin et al. 2012, JTECH).

### isfinite(obj) |
Check for `Inf` and `NaN` values. Parameters: `obj` - Value (`scalar`). Returns: `False` if `obj` is `INF` or `NAN`, `True` otherwise. Raises: `TypeError` - Non-scalar `obj`.

### isint(obj, both=False) |
Check for integer type or integer value. Parameters: `obj` - The object (any `type`). `both` - Optionally, check both type and value (`bool`). Returns: `True` if `obj` is `int`, `False` otherwise.

### isneg0(obj) |
Check for NEG0, negative 0.0. Parameters: `obj` - Value (`scalar`). Returns: `True` if `obj` is `NEG0` or -0.0, `False` otherwise.

### ispolar(points, wrap=False) |
Check whether a polygon encloses a pole. Parameters: `points` - The polygon points (`LatLon`[]). `wrap` - Wrap and unroll longitudes (`bool`). Returns: `True` if the polygon encloses a pole, `False` otherwise. Raises: `ValueError` - Insufficient number of `points`. `TypeError` - Some `points` are not `LatLon` or don't have `bearingTo2`, `initialBearingTo` and `finalBearingTo` methods.

### isscalar(obj) |
Check for scalar types. Parameters: `obj` - The object (any `type`). Returns: `True` if `obj` is `scalar`, `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`.

### issubclassof(sub, sup) |
Check whether a class is a subclass of a super class. Parameters: `sub` - The sub class (`class`). `sup` - The super class (`class`). Returns: `True` if `sub` is a subclass of `sup`.

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

### latDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`) |
Convert latitude to a string, optionally suffixed with N or S. Parameters: `deg` - Latitude to be formatted (`degrees`). `form` - Optional `deg` format (`str` or F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC, F_RAD, F_D_, F_DM_, F_DMS_, F_DEG_, F_MIN_, F_SEC_, F_RAD_, F_D__, F_DM__, F_DMS__, F_DEG__, F_MIN__, F_SEC__ or F_RAD__). `prec` - Optional number of decimal digits (0..9 or `None` for default). Trailing zero decimals are stripped for `prec` values of 1 and above, but kept for negative `prec`. `sep` - Optional separator (`str`). Returns: Degrees in the specified form (`str`). JS name: toLat.

### len2(seq) |
Make built-in function `len` work for generators, iterators, etc. since those can only be started exactly once. Parameters: `seq` - Generator, iterator, list, range, tuple, etc. Returns: 2-Tuple (number, ...) of items (`int`, `list` or `range` or `tuple`).

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

### lonDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`) |
Convert longitude to a string, optionally suffixed with E or W. Parameters: `deg` - Longitude to be formatted (`degrees`). `form` - Optional `deg` format (`str` or F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC, F_RAD, F_D_, F_DM_, F_DMS_, F_DEG_, F_MIN_, F_SEC_, F_RAD_, F_D__, F_DM__, F_DMS__, F_DEG__, F_MIN__, F_SEC__ or F_RAD__). `prec` - Optional number of decimal digits (0..9 or `None` for default). Trailing zero decimals are stripped for `prec` values of 1 and above, but kept for negative `prec`. `sep` - Optional separator (`str`). Returns: Degrees in the specified form (`str`). JS name: toLon.

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

### 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, usurvey=False) |
Convert meter to International or US Survey feet (`ft`). Parameters: `meter` - Value in meter (`scalar`). `usurvery` - Convert to US Survey feet (`bool`), International feet otherwise. Returns: Value in `feet` (`float`).

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

### map1(func, *xs) |
Apply each argument to a single-argument function and return a tuple of results. Parameters: `func` - Function to apply (`callable`). `xs` - Arguments to apply (`any positional`). Returns: Function results (`tuple`).

### map2(func, *xs) |
Apply arguments to a function and return a tuple of results. Unlike Python 2's built-in `map`, Python 3+ `map` returns a `map` object, an iterator-like object which generates the results only once. Converting the `map` object to a tuple maintains Python 2 behavior. Parameters: `func` - Function to apply (`callable`). `xs` - Arguments to apply (`list, tuple, ...`). Returns: Function results (`tuple`).

### nameof(inst) |
Get the name of an instance. Parameters: `inst` - The object (any `type`). Returns: The instance' name (`str`) or `""`.

### nearestOn3(point, points, closed=False, wrap=False, **options) |
DEPRECATED, use function nearestOn5. Returns: 3-Tuple `(lat, lon, distance)`

### nearestOn4(point, points, closed=False, wrap=False, **options) |
DEPRECATED, use function nearestOn5. Returns: 4-Tuple `(lat, lon, distance, angle)`

### nearestOn5(point, points, closed=False, wrap=False, LatLon=None, **options) |
Locate the point on a path or polygon closest to an other point. If the given point is within the extent of a polygon edge, the closest point is on that edge, otherwise the closest point is the nearest of that edge's end points. Distances are approximated by function equirectangular_, subject to the supplied `options`. Parameters: `point` - The other, reference point (`LatLon`). `points` - The path or polygon points (`LatLon`[]). `closed` - Optionally, close the path or polygon (`bool`). `wrap` - Wrap and unroll180 longitudes and longitudinal delta (`bool`) in function equirectangular_. `LatLon` - Optional (sub-)class to return the closest point (`LatLon`) or `None`. `options` - Other keyword arguments for function equirectangular_. Returns: A NearestOn3Tuple`(closest, distance, angle)` or a NearestOn5Tuple`(lat, lon, distance, angle, height)` if `LatLon` is `None`. Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. See Also: Function degrees2m to convert `degrees` to `meter`.

### normDMS(strDMS, norm=`'````'`) |
Normalize all degree ˚, minute ' and second " symbols in a string to the default symbols °, ′ and ″. Parameters: `strDMS` - DMS (`str`). `norm` - Optional replacement symbol, default symbol otherwise (`str`). Returns: Normalized DMS (`str`).

### parse3llh(strll, height=0, sep=`'``,``'`, clipLat=90, clipLon=180) |
Parse a string representing lat-, longitude and height point. The lat- and longitude value must be separated by a separator character. If height is present it must follow, separated by another separator. The lat- and longitude values may be swapped, provided at least one ends with the proper compass point. Parameters: `strll` - Latitude, longitude[, height] (`str`, ...). `height` - Optional, default height (`meter`). `sep` - Optional separator (`str`). `clipLat` - Keep latitude in `-clipLat..+clipLat` (`degrees`). `clipLon` - Keep longitude in `-clipLon..+clipLon` range (`degrees`). Returns: A LatLon3Tuple`(lat, lon, height)` in `degrees`, `degrees` and `float`. Raises: `RangeError` - Lat- or longitude value of `strll` outside valid range and rangerrors set to `True`. `ValueError` - Invalid `strll`. See Also: Functions parseDMS and parseDMS2 for more details on the forms and symbols accepted. Example:
    >>> parse3llh('000°00′05.31″W, 51° 28′ 40.12″ N')
    (51.4778°N, 000.0015°W, 0)

### parseDMS(strDMS, suffix=`'``NSEW``'`, sep=`'````'`, clip=0) |
Parse a string representing deg°min′sec″ to degrees. This is very flexible on formats, allowing signed decimal degrees, degrees and minutes or degrees minutes and seconds optionally suffixed by compass direction NSEW. A variety of symbols, separators and suffixes are accepted, for example 3° 37′ 09″W. Minutes and seconds may be omitted. Parameters: `strDMS` - Degrees in any of several forms (`str` or `degrees`). `suffix` - Optional, valid compass directions (NSEW). `sep` - Optional separator between deg°, min′ and sec″ (''). `clip` - Optionally, limit value to -clip..+clip (`degrees`). Returns: Degrees (`float`). Raises: `RangeError` - Value of `strDMS` outside the valid range and rangerrors set to `True`. `ValueError` - Invalid `strDMS`. See Also: Function parse3llh to parse a string with lat-, longitude and height values.

### parseDMS2(strLat, strLon, sep=`'````'`, clipLat=90, clipLon=180) |
Parse lat- and longitude representions. Parameters: `strLat` - Latitude in any of several forms (`str` or `degrees`). `strLon` - Longitude in any of several forms (`str` or `degrees`). `sep` - Optional separator between deg°, min′ and sec″ (''). `clipLat` - Keep latitude in `-clipLat..+clipLat` range (`degrees`). `clipLon` - Keep longitude in `-clipLon..+clipLon` range (`degrees`). Returns: A LatLon2Tuple`(lat, lon)` in `degrees`. Raises: `RangeError` - Value of `strLat` or `strLon` outside the valid range and rangerrors set to `True`. `ValueError` - Invalid `strLat` or `strLon`. See Also: Function parse3llh to parse a string with lat-, longitude and height values and function parseDMS to parse individual lat- or longitudes.

### parseETM5(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, name=`'````'`) |
Parse a string representing a UTM coordinate, consisting of `"zone[band] hemisphere easting northing"`. Parameters: `strUTM` - A UTM coordinate (`str`). `datum` - Optional datum to use (Datum). `Etm` - Optional (sub-)class to return the UTM coordinate (Etm) or `None`. `falsed` - Both easting and northing are falsed (`bool`). `name` - Optional `Etm` name (`str`). Returns: The UTM coordinate (`Etm`) or a UtmUps5Tuple`(zone, hemipole, easting, northing, band)` if `Etm` is `None`. The `hemipole` is the hemisphere `'N'|'S'`. Raises: `ETMError` - Invalid `strUTM`. Example:
    >>> u = parseETM5('31 N 448251 5411932')
    >>> u.toStr2()  # [Z:31, H:N, E:448251, N:5411932]
    >>> u = parseETM5('31 N 448251.8 5411932.7')
    >>> u.toStr()  # 31 N 448252 5411933

### parseMGRS(strMGRS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>, name=`'````'`) |
Parse a string representing a MGRS grid reference, consisting of zoneBand, grid, easting and northing. Parameters: `strMGRS` - MGRS grid reference (`str`). `datum` - Optional datum to use (Datum). `Mgrs` - Optional (sub-)class to return the MGRS grid reference (Mgrs) or `None`. `name` - Optional `Mgrs` name (`str`). Returns: The MGRS grid reference (Mgrs) or an Mgrs4Tuple`(zone, digraph, easting, northing)` if `Mgrs` is `None`. Raises: `MGRSError` - Invalid `strMGRS`. Example:
    >>> m = parseMGRS('31U DQ 48251 11932')
    >>> str(m)  # 31U DQ 48251 11932
    >>> m = parseMGRS('31UDQ4825111932')
    >>> repr(m)  # [Z:31U, G:DQ, E:48251, N:11932]

### parseOSGR(strOSGR, Osgr=<class 'pygeodesy.osgr.Osgr'>, name=`'````'`) |
Parse an OSGR coordinate string to an Osgr instance. Accepts standard OS Grid References like 'SU 387 148', with or without whitespace separators, from 2- up to 10-digit references (1 m × 1 m square), or fully numeric, comma-separated references in metres, for example '438700,114800'. Parameters: `strOSGR` - An OSGR coordinate (`str`). `Osgr` - Optional (sub-)class to return the OSGR coordinate (Osgr) or `None`. `name` - Optional `Osgr` name (`str`). Returns: The OSGR coordinate (`Osgr`) or an EasNor2Tuple`(easting, northing)` if `Osgr` is `None`. Raises: `OSGRError` - Invalid `strOSGR`. Example:
    >>> g = parseOSGR('TG 51409 13177')
    >>> str(g)  # TG 51409 13177
    >>> g = parseOSGR('TG5140913177')
    >>> str(g)  # TG 51409 13177
    >>> g = parseOSGR('TG51409 13177')
    >>> str(g)  # TG 51409 13177
    >>> g = parseOSGR('651409,313177')
    >>> str(g)  # TG 51409 13177
    >>> g.toStr(prec=0)  # 651409,313177

### parseUPS5(strUPS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Ups=<class 'pygeodesy.ups.Ups'>, falsed=True, name=`'````'`) |
Parse a string representing a UPS coordinate, consisting of `"[zone][band] pole easting northing"` where `zone` is pseudo zone `"00"|"0"|""` and `band` is `'A'|'B'|'Y'|'Z'|''`. Parameters: `strUPS` - A UPS coordinate (`str`). `datum` - Optional datum to use (Datum). `Ups` - Optional (sub-)class to return the UPS coordinate (Ups) or `None`. `falsed` - Both `easting` and `northing` are falsed (`bool`). `name` - Optional `Ups` name (`str`). Returns: The UPS coordinate (`Ups`) or a UtmUps5Tuple`(zone, hemipole, easting, northing, band)` if `Ups` is `None`. The `hemipole` is the `'N'|'S'` pole, the UPS projection top/center. Raises: `UPSError` - Invalid `strUPS`.

### parseUTM(strUTM, datum=_R_M, Utm=_R_M, name=`'````'`) |
DEPRECATED, use function parseUTM5. Returns: The UTM coordinate (Utm) or 4-tuple `(zone, hemisphere, easting, northing)` if `Utm` is `None`.

### parseUTM5(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, name=`'````'`) |
Parse a string representing a UTM coordinate, consisting of `"zone[band] hemisphere easting northing"`. Parameters: `strUTM` - A UTM coordinate (`str`). `datum` - Optional datum to use (Datum). `Utm` - Optional (sub-)class to return the UTM coordinate (Utm) or `None`. `falsed` - Both easting and northing are falsed (`bool`). `name` - Optional `Utm` name (`str`). Returns: The UTM coordinate (`Utm`) or a UtmUps5Tuple`(zone, hemipole, easting, northing, band)` if `Utm` is `None`. The `hemipole` is the hemisphere `'N'|'S'`. Raises: `UTMError` - Invalid `strUTM`. Example:
    >>> u = parseUTM5('31 N 448251 5411932')
    >>> u.toStr2()  # [Z:31, H:N, E:448251, N:5411932]
    >>> u = parseUTM5('31 N 448251.8 5411932.7')
    >>> u.toStr()  # 31 N 448252 5411933

### parseUTMUPS5(strUTMUPS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Utm=<class 'pygeodesy.utm.Utm'>, Ups=<class 'pygeodesy.ups.Ups'>, name=`'````'`) |
Parse a string representing a UTM or UPS coordinate, consisting of `"zone[band] hemisphere/pole easting northing"`. Parameters: `strUTMUPS` - A UTM or UPS coordinate (`str`). `datum` - Optional datum to use (Datum). `Utm` - Optional (sub-)class to return the UTM coordinate (Utm) or `None`. `Ups` - Optional (sub-)class to return the UPS coordinate (Ups) or `None`. `name` - Optional name (`str`). Returns: The UTM or UPS coordinate (`Utm` or `Ups`) or a UtmUps5Tuple`(zone, hemipole, easting, northing, band)` if `Utm` respectively `Ups` or both are `None`. The `hemipole` is `'N'|'S'`, the UTM hemisphere or UPS pole, the UPS projection top/center. Raises: `UTMUPSError` - Invalid `strUTMUPS`. See Also: Functions parseUTM5 and parseUPS5.

### parseWM(strWM, radius=6378137.0, Wm=<class 'pygeodesy.webmercator.Wm'>, name=`'````'`) |
Parse a string representing a WM coordinate, consisting of easting, northing and an optional radius. Parameters: `strWM` - A WM coordinate (`str`). `radius` - Optional earth radius (`meter`). `Wm` - Optional (sub-)class to return the WM coordinate (Wm) or `None`. `name` - Optional name (`str`). Returns: The WM coordinate (`Wm`) or an EasNorRadius3Tuple`(easting, northing, radius)` if `Wm` is `None`. Raises: `WebMercatorError` - Invalid `strWM`. Example:
    >>> u = parseWM('448251 5411932')
    >>> u.toStr2()  # [E:448251, N:5411932]

### perimeterOf(points, closed=False, adjust=True, radius=6371008.77141, wrap=True) |
Approximate the perimeter of a path or polygon. Parameters: `points` - The path or polygon points (`LatLon`[]). `closed` - Optionally, close the path or polygon (`bool`). `adjust` - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (`bool`). `radius` - Optional, mean earth radius (`meter`). `wrap` - Wrap lat-, wrap and unroll longitudes (`bool`). Returns: Approximate perimeter (`meter`, same units as `radius`). Raises: `TypeError` - Some `points` are not `LatLon`. `ValueError` - Insufficient number of `points`. Note: This perimeter is based on the equirectangular_ distance approximation and is ill-suited for regions exceeding several hundred Km or Miles or with near-polar latitudes. See Also: sphericalTrigonometry.perimeterOf and ellipsoidalKarney.perimeterOf.

### points2(points, closed=True, base=None, Error=<type 'exceptions.ValueError'>) |
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`. `Error` - Exception for raise (`ValueError`). Returns: 2-Tuple (n, points) with the number (`int`) of points and the points `list` or `tuple`. Raises: `TypeError` - Some `points` are not `LatLon`. `Error` - Insufficient number of `points`.

### precision(form, prec=None) |
Set the default precison for a given F_ form. Parameters: `form` - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD (`str`). `prec` - Optional number of decimal digits (0..9 or `None` for default). Trailing zero decimals are stripped for `prec` values of 1 and above, but kept for negative `prec`. Returns: Previous precision (`int`). Raises: `ValueError` - Invalid `form` or `prec` or beyond valid range.

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

### randomrangenerator(seed) |
Return a `seed`ed random range function generator. Parameters: `seed` - Initial, internal Random state (`hashable`). Returns: A generator of random range functions. Note: Random `seed` `None` seeds from the current time or from a platform-specific randomness source, if available. Example:
    >>> rrange = randomrangenerator('R')
    >>> for r in rrange(n):
    >>>    ...  # r is random in 0..n-1

### rangerrors(raiser=None) |
Gert/set raising of range errors. Parameters: `raiser` - Choose `True` to raise or `False` to ignore RangeError exceptions. Use `None` to leave the setting unchanged. Returns: Previous setting (`bool`). Note: Out-of-range lat- and longitude values are always clipped to the nearest range limit.

### scalar(value, low=2.22044604925e-16, high=1.0, name=`'``scalar``'`, Error=<type 'exceptions.ValueError'>) |
Validate a scalar. Parameters: `value` - The value (`scalar`). `low` - Optional lower bound (`scalar`). `high` - Optional upper bound (`scalar`). `name` - Optional name of value (`str`). `Error` - Exception to raise (`ValueError`). Returns: New value (`type` of `low`). Raises: `TypeError` - Non-scalar `value`. `ValueError` - Out-of-bounds `value`.

### simplify1(points, distance, radius=6371008.77141, indices=False, **options) |
Basic simplification of a path of `LatLon` points. Eliminates any points closer together than the given distance tolerance. Parameters: `points` - Path points (`LatLon`[]). `distance` - Tolerance (`meter`, same units as `radius`). `radius` - Optional, mean earth radius (`meter`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `distance` or `radius` too small.

### simplifyRDP(points, distance, radius=6371008.77141, shortest=False, indices=False, **options) |
Ramer-Douglas-Peucker (RDP) simplification of a path of `LatLon` points. Eliminates any points too close together or closer to an edge than the given distance tolerance. This `RDP` method exhaustively searches for the point with the largest distance, resulting in worst-case complexity O(n**2) where n is the number of points. Parameters: `points` - Path points (`LatLon`[]). `distance` - Tolerance (`meter`, same units as `radius`). `radius` - Optional, mean earth radius (`meter`). `shortest` - Optional, shortest or perpendicular distance (`bool`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `distance` or `radius` too small.

### simplifyRDPm(points, distance, radius=6371008.77141, shortest=False, indices=False, **options) |
Modified Ramer-Douglas-Peucker (RDPm) simplification of a path of `LatLon` points. Eliminates any points too close together or closer to an edge than the given distance tolerance. This `RDPm` method stops at the first point farther than the given distance tolerance, significantly reducing the run time (but producing results different from the original `RDP` method). Parameters: `points` - Path points (`LatLon`[]). `distance` - Tolerance (`meter`, same units as `radius`). `radius` - Optional, mean earth radius (`meter`). `shortest` - Optional, shortest or perpendicular distance (`bool`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `distance` or `radius` too small.

### simplifyRW(points, pipe, radius=6371008.77141, shortest=False, indices=False, **options) |
Reumann-Witkam (RW) simplification of a path of `LatLon` points. Eliminates any points too close together or within the given pipe tolerance along an edge. Parameters: `points` - Path points (`LatLon`[]). `pipe` - Half pipe width (`meter`, same units as `radius`). `radius` - Optional, mean earth radius (`meter`). `shortest` - Optional, shortest or perpendicular distance (`bool`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `pipe` or `radius` too small.

### simplifyVW(points, area, radius=6371008.77141, attr=None, indices=False, **options) |
Visvalingam-Whyatt (VW) simplification of a path of `LatLon` points. Eliminates any points too close together or with a triangular area not exceeding the given area tolerance (squared). This `VW` method exhaustively searches for the single point with the smallest triangular area, resulting in worst-case complexity O(n**2) where n is the number of points. Parameters: `points` - Path points (`LatLon`[]). `area` - Tolerance (`meter`, same units as `radius`). `radius` - Optional, mean earth radius (`meter`). `attr` - Optional, points attribute save area value (`str`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `AttributeError` - If an `attr` is specified for Numpy2 `points`. `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `area` or `radius` too small.

### simplifyVWm(points, area, radius=6371008.77141, attr=None, indices=False, **options) |
Modified Visvalingam-Whyatt (VWm) simplification of a path of `LatLon` points. Eliminates any points too close together or with a triangular area not exceeding the given area tolerance (squared). This `VWm` method removes all points with a triangular area below the tolerance in each iteration, significantly reducing the run time (but producing results different from the original `VW` method). Parameters: `points` - Path points (`LatLon`[]). `area` - Tolerance (`meter`, same units as `radius`). `radius` - Optional, mean earth radius (`meter`). `attr` - Optional attribute to save the area value (`str`). `indices` - Optionally return the simplified point indices instead of the simplified points (`bool`). `options` - Optional keyword arguments passed thru to function equirectangular_. Returns: Simplified points (`LatLon`[]). Raises: `AttributeError` - If an `attr` is specified for Numpy2 `points`. `LimitError` - Lat- and/or longitudinal delta exceeds the `limit`, see function equirectangular_. `ValueError` - Tolerance `area` or `radius` too small.

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

### sqrt3(x) |
Compute the square root cubed sqrt(x)**3 or sqrt(x**3). Parameters: `x` - Value (`scalar`). Returns: Cubed square root (`float`). Raises: `ValueError` - Negative `x`. See Also: Functions cbrt and cbrt2.

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

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

### toCss(latlon, cs0=None, height=None, Css=<class 'pygeodesy.css.Css'>, name=`'````'`) |
Convert an (ellipsoidal) geodetic point to a Cassini-Soldner location. Parameters: `latlon` - Ellipsoidal point (`LatLon`). `cs0` - Optional, the Cassini-Soldner projection to use (CassiniSoldner). `height` - Optional height for the point, overriding the default height (`meter`). `Css` - Optional (sub-)class to return the location (Css) or `None`. `name` - Optional `Css` name (`str`). Returns: The Cassini-Soldner location (`Css`) or an EasNor3Tuple`(easting, northing, height)` if `Css` is `None`. Raises: `CSSError` - Mismatch of this and the `latlon` ellipsoidal. `ImportError` - Package GeographicLib missing. `TypeError` - If `latlon` is not ellipsoidal.

### toDMS(deg, form=`'``dms``'`, prec=2, sep=`'````'`, ddd=2, neg=`'``-``'`, pos=`'````'`) |
Convert signed degrees to string, without suffix. Parameters: `deg` - Degrees to be formatted (`degrees`). `form` - Optional `deg` format (`str` or F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC, F_RAD without suffix, F_D_, F_DM_, F_DMS_, F_DEG_, F_MIN_, F_SEC_, F_RAD_, F_D__, F_DM__, F_DMS__, F_DEG__, F_MIN__, F_SEC__ or F_RAD__). `prec` - Optional number of decimal digits (0..9 or `None` for default). Trailing zero decimals are stripped for `prec` values of 1 and above, but kept for negative `prec`. `sep` - Optional separator (`str`). `ddd` - Optional number of digits for deg° (2 or 3). `neg` - Optional sign for negative degrees ('-'). `pos` - Optional sign for positive degrees (''). Returns: Degrees in the specified form (`str`).

### toEtm8(latlon, lon=None, datum=None, Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, name=`'````'`, zone=None, **cmoff) |
Convert a lat-/longitude point to an ETM coordinate. Parameters: `latlon` - Latitude (`degrees`) or an (ellipsoidal) geodetic `LatLon` point. `lon` - Optional longitude (`degrees`) or `None`. `datum` - Optional datum for this ETM coordinate, overriding `latlon`'s datum (`Datum`). `Etm` - Optional (sub-)class to return the ETM coordinate (Etm) or `None`. `falsed` - False both easting and northing (`bool`). `name` - Optional `Utm` name (`str`). `zone` - Optional UTM zone to enforce (`int` or `str`). `cmoff` - DEPRECATED, use `falsed`. Offset longitude from the zone's central meridian (`bool`). Returns: The ETM coordinate (`Etm`) or a UtmUps8Tuple`(zone, hemipole, easting, northing, band, datum, convergence, scale)` if `Etm` is `None` or not `falsed`. The `hemipole` is the `'N'|'S'` hemisphere. Raises: `EllipticError` - No convergence. `ETMError` - Invalid `zone`. `TypeError` - If `latlon` is not ellipsoidal. `RangeError` - If `lat` outside the valid UTM bands or if `lat` or `lon` outside the valid range and rangerrors set to `True`. `ValueError` - If `lon` value is missing or if `latlon` is invalid.

### toLcc(latlon, conic=Conic(name='WRF_Lb', lat0=40, lon0=-97, par1=33, par2=45, E0=0`...`, height=None, Lcc=<class 'pygeodesy.lcc.Lcc'>, name=`'````'`) |
Convert an (ellipsoidal) geodetic point to a Lambert location. Parameters: `latlon` - Ellipsoidal point (`LatLon`). `conic` - Optional Lambert projection to use (Conic). `height` - Optional height for the point, overriding the default height (`meter`). `Lcc` - Optional (sub-)class to return the Lambert location (Lcc). `name` - Optional `Lcc` name (`str`). Returns: The Lambert location (Lcc) or an EasNor3Tuple`(easting, northing, height)` if `Lcc` is `None`. Raises: `TypeError` - If `latlon` is not ellipsoidal.

### toMgrs(utm, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>, name=`'````'`) |
Convert a UTM coordinate to an MGRS grid reference. Parameters: `utm` - A UTM coordinate (Utm or Etm). `Mgrs` - Optional (sub-)class to return the MGRS grid reference (Mgrs) or `None`. `name` - Optional `Mgrs` name (`str`). Returns: The MGRS grid reference (Mgrs) or an Mgrs6Tuple`(zone, digraph, easting, northing, band, datum)` if Mgrs is `None`. Raises: `TypeError` - If `utm` is not Utm nor Etm. `MGRSError` - Invalid `utm`. Example:
    >>> u = Utm(31, 'N', 448251, 5411932)
    >>> m = u.toMgrs()  # 31U DQ 48251 11932

### toOsgr(latlon, lon=None, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran`...`, Osgr=<class 'pygeodesy.osgr.Osgr'>, name=`'````'`) |
Convert a lat-/longitude point to an OSGR coordinate. Parameters: `latlon` - Latitude (`degrees`) or an (ellipsoidal) geodetic `LatLon` point. `lon` - Optional longitude in degrees (scalar or `None`). `datum` - Optional datum to convert (`Datum`). `Osgr` - Optional (sub-)class to return the OSGR coordinate (Osgr) or `None`. `name` - Optional `Osgr` name (`str`). Returns: The OSGR coordinate (`Osgr`) or an EasNor2Tuple`(easting, northing)` if `Osgr` is `None`. Raises: `TypeError` - Non-ellipsoidal `latlon` or `datum` conversion failed. `OSGRError` - Invalid `latlon` or `lon`. Example:
    >>> p = LatLon(52.65798, 1.71605)
    >>> r = toOsgr(p)  # TG 51409 13177
    >>> # for conversion of (historical) OSGB36 lat-/longitude:
    >>> r = toOsgr(52.65757, 1.71791, datum=Datums.OSGB36)

### toUps8(latlon, lon=None, datum=None, Ups=<class 'pygeodesy.ups.Ups'>, pole=`'````'`, falsed=True, strict=True, name=`'````'`) |
Convert a lat-/longitude point to a UPS coordinate. Parameters: `latlon` - Latitude (`degrees`) or an (ellipsoidal) geodetic `LatLon` point. `lon` - Optional longitude (`degrees`) or `None` if `latlon` is a `LatLon`. `datum` - Optional datum for this UPS coordinate, overriding `latlon`'s datum (`Datum`). `Ups` - Optional (sub-)class to return the UPS coordinate (Ups) or `None`. `pole` - Optional top/center of (stereographic) projection (`str`, `'N[orth]'` or `'S[outh]'`). `falsed` - False both easting and northing (`bool`). `strict` - Restrict `lat` to UPS ranges (`bool`). `name` - Optional `Ups` name (`str`). Returns: The UPS coordinate (`Ups`) or a UtmUps8Tuple`(zone, hemipole, easting, northing, band, datum, convergence, scale)` if `Ups` is `None`. The `hemipole` is the `'N'|'S'` pole, the UPS projection top/center. Raises: `RangeError` - If `strict` and `lat` outside the valid UPS bands or if `lat` or `lon` outside the valid range and rangerrors set to `True`. `TypeError` - If `latlon` is not ellipsoidal. `ValueError` - If `lon` value is missing or if `latlon` is invalid. See Also: Karney's C++ class UPS.

### toUtm(latlon, lon=None, datum=None, Utm=_R_M, cmoff=True, name=`'````'`) |
DEPRECATED, use function toUtm8. Returns: The UTM coordinate (`Utm`) or a 6-tuple `(zone, easting, northing, band, convergence, scale)` if `Utm` is `None` or `cmoff` is `False`.

### toUtm8(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, name=`'````'`, zone=None, **cmoff) |
Convert a lat-/longitude point to a UTM coordinate. Parameters: `latlon` - Latitude (`degrees`) or an (ellipsoidal) geodetic `LatLon` point. `lon` - Optional longitude (`degrees`) or `None`. `datum` - Optional datum for this UTM coordinate, overriding `latlon`'s datum (`Datum`). `Utm` - Optional (sub-)class to return the UTM coordinate (Utm) or `None`. `falsed` - False both easting and northing (`bool`). `name` - Optional `Utm` name (`str`). `zone` - Optional UTM zone to enforce (`int` or `str`). `cmoff` - DEPRECATED, use `falsed`. Offset longitude from the zone's central meridian (`bool`). Returns: The UTM coordinate (`Utm`) or a UtmUps8Tuple`(zone, hemipole, easting, northing, band, datum, convergence, scale)` if `Utm` is `None` or not `falsed`. The `hemipole` is the `'N'|'S'` hemisphere. Raises: `TypeError` - If `latlon` is not ellipsoidal. `RangeError` - If `lat` outside the valid UTM bands or if `lat` or `lon` outside the valid range and rangerrors set to `True`. `UTMError` - Invalid `zone`. `ValueError` - If `lon` value is missing or if `latlon` is invalid. Note: Implements Karney’s method, using 8-th order Krüger series, giving results accurate to 5 nm (or better) for distances up to 3900 km from the central meridian. Example:
    >>> p = LatLon(48.8582, 2.2945)  # 31 N 448251.8 5411932.7
    >>> u = toUtm(p)  # 31 N 448252 5411933
    >>> p = LatLon(13.4125, 103.8667) # 48 N 377302.4 1483034.8
    >>> u = toUtm(p)  # 48 N 377302 1483035

### toUtmUps8(latlon, lon=None, datum=None, falsed=True, Utm=<class 'pygeodesy.utm.Utm'>, Ups=<class 'pygeodesy.ups.Ups'>, pole=`'````'`, name=`'````'`, **cmoff) |
Convert a lat-/longitude point to a UTM or UPS coordinate. Parameters: `latlon` - Latitude (`degrees`) or an (ellipsoidal) geodetic `LatLon` point. `lon` - Optional longitude (`degrees`) or `None`. `datum` - Optional datum to use this UTM coordinate, overriding `latlon`'s datum (`Datum`). `falsed` - False both easting and northing (`bool`). `Utm` - Optional (sub-)class to return the UTM coordinate (Utm) or `None`. `Ups` - Optional (sub-)class to return the UPS coordinate (Ups) or `None`. `pole` - Optional top/center of UPS (stereographic) projection (`str`, `'N[orth]'` or `'S[outh]'`). `name` - Optional name (`str`). `cmoff` - DEPRECATED, use `falsed`. Offset longitude from zone's central meridian, for UTM only (`bool`). Returns: The UTM or UPS coordinate (`Utm` respectively `Ups`) or a UtmUps8Tuple`(zone, hemipole, easting, northing, band, datum, convergence, scale)` if `Utm` respectively `Ups` is `None` or `cmoff` is `False`. Raises: `RangeError` - If `lat` outside the valid UTM or UPS bands or if `lat` or `lon` outside the valid range and rangerrors set to `True`. `TypeError` - If `latlon` is not ellipsoidal or `lon` value is missing. `UTMUPSError` - UTM or UPS validation failed. `ValueError` - Invalid `lat` or `lon`. See Also: Functions toUtm8 and toUps8.

### toWm(latlon, lon=None, radius=6378137.0, Wm=<class 'pygeodesy.webmercator.Wm'>, name=`'````'`) |
Convert a lat-/longitude point to a WM coordinate. Parameters: `latlon` - Latitude (`degrees`) or an (ellipsoidal or spherical) geodetic `LatLon` point. `lon` - Optional longitude (`degrees` or `None`). `radius` - Optional earth radius (`meter`). `Wm` - Optional (sub-)class to return the WM coordinate (Wm) or `None`. `name` - Optional name (`str`). Returns: The WM coordinate (`Wm`) or an EasNorRadius3Tuple`(easting, northing, radius)` if `Wm` is `None`. Raises: `ValueError` - If `lon` value is missing, if `latlon` is not scalar, if `latlon` is beyond the valid WM range and rangerrors is set to `True` or if `radius` is invalid. Example:
    >>> p = LatLon(48.8582, 2.2945)  # 448251.8 5411932.7
    >>> w = toWm(p)  # 448252 5411933
    >>> p = LatLon(13.4125, 103.8667)  # 377302.4 1483034.8
    >>> w = toWm(p)  # 377302 1483035

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

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

### upsZoneBand5(lat, lon, strict=True) |
Return the UTM/UPS zone number, (polar) Band letter, pole and clipped lat- and longitude for a given location. Parameters: `lat` - Latitude in degrees (`scalar` or `str`). `lon` - Longitude in degrees (`scalar` or `str`). `strict` - Restrict `lat` to UPS ranges (`bool`). Returns: A UtmUpsLatLon5Tuple`(zone, band, hemipole, lat, lon)` where `hemipole` is the `'N'|'S'` pole, the UPS projection top/center. Raises: `RangeError` - If `strict` and `lat` in the UTM and not the UPS range or if `lat` or `lon` outside the valid range and rangerrors set to `True`. `ValueError` - Invalid `lat` or `lon`.

### utmZoneBand2(lat, lon) |
DEPRECATED, use function utmZoneBand5. Returns: 2-Tuple `(zone, band)`.

### utmZoneBand5(lat, lon, cmoff=False) |
Return the UTM zone number, Band letter, hemisphere and (clipped) lat- and longitude for a given location. Parameters: `lat` - Latitude in degrees (`scalar` or `str`). `lon` - Longitude in degrees (`scalar` or `str`). `cmoff` - Offset longitude from the zone's central meridian (`bool`). Returns: A UtmUpsLatLon5Tuple`(zone, band, hemipole, lat, lon)` where `hemipole` is the `'N'|'S'` UTM hemisphere. Raises: `RangeError` - If `lat` outside the valid UTM bands or if `lat` or `lon` outside the valid range and rangerrors set to `True`. `ValueError` - Invalid `lat` or `lon`.

### utmupsValidate(coord, falsed=False, MGRS=False) |
Check a UTM or UPS coordinate. Parameters: `coord` - The UTM or UPS coordinate (Utm, Ups or `5+Tuple`). `falsed` - `5+Tuple` easting and northing are falsed (`bool`). `MGRS` - Increase easting and northing ranges (`bool`). Returns: `None` if validation passed. Raises: `UTMUPSError` - Validation failed. See Also: Function utmupsValidateOK.

### utmupsValidateOK(coord, falsed=False, ok=`'``OK``'`) |
Check a UTM or UPS coordinate. Parameters: `coord` - The UTM or UPS coordinate (Utm, Ups or `5+Tuple`). `falsed` - `5+Tuple` easting and northing are falsed (`bool`). `ok` - Result to return if validation passed (`ok`). Returns: `ok` if validation passed, the UTMUPSError otherwise. See Also: Function utmupsValidate.

### utmupsZoneBand5(lat, lon, cmoff=False) |
Return the UTM/UPS zone number, Band letter, hemisphere/pole and clipped lat- and longitude for a given location. Parameters: `lat` - Latitude in degrees (`scalar` or `str`). `lon` - Longitude in degrees (`scalar` or `str`). `cmoff` - Offset longitude from the zone's central meridian, for UTM only (`bool`). Returns: A UtmUpsLatLon5Tuple`(zone, band, hemipole, lat, lon)` where `hemipole` is `'N'|'S'`, the UTM hemisphere or UPS pole, the UPS projection top/center. Raises: `RangeError` - If `lat` outside the valid UTM or UPS bands or if `lat` or `lon` outside the valid range and rangerrors set to `True`. `ValueError` - Invalid `lat` or `lon`. See Also: Functions utmZoneBand5 and upsZoneBand5.

### vincentys(lat1, lon1, lat2, lon2, radius=6371008.77141, wrap=False) |
Compute the distance between two (spherical) points using Vincenty's spherical formula. Parameters: `lat1` - Start latitude (`degrees`). `lon1` - Start longitude (`degrees`). `lat2` - End latitude (`degrees`). `lon2` - End longitude (`degrees`). `radius` - Optional, mean earth radius (`meter`). `wrap` - Wrap and unroll180 longitudes (`bool`). Returns: Distance (`meter`, same units as `radius`). See Also: Functions equirectangular, euclidean and haversine and methods Ellipsoid.distance2, `LatLon.distanceTo*` and `LatLon.equirectangularTo`. Note: See note under vincentys_.

### vincentys_(a2, a1, b21) |
Compute the angular distance between two (spherical) points using Vincenty's spherical formula. Parameters: `a2` - End latitude (`radians`). `a1` - Start latitude (`radians`). `b21` - Longitudinal delta, end-start (`radians`). Returns: Angular distance (`radians`). See Also: Functions vincentys, equirectangular_, euclidean_ and haversine_. Note: Functions vincentys_ and haversine_ produce equivalent results, but vincentys_ is suitable for antipodal points and slightly more expensive than haversine_ (3 cos, 3 sin, 1 hypot, 1 atan2, 7 mul, 2 add versus 2 cos, 2 sin, 2 sqrt, 1 atan2, 5 mul, 1 add).

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

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

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

Variables Details

  ### pygeodesy_abspath Fully qualified `pygeodesy` directory name (`str`). Value:
      '..../PyGeodesy/pygeodesy'

  ### Conics Registered conics (`enum-like`). Value:
      Conics.Be08Lb: Conic(name='Be08Lb', lat0=50.797815, lon0=4.35921583, p
      ar1=49.833333, par2=51.166667, E0=649328, N0=665262, k0=1, SP=2, datum
      =(name='GRS80', ellipsoid=Ellipsoids.GRS80, transform=Transforms.WGS84
      ),
      Conics.Be72Lb: Conic(name='Be72Lb', lat0=90, lon0=4.3674867, par1=49.8
      333339, par2=51.1666672, E0=150000.013, N0=5400088.438, k0=1, SP=2, da
      tum=(name='NAD83', ellipsoid=Ellipsoids.GRS80, transform=Transforms.NA
      D83),
      ...

  ### Datums Registered datums (`enum-like`). Value:
      Datums.BD72: Datum(name='BD72', ellipsoid=Ellipsoids.Intl1924, transfo
      rm=Transforms.BD72),
      Datums.DHDN: Datum(name='DHDN', ellipsoid=Ellipsoids.Bessel1841, trans
      form=Transforms.DHDN),
      Datums.ED50: Datum(name='ED50', ellipsoid=Ellipsoids.Intl1924, transfo
      rm=Transforms.ED50),
      Datums.GDA2020: Datum(name='GDA2020', ellipsoid=Ellipsoids.GRS80, tran
      sform=Transforms.WGS84),
      ...

  ### Ellipsoids Registered ellipsoids (`enum-like`). Value:
      Ellipsoids.Airy1830: Ellipsoid(name='Airy1830', a=6377563.396, b=63562
      56.909, f_=299.3249646, f=0.003340851, e=0.081673374, e2=0.00667054, e
      22=0.006715335, n=0.00167322, R1=6370461.233666666, R2=6370459.6545894
      42, R3=6370453.309866445, Rr=6366914.608805893, Rs=6366901.239881964),
      Ellipsoids.AiryModified: Ellipsoid(name='AiryModified', a=6377340.189,
       b=6356034.448, f_=299.3249646, f=0.003340851, e=0.081673374, e2=0.006
      67054, e22=0.006715335, n=0.00167322, R1=6370238.275333334, R2=6370236
      .696361165, R3=6370230.351810658, Rr=6366691.774649803, Rs=6366678.406
      ...

  ### RefFrames Registered reference frames (`enum-like`). Value:
      RefFrames.ETRF2000: RefFrame(name='ETRF2000', epoch=2005.0, ellipsoid=
      Ellipsoid(name='GRS80'),
      RefFrames.GDA94: RefFrame(name='GDA94', epoch=1994.0, ellipsoid=Ellips
      oid(name='GRS80'),
      RefFrames.ITRF2000: RefFrame(name='ITRF2000', epoch=1997.0, ellipsoid=
      Ellipsoid(name='GRS80'),
      RefFrames.ITRF2005: RefFrame(name='ITRF2005', epoch=2000.0, ellipsoid=
      Ellipsoid(name='GRS80'),
      ...

  ### Transforms Registered transforms (`enum-like`). Value:
      Transforms.BD72: Transform(name='BD72', tx=106.86863, ty=-52.29778, tz
      =103.72389, rx=-0, ry=-0, rz=-0.00001, s=1.2727, s1=1, sx=-0.33657, sy
      =-0.45696, sz=-1.84218),
      Transforms.Bessel1841: Transform(name='Bessel1841', tx=-582, ty=-105,
      tz=-414, rx=-0.00001, ry=-0, rz=0.00001, s=-8.3, s1=0.99999, sx=-1.04,
       sy=-0.35, sz=3.08),
      Transforms.Clarke1866: Transform(name='Clarke1866', tx=8, ty=-160, tz=
      -176, rx=0, ry=0, rz=0, s=0, s1=1, sx=0, sy=0, sz=0),
      ...