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, exact, elliptic, iterative and approximate methods for geodetic (lat-/longitude), geocentric (ECEF cartesian) and certain triaxial ellipsoidal coordinates.

Transcoded in part from JavaScript originals by Chris Veness (C) 2005-2024 and from several C++ classes by Charles F. F. Karney (C) 2008-2024 and published under the same MIT License**.

There are four modules for ellipsoidal earth models, ellipsoidalExact, -Karney, -Vincenty and -Nvector and two for spherical ones, sphericalTrigonometry and -Nvector. Each module provides a geodetic LatLon and a geocentric Cartesian class with methods and functions to compute distance, surface area, perimeter, forward and reverse azimuth, initial and final bearing, intermediate and nearest points, intersections of geodesic, great circle and rhumb lines, circle intersections and secants, 3-point resections, triangulation, trilateration (by intersection, by overlap and in 3-D), 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 Karney's Python geographiclib and C++ GeographicLib.

Also included are modules for conversions to and from Cassini-Soldner, ECEF (Earth-Centered, Earth-Fixed cartesian), UTM (Universal Transverse Mercator and Exact), UPS (Universal Polar Stereographic) and Web Mercator (Pseudo-Mercator) coordinates, MGRS (Military Grid Reference System, UTM and UPS) 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 Albers equal-area projections, equidistant and other azimuthal projections, Lambert conformal conic projections and positions, functions to clip paths or polygons of LatLon points using the Cohen-Sutherland, Forster-Hormann-Popa, Greiner-Hormann, Liang-Barsky and 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 the Reumann-Witkam algorithms and modified versions of the former. Other classes provide boolean operations between (composite) polygons or interpolate the height of LatLon points and Geoid models, compute various Fréchet or Hausdorff distances.

Installation

To install PyGeodesy, type python[3] -m pip install pygeodesy or python[3] -m easy_install pygeodesy in a terminal or command window.

If the wheel pygeodesy-yy.m.d-py2.py3-none-any.whl is missing in PyPI Download files, download the file from GitHub/dist. Install that with python[3] -m pip install <path-to-downloaded-wheel> and verify with python[3] -m pygeodesy.

Alternatively, download pygeodesy-yy.m.d.tar.gz from PyPI or GitHub, unzip the downloaded file, cd to directory pygeodesy-yy.m.d and type python[3] setup.py install.

To run all PyGeodesy tests, type python[3] test/run.py or type python[3] test/unitTestSuite.py before or after installation.

Dependencies

Installation of Karney's Python package geographiclib is optional, but required to use modules ellipsoidalKarney and css, azimuthal classes EquidistantKarney and GnomonicKarney and the HeightIDWkarney interpolator.

Both numpy and scipy must be installed for most Geoid... and Height... interpolators, except GeoidKarney and the HeightIDW... ones.

Functions and LatLon methods circin6, circum3, circum4_, soddy4, trilaterate3d2 do and trilaterate5 and modules auxilats and rhumb may require numpy.

Modules ellipsoidalGeodSolve and geodsolve and azimuthal classes EquidistantGeodSolve and GnomonicGeodSolve depend on Karney's C++ utility GeodSolve to be executable and set with env variable PYGEODESY_GEODSOLVE or with property Ellipsoid.geodsolve.

Class Intersectool in module geodesici needs Karney's C++ utility IntersectTool to be executable and set with env variable PYGEODESY_INTERSECTTOOL.

To compare MGRS results from modules mgrs and testMgrs with Karney's C++ utility GeoConvert, the latter must be executable and set with env variable PYGEODESY_GEOCONVERT.

Module rhumb.solve needs Karney's C++ utility RhumbSolve to be executable and set with env variable PYGEODESY_RHUMBSOLVE or with property Ellipsoid.rhumbsolve.

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 ran with Python 3.13.1 (with geographiclib 2.0), Python 3.12.7 (with geographiclib 2.0, numpy 2.1.0, scipy 1.14.1, GeodSolve 2.3, IntersectTool 2.3 and RhumbSolve 2.3), Python 3.11.5 (with geographiclib 2.0, numpy 1.24.2 and scipy 1.10.1), Python 3.10.8 (with geographiclib 2.0, numpy 1.23.3, scipy 1.9.1, GeoConvert 2.3, GeodSolve 2.3) and Python 2.7.18 (with geographiclib 1.50, numpy 1.16.6, scipy 1.2.2, GeoConvert 2.3, GeodSolve 2.3, IntersectTool 2.3 and RhumbSolve 2.3), all in 64-bit on macOS 14.6.1 Sonoma.

All tests ran with and without lazy import for Python 3 and with command line option -W default and env variable PYGEODESY_WARNINGS=on for all Python versions. The results of those tests are included in the distribution files.

Test coverage has been measured with coverage 7.6.1 using Python 3.13.1, 3.12.7, 3.11.5 and 3.10.8. The complete coverage report in HTML and a PDF summary are included in the distribution files.

Python 3.13.1, 3.12.7, 3.11.5 and 3.10.8 run on Apple M1 Silicon (arm64), natively. Python 2.7.18 runs on Intel (x86_64) or Intel emulation ("arm64_x86_64", see function machine).

The tests also ran with Python 3.13.1 (and geographiclib 2.0) on Debian 12 in 64-bit only, with Python 3.12.5 (and geographiclib 2.0) on Windows 2019Server in 64-bit only and with Python 2.7.18 (and geographiclib 1.52) on Windows 10 in 64- and 32-bit.

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 3.13.0, 3.12.0-6, 3.11.2-4, 3.10.1-7, 3.9.6, 3.9.1, 3.8.7, 3.7.1, 2.7.15, PyPy 7.3.12 (Python 3.10.12), 7.3.1 (Python 3.6.9) and PyPy 7.1.1 (Python 2.7.13) (and geographiclib 1.52, numpy 1.16.3, 1.16.4, 1.16.6, 1.19.0, 1.19.4, 1.19.5 or 1.22.4 and scipy 1.2.1, 1.4.1, 1.5.2 or 1.8.1) on Ubuntu 16.04, with Python 3.10.0-1, 3.9.0-5, 3.8.0-6, 3.7.2-6, 3.7.0, 3.6.2-5, 3.5.3, 2.7.13-17, 2.7.10 and 2.6.9 (and numpy 1.19.0, 1.16.5, 1.16.2, 1.15.2, 1.14.0, 1.13.1, 1.8.0rc1 or 1.6.2 and scipy 1.5.0), PyPy 7.3.0 (Python 2.7.13 and 3.6.9), PyPy 6.0.0 (Python 2.7.13 and 3.5.3) and Intel-Python 3.5.3 (and numpy 1.11.3) on macOS 14.0-5 Sonoma, 13.0-5.2 Ventura, 12.1-6 Monterey, 11.0-5.2-6.1 Big Sur (aka 10.16), 10.15.3, 10.15.5-7 Catalina, 10.14 Mojave, 10.13.6 High Sierra and 10.12 Sierra, MacOS X 10.11 El Capitan and/or MacOS X 10.10 Yosemite, with Pythonista3.2 (with geographiclib 1.50 or 1.49 and numpy 1.8.0) on iOS 14.4.2, 11.4.1, 12.0-3 on iPad4, iPhone6, iPhone10 and/or iPhone12, with Pythonista 3.1 on iOS 10.3.3, 11.0.3, 11.1.2 and 11.3 on iPad4, all in 64-bit only and with 32-bit Python 2.7.14 on Windows Server 2012R2, Windows 10 Pro and with 32-bit Python 2.6.6 on Windows XP SP3.

Notes

All Python source code has been statically checked with PyChecker, PyFlakes, PyCodeStyle (formerly Pep8) and McCabe using Python 2.7.18 and with Flake8 using Python 3.11.5, both in 64-bit on macOS 14.6.1 Sonoma.

For a summary of all Karney-based functionality in pygeodesy, see module karney.

In Python 2, symbols S_DEG, S_MIN, S_SEC, S_RAD and S_SEP may be multi-byte, non-ascii characters and if so, not unicode.

Env variables

The following environment variables are observed by pygeodesy:

and these to specify standard or named representations:

plus during development:

and:

License

**) Copyright (C) 2016-2025 -- mrJean1 at Gmail -- All Rights Reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


Version: 25.01.09

Submodules

Classes
  ADict
A dict with both key and attribute access to the dict items.
  Aer
Local Azimuth-Elevation-Range (AER) in a local tangent plane.
  Aer4Tuple
4-Tuple (azimuth, elevation, slantrange, ltp), all in meter except ltp.
  Albers7Tuple
7-Tuple (x, y, lat, lon, gamma, scale, datum), in meter, meter, degrees90, degrees180, degrees360, scalar and Datum where (x, y) is the projected, (lat, lon) the geodetic location, gamma the meridian convergence at point, the bearing of the y-axis measured clockwise from true North and scale is the azimuthal scale of the projection at point.
  AlbersEqualArea
An Albers equal-area (authalic) projection with a single standard parallel.
  AlbersEqualArea2
An Albers equal-area (authalic) projection with two standard parallels.
  AlbersEqualArea4
An Albers equal-area (authalic) projection specified by the sin and cos of both standard parallels.
  AlbersEqualAreaCylindrical
An AlbersEqualArea projection at lat=0 and k0=1 degenerating to the cylindrical-equal-area projection.
  AlbersEqualAreaNorth
An azimuthal AlbersEqualArea projection at lat=90 and k0=1 degenerating to the azimuthal LambertEqualArea projection.
  AlbersEqualAreaSouth
An azimuthal AlbersEqualArea projection at lat=-90 and k0=1 degenerating to the azimuthal LambertEqualArea projection.
  AlbersError
An AlbersEqualArea, AlbersEqualArea2, AlbersEqualArea4, AlbersEqualAreaCylindrical, AlbersEqualAreaNorth, AlbersEqualAreaSouth or Albers7Tuple issue.
  Area3Tuple
3-Tuple (number, perimeter, area) with the number of points of the polygon or polyline, the perimeter in meter and the area in meter squared.
  Attitude
The pose of a plane or camera in space.
  Attitude4Tuple
4-Tuple (alt, tilt, yaw, roll) with altitude in (positive) meter and tilt, yaw and roll in degrees representing the attitude of a plane or camera.
  AttitudeError
An Attitude or Attitude4Tuple issue.
  AuxError
Error raised for a rhumb.aux_, Aux, AuxDLat or AuxLat issue.
  Azimuth
Named float representing an azimuth in compass degrees from (true) North.
  Azimuthal7Tuple
7-Tuple (x, y, lat, lon, azimuth, scale, datum), in meter, meter, degrees90, degrees180, compass degrees, scalar and Datum where (x, y) is the easting and northing of a projected point, (lat, lon) the geodetic location, azimuth the azimuth, clockwise from true North and scale is the projection scale, either 1 / reciprocal or 1 or -1 in the Equidistant case.
  AzimuthalError
An azimuthal Equidistant, EquidistantKarney, Gnomonic, LambertEqualArea, Orthographic, Stereographic or Azimuthal7Tuple issue.
  Band
Named str representing a UTM/UPS band letter, unchecked.
  Bearing
Named float representing a bearing in compass degrees from (true) North.
  Bearing2Tuple
2-Tuple (initial, final) bearings, both in compass degrees360.
  Bearing_
Named float representing a bearing in radians from compass degrees from (true) North.
  BetaOmega2Tuple
2-Tuple (beta, omega) with ellipsoidal lat- and longitude beta and omega both in Radians (or Degrees).
  BetaOmega3Tuple
3-Tuple (beta, omega, height) with ellipsoidal lat- and longitude beta and omega both in Radians (or Degrees) and the height, rather the (signed) distance to the triaxial's surface (measured along the radial line to the triaxial's center) in meter, conventionally.
  Bool
Named bool, a sub-class of int like Python's bool.
  BooleanFHP
Composite class providing boolean operations between two composites using Forster-Hormann-Popa's C++ implementation, transcoded to pure Python.
  BooleanGH
Composite class providing boolean operations between two composites using the Greiner-Hormann algorithm and Correia's implementation, modified and extended.
  Bounds2Tuple
2-Tuple (latlonSW, latlonNE) with the bounds' lower-left and upper-right corner as LatLon instance.
  Bounds4Tuple
4-Tuple (latS, lonW, latN, lonE) with the bounds' lower-left (LatS, LowW) and upper-right (latN, lonE) corner lat- and longitudes.
  CSSError
Cassini-Soldner (CSS) conversion or other Css issue.
  CassiniSoldner
Cassini-Soldner projection, a Python version of Karney's C++ class CassiniSoldner.
  ChLV
Conversion between WGS84 geodetic and Swiss projection coordinates using pygeodesy.EcefKarney's Earth-Centered, Earth-Fixed (ECEF) methods.
  ChLV9Tuple
9-Tuple (Y, X, h_, lat, lon, height, ltp, ecef, M) with unfalsed Swiss (Y, X, h_) coordinates and height, all in meter, ltp either a ChLV, ChLVa or ChLVe instance and ecef (EcefKarney at Bern, Ch), otherwise like Local9Tuple.
  ChLVEN2Tuple
2-Tuple (E_LV95, N_LV95) with falsed Swiss LV95 easting and norting in meter (2_600_000, 1_200_000) and origin at Bern, Ch.
  ChLVYX2Tuple
2-Tuple (Y, X) with unfalsed Swiss LV95 easting and norting in meter.
  ChLVa
Conversion between WGS84 geodetic and Swiss projection coordinates using the Approximate formulas, page 13.
  ChLVe
Conversion between WGS84 geodetic and Swiss projection coordinates using the Ellipsoidal approximate formulas, pp 10-11 and Bolliger, J. pp 148-151 (also GGGS).
  ChLVyx2Tuple
2-Tuple (y_LV03, x_LV03) with falsed Swiss LV03 easting and norting in meter (600_000, 200_000) and origin at Bern, Ch.
  Circin6Tuple
6-Tuple (radius, center, deltas, cA, cB, cC) with the radius, the trilaterated center and contact points of the inscribed aka In- circle of a triangle.
  Circle4Tuple
4-Tuple (radius, height, lat, beta) of the radius and height, both conventionally in meter of a parallel circle of latitude at (geodetic) latitude lat and the parametric (or reduced) auxiliary latitude beta, both in degrees90.
  Circum3Tuple
3-Tuple (radius, center, deltas) with the circumradius and trilaterated circumcenter of the circumcircle through 3 points (aka {Meeus}' Type II circle) or the radius and center of the smallest Meeus' Type I circle.
  Circum4Tuple
4-Tuple (radius, center, rank, residuals) with radius and center of a sphere least-squares fitted through given points and the rank and residuals -if any- from numpy.linalg.lstsq.
  ClipCS3Tuple
DEPRECATED, see DEPRECATED function pygeodesy.deprecated.clipCS3.
  ClipCS4Tuple
4-Tuple (start, end, i, j) for each edge of a clipped path with the start and end points (LatLon) of the portion of the edge inside or on the clip box and the indices i and j (int) of the edge start and end points in the original path.
  ClipError
Clip box or clip region issue.
  ClipFHP4Tuple
4-Tuple (lat, lon, height, clipid) for each point of the clipFHP4 result with the lat-, longitude, height and clipid of the polygon or clip.
  ClipGH4Tuple
4-Tuple (lat, lon, height, clipid) for each point of the clipGH4 result with the lat-, longitude, height and clipid of the polygon or clip.
  ClipLB6Tuple
6-Tuple (start, end, i, fi, fj, j) for each edge of the clipped path with the start and end points (LatLon) of the portion of the edge inside or on the clip box, indices i and j (both int) of the original path edge start and end points and fractional indices fi and fj (both FIx) of the start and end points along the edge of the original path.
  ClipSH3Tuple
3-Tuple (start, end, original) for each edge of a clipped polygon, the start and end points (LatLon) of the portion of the edge inside or on the clip region and original indicates whether the edge is part of the original polygon or part of the clip region (bool).
  Collins5Tuple
5-Tuple (pointP, pointH, a, b, c) with survey pointP, auxiliary pointH, each an instance of pointA's (sub-)class and triangle sides a, b and c in meter, conventionally.
  Conic
Lambert conformal conic projection (1- or 2-SP).
  CrossError
Error raised for zero or near-zero vectorial cross products, occurring for coincident or colinear points, lines or bearings.
  Css
Cassini-Soldner East-/Northing location.
  Curvature2Tuple
2-Tuple (meridional, prime_vertical) of radii of curvature, both in meter, conventionally.
  Datum
Ellipsoid and transform parameters for an earth model.
  Degrees
Named float representing a coordinate in degrees, optionally clipped.
  Degrees2
Named float representing a distance in degrees squared.
  Degrees_
Named Degrees representing a coordinate in degrees with optional limits low and high.
  Destination2Tuple
2-Tuple (destination, final), destination in LatLon and final bearing in compass degrees360.
  Destination3Tuple
3-Tuple (lat, lon, final), destination lat, lon in degrees90 respectively degrees180 and final bearing in compass degrees360.
  Direct9Tuple
9-Tuple (a12, lat2, lon2, azi2, s12, m12, M12, M21, S12) with arc length a12, angles lat2, lon2 and azimuth azi2 in degrees, distance s12 and reduced length m12 in meter and area S12 in meter squared.
  Distance
Named float representing a distance, conventionally in meter.
  Distance2Tuple
2-Tuple (distance, initial), distance in meter and initial bearing in compass degrees360.
  Distance3Tuple
3-Tuple (distance, initial, final), distance in meter and initial and final bearing, both in compass degrees360.
  Distance4Tuple
4-Tuple (distance2, delta_lat, delta_lon, unroll_lon2) with the distance in degrees squared, the latitudinal delta_lat = lat2 - lat1, the wrapped, unrolled and adjusted longitudinal delta_lon = lon2 - lon1 and unroll_lon2, the unrolled or original lon2.
  Distance_
Named float with optional low and high limits representing a distance, conventionally in meter.
  DivMod2Tuple
2-Tuple (div, mod) with the quotient div and remainder mod results of a divmod operation.
  EPSGError
EPSG encode, decode or other Epsg issue.
  ETMError
Exact Transverse Mercator (ETM) parse, projection or other Etm issue or ExactTransverseMercator conversion failure.
  EasNor2Tuple
2-Tuple (easting, northing), both in meter, conventionally.
  EasNor3Tuple
3-Tuple (easting, northing, height), all in meter, conventionally.
  EasNorAziRk4Tuple
4-Tuple (easting, northing, azimuth, reciprocal) for the Cassini-Soldner location with easting and northing in meters and the azimuth of easting direction and reciprocal of azimuthal northing scale, both in degrees.
  EasNorAziRkEqu6Tuple
6-Tuple (easting, northing, azimuth, reciprocal, equatorarc, equatorazimuth) for the Cassini-Soldner location with easting and northing in meters and the azimuth of easting direction, reciprocal of azimuthal northing scale, equatorarc and equatorazimuth, all in degrees.
  EasNorExact4Tuple
DEPRECATED, use class Forward4Tuple, item gamma for convergence.
  EasNorRadius3Tuple
3-Tuple (easting, northing, radius), all in meter.
  Easting
Named float representing an easting, conventionally in meter.
  Ecef9Tuple
9-Tuple (x, y, z, lat, lon, height, C, M, datum) with geocentric x, y and z plus geodetic lat, lon and height, case C (see the Ecef*.reverse methods) and optionally, rotation matrix M (EcefMatrix) and datum, with lat and lon in degrees and x, y, z and height in meter, conventionally.
  EcefError
An ECEF or Ecef* related issue.
  EcefFarrell21
Conversion between geodetic and geocentric, Earth-Centered, Earth-Fixed (ECEF) coordinates based on Jay A. Farrell's Table 2.1, page 29.
  EcefFarrell22
Conversion between geodetic and geocentric, Earth-Centered, Earth-Fixed (ECEF) coordinates based on Jay A. Farrell's Table 2.2, page 30.
  EcefKarney
Conversion between geodetic and geocentric, Earth-Centered, Earth-Fixed (ECEF) coordinates transcoded from Karney's C++ Geocentric methods.
  EcefMatrix
A rotation matrix known as East-North-Up (ENU) to ECEF.
  EcefSudano
Conversion between geodetic and geocentric, Earth-Centered, Earth-Fixed (ECEF) coordinates based on John J. Sudano's paper.
  EcefVeness
Conversion between geodetic and geocentric, Earth-Centered, Earth-Fixed (ECEF) coordinates transcoded from Chris Veness' JavaScript classes LatLonEllipsoidal, Cartesian.
  EcefYou
Conversion between geodetic and geocentric, Earth-Centered, Earth-Fixed (ECEF) coordinates using Rey-Jer You's transformation for non-prolate ellipsoids.
  Elevation2Tuple
2-Tuple (elevation, data_source) in meter and str.
  Ellipsoid
Ellipsoid with equatorial and polar radii, flattening, inverse flattening and other, often used, cached attributes, supporting oblate and prolate ellipsoidal and spherical earth models.
  Ellipsoid2
An Ellipsoid specified by equatorial radius and flattening.
  Elliptic
Elliptic integrals and functions.
  Elliptic3Tuple
3-Tuple (sn, cn, dn) all scalar.
  EllipticError
Elliptic function, integral, convergence or other Elliptic issue.
  Enu
Local Eeast-North-Up (ENU) location in a local tangent plane.
  Enu4Tuple
4-Tuple (east, north, up, ltp), in meter except ltp.
  Epoch
Named epoch with optional low and high limits representing a fractional calendar year.
  Epsg
EPSG class, a named int.
  Equidistant
Azimuthal equidistant projection for the sphere***, see Snyder, pp 195-197 and MathWorld-Wolfram.
  EquidistantExact
Azimuthal equidistant projection, a Python version of Karney's C++ class AzimuthalEquidistant, based on exact geodesic classes GeodesicExact and GeodesicLineExact.
  EquidistantGeodSolve
Azimuthal equidistant projection, a Python version of Karney's C++ class AzimuthalEquidistant, based on (exact) geodesic wrappers GeodesicSolve and GeodesicLineSolve and intended for testing purposes only.
  EquidistantKarney
Azimuthal equidistant projection, a Python version of Karney's C++ class AzimuthalEquidistant, requiring package geographiclib to be installed.
  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
Pure Python version of Karney's C++ class TransverseMercatorExact, a numerically exact transverse Mercator projection, abbreviated as TMExact.
  FIx
A named Fractional Index, an int or float index into a list or tuple of points, typically.
  Fcbrt
Cubic root of a precision summation.
  Fcook
Cook's RunningStats computing the running mean, median and (sample) kurtosis, skewness, variance, standard deviation and Jarque-Bera normality.
  Fdot
Precision dot product.
  Feet
Named float representing a distance or length in feet.
  Fhorner
Precision polynomial evaluation using the Horner form.
  Fhypot
Precision summation and hypotenuse, default root=2.
  Flinear
Cook's RunningRegression computing the running slope, intercept and correlation of a linear regression.
  Float
Named float.
  Float_
Named float with optional low and high limit.
  Footprint5Tuple
5-Tuple (center, upperleft, upperight, loweright, lowerleft) with the center and 4 corners of the local projection of a Frustum, each an Xyz4Tuple, XyzLocal, LatLon, etc.
  Forward4Tuple
4-Tuple (easting, northing, gamma, scale) in meter, meter, meridian convergence gamma at point in degrees and the scale of projection at point scalar.
  Fpolynomial
Precision polynomial evaluation.
  Fpowers
Precision summation of powers, optimized for power=2, 3 and 4.
  Frechet
Frechet base class, requires method Frechet.distance to be overloaded.
  Frechet6Tuple
6-Tuple (fd, fi1, fi2, r, n, units) with the discrete Fréchet distance fd, fractional indices fi1 and fi2 as FIx, the recursion depth r, the number of distances computed n and the units class or class or name of the distance units.
  FrechetCosineLaw
Compute the Frechet distance with functionn pygeodesy.cosineLaw.
  FrechetDegrees
DEPRECATED, use an other Frechet* class.
  FrechetDistanceTo
Compute the Frechet distance with the point1s' LatLon.distanceTo method.
  FrechetEquirectangular
Compute the Frechet distance with function pygeodesy.equirectangular.
  FrechetError
Fréchet issue.
  FrechetEuclidean
Compute the Frechet distance with function pygeodesy.euclidean.
  FrechetExact
Compute the Frechet distance with method GeodesicExact.Inverse.
  FrechetFlatLocal
Compute the Frechet distance with function pygeodesy.flatLocal_/pygeodesy.hubeny.
  FrechetFlatPolar
Compute the Frechet distance with function flatPolar_.
  FrechetHaversine
Compute the Frechet distance with function pygeodesy.haversine_.
  FrechetHubeny
Compute the Frechet distance with function pygeodesy.flatLocal_/pygeodesy.hubeny.
  FrechetKarney
Compute the Frechet distance with Karney's geographiclib geodesic.Geodesic.Inverse method.
  FrechetRadians
DEPRECATED, use an other Frechet* class.
  FrechetThomas
Compute the Frechet distance with function pygeodesy.thomas_.
  FrechetVincentys
Compute the Frechet distance with function pygeodesy.vincentys_.
  Froot
The root of a precision summation.
  Frustum
A rectangular pyramid, typically representing a camera's field-of-view (fov) and the intersection with (or projection to) a local tangent plane.
  Fsqrt
Square root of a precision summation.
  Fsum
Precision floating point summation, running summation and accurate multiplication.
  Fsum2Tuple
2-Tuple (fsum, residual) with the precision running fsum and the residual, the sum of the remaining partials.
  Fwelford
Welford's accumulator computing the running mean, (sample) variance and standard deviation.
  GARSError
Global Area Reference System (GARS) encode, decode or other Garef issue.
  GDict
A dict with both key and attribute access to the dict items.
  Garef
Garef class, a named str.
  GeodSolve12Tuple
12-Tuple (lat1, lon1, azi1, lat2, lon2, azi2, s12, a12, m12, M12, M21, S12) with angles lat1, lon1, azi1, lat2, lon2 and azi2 and arc a12 all in degrees, initial azi1 and final azi2 forward azimuths, distance s12 and reduced length m12 in meter, area S12 in meter squared and geodesic scale factors M12 and M21, both scalar, see GeodSolve.
  Geodesic
Wrapper around Karney's class geographiclib.geodesic.Geodesic.
  GeodesicAreaExact
Area and perimeter of a geodesic polygon, an enhanced version of Karney's Python class PolygonArea using the more accurate surface area.
  GeodesicError
Error raised for convergence or other issues in geodesicx, geodesicw or karney.
  GeodesicExact
A pure Python version of Karney's C++ class GeodesicExact, modeled after Karney's Python class geodesic.Geodesic.
  GeodesicLine
Wrapper around Karney's class geographiclib.geodesicline.GeodesicLine.
  GeodesicLineExact
A pure Python version of Karney's C++ class GeodesicLineExact, modeled after Karney's Python class geodesicline.GeodesicLine.
  GeodesicLineSolve
Wrapper to invoke Karney's GeodSolve as an Exact version of Karney's Python class GeodesicLine.
  GeodesicSolve
Wrapper to invoke Karney's GeodSolve as an Exact version of Karney's Python class Geodesic.
  Geohash
Geohash class, a named str.
  GeohashError
Geohash encode, decode or other Geohash issue.
  Geohashed
A cache of en- and decoded geohashes of one precision.
  GeoidEGM96
Geoid height interpolator for the EGM96 15 Minute Interpolation Grid based on SciPy interpolation RectBivariateSpline, interp2d or bisplrep/-ev.
  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 interpolation RectBivariateSpline, interp2d or bisplrep/-ev.
  GeoidHeight2Tuple
2-Tuple (height, model_name), geoid height in meter and model_name as str.
  GeoidHeight5Tuple
5-Tuple (lat, lon, egm84, egm96, egm2008) for GeoidHeights.dat tests with the heights for 3 different EGM grids at degrees90 and degrees180 degrees (after converting lon from original 0 <= EasterLon <= 360).
  GeoidKarney
Geoid height interpolator for Karney's GeographicLib Earth Gravitational Model (EGM) geoid egm*.pgm datasets using bilinear or cubic interpolation and caching in pure Python, transcoded from Karney's C++ class Geoid.
  GeoidPGM
Geoid height interpolator for Karney's GeographicLib Earth Gravitational Model (EGM) geoid egm*.pgm datasets but based on SciPy RectBivariateSpline, bisplrep/-ev or interp2d interpolation.
  Georef
Georef class, a named str.
  Gnomonic
Azimuthal gnomonic projection for the sphere***, see Snyder, pp 164-168 and MathWorld-Wolfram.
  GnomonicExact
Azimuthal gnomonic projection, a Python version of Karney's C++ class Gnomonic, based on exact geodesic classes GeodesicExact and GeodesicLineExact.
  GnomonicGeodSolve
Azimuthal gnomonic projection, a Python version of Karney's C++ class Gnomonic, based on (exact) geodesic wrappers GeodesicSolve and GeodesicLineSolve and intended for testing purposes only.
  GnomonicKarney
Azimuthal gnomonic projection, a Python version of Karney's C++ class Gnomonic, requiring package geographiclib to be installed.
  Hausdorff
Hausdorff base class, requires method Hausdorff.distance to be overloaded.
  Hausdorff6Tuple
6-Tuple (hd, i, j, mn, md, units) with the Hausdorff distance hd, indices i and j, the total count mn, the mean Hausdorff distance md and the class or name of both distance units.
  HausdorffCosineLaw
Compute the Hausdorff distance with function pygeodesy.cosineLaw_.
  HausdorffDegrees
Hausdorff base class for distances from LatLon points in degrees.
  HausdorffDistanceTo
Compute the Hausdorff distance the points' LatLon.distanceTo method.
  HausdorffEquirectangular
Compute the Hausdorff distance with function pygeodesy.equirectangular.
  HausdorffError
Hausdorff issue.
  HausdorffEuclidean
Compute the Hausdorff distance with function pygeodesy.euclidean_.
  HausdorffExact
Compute the Hausdorff distance with method GeodesicExact.Inverse.
  HausdorffFlatLocal
Compute the Hausdorff distance with function pygeodesy.flatLocal_/pygeodesy.hubeny_.
  HausdorffFlatPolar
Compute the Hausdorff distance with function pygeodesy.flatPolar_.
  HausdorffHaversine
Compute the Hausdorff distance with function pygeodesy.haversine_.
  HausdorffHubeny
Compute the Hausdorff distance with function pygeodesy.flatLocal_/pygeodesy.hubeny_.
  HausdorffKarney
Compute the Hausdorff distance with Karney's geographiclib geodesic.Geodesic.Inverse method.
  HausdorffRadians
Hausdorff base class for distances from LatLon points converted from degrees to radians.
  HausdorffThomas
Compute the Hausdorff distance with function pygeodesy.thomas_.
  HausdorffVincentys
Compute the Hausdorff distance with function pygeodesy.vincentys_.
  Height
Named float representing a height, conventionally in meter.
  HeightCubic
Height interpolator based on SciPy interp2d kind='cubic' or bisplrep/-ev kx=ky=3.
  HeightError
Height interpolator Height... or interpolation issue.
  HeightIDWcosineLaw
Height interpolator using Inverse Distance Weighting (IDW) and function pygeodesy.cosineLaw.
  HeightIDWdistanceTo
Height interpolator using Inverse Distance Weighting (IDW) and the points' LatLon.distanceTo method.
  HeightIDWequirectangular
Height interpolator using Inverse Distance Weighting (IDW) and function pygeodesy.equirectangular4.
  HeightIDWeuclidean
Height interpolator using Inverse Distance Weighting (IDW) and function pygeodesy.euclidean_.
  HeightIDWexact
Height interpolator using Inverse Distance Weighting (IDW) and method GeodesicExact.Inverse.
  HeightIDWflatLocal
Height interpolator using Inverse Distance Weighting (IDW) and the function pygeodesy.flatLocal_/pygeodesy.hubeny_.
  HeightIDWflatPolar
Height interpolator using Inverse Distance Weighting (IDW) and function pygeodesy.flatPolar_.
  HeightIDWhaversine
Height interpolator using Inverse Distance Weighting (IDW) and function pygeodesy.haversine_.
  HeightIDWhubeny
Height interpolator using Inverse Distance Weighting (IDW) and the function pygeodesy.flatLocal_/pygeodesy.hubeny_.
  HeightIDWkarney
Height interpolator using Inverse Distance Weighting (IDW) and Karney's geographiclib method geodesic.Geodesic.Inverse.
  HeightIDWthomas
Height interpolator using Inverse Distance Weighting (IDW) and function pygeodesy.thomas_.
  HeightIDWvincentys
Height interpolator using Inverse Distance Weighting (IDW) and function pygeodesy.vincentys_.
  HeightLSQBiSpline
Height interpolator using SciPy LSQSphereBivariateSpline.
  HeightLinear
Height interpolator based on SciPy interp2d kind='linear' or bisplrep/-ev kx=ky=1.
  HeightSmoothBiSpline
Height interpolator using SciPy SmoothSphereBivariateSpline.
  HeightX
Like Height, used to distinguish the interpolated height from an original Height at a clip intersection.
  Height_
Named float with optional low and high limits representing a height, conventionally in meter.
  Helmert7Tuple
DEPRECATED on 2024.02.02, use class TRFXform7Tuple, without keyword arguments.
  Int
Named int.
  Int_
Named int with optional limits low and high.
  Intersect7Tuple
7-Tuple (A, B, sAB, aAB, c, kA, kB) with A and B each a LatLon or LatLon4Tuple(lat, lon, height, datum) of the intersection on each geodesic line, the distance sAB in in meter and angular distance aAB in degrees between A and B, coincidence indicator c and segment indicators kA and kB all int, see XDict and method intersect7.
  Intersection3Tuple
3-Tuple (point, outside1, outside2) of an intersection point and outside1, the position of the point, -1 if before the start, +1 if after the end and 0 if on or between the start and end point of the first line.
  IntersectionError
Error raised for line or circle intersection issues.
  Intersectool
Wrapper to invoke Karney's utility IntersectTool similar to class Intersector.
  Intersectool5Tuple
5-Tuple (A, B, sAB, aAB, c) with A and B the Position of the intersection on each geodesic line, the distance sAB between A and B in meter, the angular distance aAB in degrees and coincidence indicator c (int), see XDict.
  Intersector
Finder of intersections between two goedesic lines, each an instance of GeodesicLineExact, wrapped GeodesicLine or GeodesicLineSolve.
  Intersector5Tuple
5-Tuple (A, B, sAB, aAB, c) with A and B the Position of the intersection on each geodesic line, the distance sAB between A and B in meter, angular distance aAB in degrees and coincidence indicator c (int), see XDict.
  Inverse10Tuple
10-Tuple (a12, s12, salp1, calp1, salp2, calp2, m12, M12, M21, S12) with arc length a12 in degrees, distance s12 and reduced length m12 in meter, area S12 in meter squared and the sines salp1, salp2 and cosines calp1, calp2 of the initial 1 and final 2 (forward) azimuths.
  Jacobi2Tuple
2-Tuple (x, y) with a Jacobi Conformal x and y projection, both in Radians (or Degrees).
  JacobiConformal
This is a conformal projection of a triaxial ellipsoid to a plane in which the X and Y grid lines are straight.
  JacobiConformalSpherical
An alternate, spherical JacobiConformal projection.
  KTMError
Error raised for KTransverseMercator and KTransverseMercator.forward issues.
  KTransverseMercator
Karney's C++ class TransverseMercator transcoded to pure Python, following is a partial copy of Karney's documentation.
  LCCError
Lambert Conformal Conic LCC or other Lcc issue.
  Lam
Named float representing a longitude in radians.
  Lam_
DEPRECATED on 2024.06.15, use class Lamd.
  LambertEqualArea
Lambert-equal-area projection for the sphere*** (aka Lambert zenithal equal-area projection, see Snyder, pp 185-187 and MathWorld-Wolfram.
  Lamd
Named float representing a longitude in radians converted from degrees.
  Lat
Named float representing a latitude in degrees.
  LatLon2PsxyIter
Iterate and convert for points with optional loop-back and copies.
  LatLon2Tuple
2-Tuple (lat, lon) in degrees90 and degrees180.
  LatLon2psxy
Wrapper for LatLon points as "on-the-fly" pseudo-xy coordinates.
  LatLon3Tuple
3-Tuple (lat, lon, height) in degrees90, degrees180 and meter, conventionally.
  LatLon4Tuple
4-Tuple (lat, lon, height, datum) in degrees90, degrees180, meter and Datum.
  LatLonAziRk4Tuple
4-Tuple (lat, lon, azimuth, reciprocal), all in degrees where azimuth is the azimuth of easting direction and reciprocal the reciprocal of azimuthal northing scale.
  LatLonDatum3Tuple
3-Tuple (lat, lon, datum) in degrees90, degrees180 and Datum.
  LatLonDatum5Tuple
5-Tuple (lat, lon, datum, gamma, scale) in degrees90, degrees180, Datum, degrees and float.
  LatLonExact4Tuple
DEPRECATED, use class Reverse4Tuple, item gamma for convergence.
  LatLonFHP
A point or intersection in a BooleanFHP clip or composite.
  LatLonGH
A point or intersection in a BooleanGH clip or composite.
  LatLonHeightBase
'DEPRECATED on 2021.02.10, use (INTERNAL) class pygeodesy.latlonBase.LatLonBase.
  LatLonNvectorBase
(INTERNAL) Base class for n-vector-based ellipsoidal and spherical LatLons.
  LatLonPrec3Tuple
3-Tuple (lat, lon, precision) in degrees, degrees and int.
  LatLonPrec5Tuple
5-Tuple (lat, lon, precision, height, radius) in degrees, degrees, int and height or radius in meter (or None if missing).
  LatLon_
Low-overhead LatLon class, mainly for Numpy2LatLon and Tuple2LatLon.
  Lat_
Named float representing a latitude in degrees within limits low and high.
  LazyAttributeError
Raised if a lazily imported attribute is missing or invalid.
  LazyImportError
Raised if lazy import is not supported, disabled or failed some other way.
  Lcc
Lambert conformal conic East-/Northing location.
  LenError
Error raised for mis-matching len values.
  LimitError
Error raised for lat- or longitudinal values or deltas exceeding the given limit in functions equirectangular, equirectangular4, nearestOn* and simplify* or methods with limit or options keyword arguments.
  Local9Tuple
9-Tuple (x, y, z, lat, lon, height, ltp, ecef, M) with local x, y, z all in meter, geodetic lat, lon, height, local tangent plane ltp (Ltp), ecef (Ecef9Tuple) with geocentric x, y, z, geodetic lat, lon, height and concatenated rotation matrix M (EcefMatrix) or None.
  LocalCartesian
Conversion between geodetic (lat, lon, height) and local cartesian (x, y, z) coordinates with geodetic origin (lat0, lon0, height0), transcoded from Karney's C++ class LocalCartesian.
  LocalError
A LocalCartesian or Ltp related issue.
  Lon
Named float representing a longitude in degrees.
  Lon_
Named float representing a longitude in degrees within limits low and high.
  Los
A Line-Of-Sight (LOS) from a LatLon or Cartesian location.
  Ltp
A local tangent plan (LTP), a sub-class of LocalCartesian with (re-)configurable ECEF converter.
  MGRSError
Military Grid Reference System (MGRS) parse or other Mgrs issue.
  Meeus2Tuple
2-Tuple (radius, Type) with radius and Meeus' Type of the smallest circle containing 3 points.
  Meter
Named float representing a distance or length in meter.
  Meter2
Named float representing an area in meter squared.
  Meter3
Named float representing a volume in meter cubed.
  Meter_
Named float representing a distance or length in meter.
  Mgrs
Military Grid Reference System (MGRS/NATO) references, with method to convert to UTM coordinates.
  Mgrs4Tuple
4-Tuple (zone, EN, easting, northing), zone and grid tile EN as str, easting and northing in meter.
  Mgrs6Tuple
6-Tuple (zone, EN, easting, northing, band, datum), with zone, grid tile EN and band as str, easting and northing in meter and datum a Datum.
  Middle5Tuple
5-Tuple (A, B, sMM, aMM, c) with A and B the line segments including the mid-point location in latM, lonM, distance s1M in meter and angular distance a1M in degrees, the distance between both mid-points sMM in meter and angular distance aMM in degrees and coincidence indicator c (int).
  NearestOn2Tuple
2-Tuple (closest, fraction) of the closest point on and fraction along a line (segment) between two points.
  NearestOn3Tuple
3-Tuple (closest, distance, angle) of the closest point on the polygon, either a LatLon instance or a LatLon3Tuple(lat, lon, height) and the distance and angle to the closest point are in meter respectively compass degrees360.
  NearestOn4Tuple
DEPRECATED on 2023.10.10, see methods RhumbLine.nearestOn4 and RhumbLineAux.nearestOn4.
  NearestOn6Tuple
6-Tuple (closest, distance, fi, j, start, end) with the closest point, the distance in meter, conventionally and the start and end point of the path or polygon edge.
  NearestOn8Tuple
8-Tuple (closest, distance, fi, j, start, end, initial, final), like NearestOn6Tuple but extended with the initial and the final bearing at the reference respectively the closest point, both in compass degrees.
  Ned
Local North-Eeast-Down (NED) location in a local tangent plane.
  Ned3Tuple
DEPRECATED, use class Ned4Tuple, ignoring item ltp.
  Ned4Tuple
4-Tuple (north, east, down, ltp), all in meter except ltp.
  Neighbors8Dict
8-Dict (N, NE, E, SE, S, SW, W, NW) of Geohashes, providing key and attribute access to the items.
  Northing
Named float representing a northing, conventionally in meter.
  NumPyError
Error raised for NumPy issues.
  Number_
Named int representing a non-negative number.
  Numpy2LatLon
Wrapper for NumPy arrays as "on-the-fly" LatLon points.
  Nvector
DEPRECATED on 2021.05.20, see (INTERNAL) class pygeodesy.nvectorBase.NvectorBase.
  OSGRError
Error raised for a parseOSGR, Osgr or other OSGR issue.
  Orthographic
Orthographic projection for the sphere***, see Snyder, pp 148-153 and MathWorld-Wolfram.
  Osgr
Ordnance Survey Grid References (OSGR) coordinates on the National Grid.
  PGMError
An issue while parsing or cropping an egm*.pgm geoid dataset.
  ParseError
Error parsing degrees, radians or several other formats.
  Phi
Named float representing a latitude in radians.
  PhiLam2Tuple
2-Tuple (phi, lam) with latitude phi in radians[PI_2] and longitude lam in radians[PI].
  PhiLam3Tuple
3-Tuple (phi, lam, height) with latitude phi in radians[PI_2], longitude lam in radians[PI] and height in meter.
  PhiLam4Tuple
4-Tuple (phi, lam, height, datum) with latitude phi in radians[PI_2], longitude lam in radians[PI], height in meter and Datum.
  Phi_
DEPRECATED on 2024.06.15, use class Phid.
  Phid
Named float representing a latitude in radians converted from degrees.
  Point3Tuple
3-Tuple (x, y, ll) in meter, meter and LatLon.
  Points2Tuple
2-Tuple (number, points) with the number of points and -possible reduced- list or tuple of points.
  PointsError
Error for an insufficient number of points.
  PointsIter
Iterator for points with optional loop-back and copies.
  PolygonArea
For geographiclib compatibility, sub-class of GeodesicAreaExact.
  Precision_
Named int with optional low and high limits representing a precision.
  Property
  Property_RO
  Radians
Named float representing a coordinate in radians, optionally clipped.
  Radians2
Named float representing a distance in radians squared.
  Radians_
Named float representing a coordinate in radians with optional limits low and high.
  Radical2Tuple
2-Tuple (ratio, xline) of the radical ratio and radical xline, both scalar and 0.0 <= ratio <= 1.0
  Radii11Tuple
11-Tuple (rA, rB, rC, cR, rIn, riS, roS, a, b, c, s) with the Tangent circle radii rA, rB and rC, the circumradius cR, the Incircle radius rIn aka inradius, the inner and outer Soddy circle radii riS and roS, the sides a, b and c and semi-perimeter s of a triangle, all in meter conventionally.
  Radius
Named float representing a radius, conventionally in meter.
  RadiusThetaPhi3Tuple
3-Tuple (r, theta, phi) with radial distance r in meter, inclination theta (with respect to the positive z-axis) and azimuthal angle phi in Degrees or Radians representing a spherical, polar position.
  Radius_
Named float with optional low and high limits representing a radius, conventionally in meter.
  RangeError
Error raised for lat- or longitude values outside the clip, clipLat, clipLon in functions parse3llh, parseDMS, parseDMS2 and parseRad or the limit set with functions clipDegrees and clipRadians.
  RefFrame
Terrestrial Reference Frame (TRF) parameters.
  ResectionError
Error raised for issues in pygeodesy.resections.
  ResidualError
Error raised for a division, power or root operation of an Fsum instance with a residual ratio exceeding the RESIDUAL threshold.
  Resolutions2Tuple
2-Tuple (res1, res2) with the primary (longitudinal) and secondary (latitudinal) resolution, both in degrees.
  Reverse4Tuple
4-Tuple (lat, lon, gamma, scale) with lat- and longitude in degrees, meridian convergence gamma at point in degrees and the scale of projection at point scalar.
  Rhumb
Class to solve the direct and inverse rhumb problems, based on elliptic functions or Krüger series expansion
  Rhumb7Tuple
DEPRECATED, use class Rhumb8Tuple, ignoring item a12.
  Rhumb8Tuple
8-Tuple (lat1, lon1, lat2, lon2, azi12, s12, S12, a12) with lat- lat1, lat2 and longitudes lon1, lon2 of both points, the azimuth of the rhumb line azi12, the distance s12, the area S12 under the rhumb line and the angular distance a12 between both points.
  RhumbAux
Class to solve the direct and inverse rhumb problems, based on Auxiliary Latitudes for accuracy near the poles.
  RhumbError
Error raised for a rhumb aux_, ekx or solve issue.
  RhumbLine
Compute one or several points on a single rhumb line.
  RhumbLineAux
Compute one or several points on a single rhumb line.
  RhumbLineSolve
Wrapper to invoke Karney's RhumbSolve like a class, similar to pygeodesy.RhumbLine and pygeodesy.RhumbLineAux.
  RhumbOrder2Tuple
DEPRECATED, see deprecated method Rhumb.orders.
  RhumbSolve
Wrapper to invoke Karney's RhumbSolve like a class, similar to pygeodesy.Rhumb and pygeodesy.RhumbAux.
  RhumbSolve7Tuple
7-Tuple (lat1, lon1, lat2, lon2, azi12, s12, S12) with lat- lat1, lat2 and longitudes lon1, lon2 of both points, the azimuth of the rhumb line azi12, the distance s12 and the area S12 under the rhumb line between both points.
  Scalar
Named float representing a factor, fraction, scale, etc.
  Scalar_
Named float with optional low and high limits representing a factor, fraction, scale, etc.
  SciPyError
Error raised for SciPy issues.
  SciPyWarning
Error thrown for SciPy warnings.
  Shape2Tuple
2-Tuple (nrows, ncols), the number of rows and columns, both int.
  Sizes3Tuple
3-Tuple (height, width, radius) with latitudinal height, longitudinal width and area radius, all in meter.
  Soddy4Tuple
4-Tuple (radius, center, deltas, outer) with radius and (trilaterated) center of the inner Soddy circle and the radius of the outer Soddy circle.
  Stereographic
Stereographic projection for the sphere***, see Snyder, pp 157-160 and MathWorld-Wolfram.
  Str
Named, callable str.
  Str_
Extended, callable str class, not nameable.
  Survey3Tuple
3-Tuple (PA, PB, PC) with distance from survey point P to each of the triangle corners A, B and C in meter, conventionally.
  TRFError
Terrestrial Reference Frame (TRF), Epoch, RefFrame or RefFrame conversion issue.
  TRFXform
A Terrestrial Reference Frame (TRF) converter between two reference frames observed at an epoch.
  TRFXform7Tuple
7-Tuple (tx, ty, tz, s, sx, sy, sz) of conversion parameters with translations tx, ty and tz in milli-meter, scale s in ppB and rotations sx, sy and sz in milli-arc-seconds.
  Tienstra7Tuple
7-Tuple (pointP, A, B, C, a, b, c) with survey pointP, interior triangle angles A, B and C in degrees and triangle sides a, b and c in meter, conventionally.
  Transform
Helmert datum transformation.
  Transform7Tuple
DEPRECATED on 2024.02.02, use class TRFXform7Tuple, without keyword arguments.
  TransformXform
Helmert transformation, extended with an Xform TRF converter.
  TriAngle4Tuple
DEPRECATED on 2023.09.14, use class TriAngle5Tuple, ignoring item area.
  TriAngle5Tuple
5-Tuple (radA, radB, radC, rIn, area) with the interior angles at triangle corners A, B and C in radians, the InCircle radius rIn aka inradius in meter and the triangle area in meter squared, conventionally.
  TriSide2Tuple
2-Tuple (a, radA) with triangle side a in meter, conventionally and angle radA at the opposite triangle corner in radians.
  TriSide4Tuple
4-Tuple (a, b, radC, d) with interior angle radC at triangle corner C in radianswith the length of triangle sides a and b and with triangle height d perpendicular to triangle side c, in the same units as triangle sides a and b.
  Triangle7Tuple
7-Tuple (A, a, B, b, C, c, area) with interior angles A, B and C in degrees, spherical sides a, b and c in meter conventionally and the area of a (spherical) triangle in square meter conventionally.
  Triangle8Tuple
8-Tuple (A, a, B, b, C, c, D, E) with interior angles A, B and C, spherical sides a, b and c, the spherical deficit D and the spherical excess E of a (spherical) triangle, all in radians.
  TriangleError
Error raised for triangle, intersection or resection issues.
  Triaxial
Ordered triaxial ellipsoid.
  TriaxialError
Raised for Triaxial issues.
  Triaxial_
Unordered triaxial ellipsoid and base class.
  Triaxum5Tuple
5-Tuple (a, b, c, rank, residuals) with the (unordered) triaxial radii a, b and c of an ellipsoid least-squares fitted through given points and the rank and residuals -if any- from numpy.linalg.lstsq.
  Trilaterate5Tuple
5-Tuple (min, minPoint, max, maxPoint, n) with min and max in meter, the corresponding trilaterated minPoint and maxPoint as LatLon and the number n.
  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.
  UnitError
Default exception for units issues for a value exceeding the low or high limit.
  Ups
Universal Polar Stereographic (UPS) coordinate.
  Utm
Universal Transverse Mercator (UTM) coordinate.
  UtmUps2Tuple
2-Tuple (zone, hemipole) as int and str, where zone is 1..60 for UTM or 0 for UPS and hemipole 'N'|'S' is the UTM hemisphere or the UPS pole.
  UtmUps4Tuple
DEPRECATED and OBSOLETE, expect a UtmUps5Tuple from method pygeodesy.Mgrs.toUtm(utm=None).
  UtmUps5Tuple
5-Tuple (zone, hemipole, easting, northing, band) as int, str, meter, meter and band letter, where zone is 1..60 for UTM or 0 for UPS, hemipole 'N'|'S' is the UTM hemisphere or the UPS pole and band is "" or the longitudinal UTM band 'C'|'D'|..|'W'|'X' or polar UPS band 'A'|'B'|'Y'|'Z'.
  UtmUps8Tuple
8-Tuple (zone, hemipole, easting, northing, band, datum, gamma, scale) as int, str, meter, meter, band letter, Datum, degrees and scalar, where zone is 1..60 for UTM or 0 for UPS, hemipole 'N'|'S' is the UTM hemisphere or the UPS pole and band is "" or the longitudinal UTM band 'C'|'D'|..|'W'|'X' or polar UPS band 'A'|'B'|'Y'|'Z'.
  UtmUpsLatLon5Tuple
5-Tuple (zone, band, hemipole, lat, lon) as int, str, str, degrees90 and degrees180, where zone is 1..60 for UTM or 0 for UPS, band is "" or the longitudinal UTM band 'C'|'D'|..|'W'|'X' or polar UPS band 'A'|'B'|'Y'|'Z' and hemipole 'N'|'S' is the UTM hemisphere or the UPS pole.
  Uvw
3-D u-v-w (UVW) components.
  Uvw3Tuple
3-Tuple (u, v, w), in meter.
  Vector2Tuple
2-Tuple (x, y) of (geocentric) components, each in meter or the same units.
  Vector3Tuple
3-Tuple (x, y, z) of (geocentric) components, all in meter or the same units.
  Vector3d
Extended 3-D vector.
  Vector4Tuple
4-Tuple (x, y, z, h) of (geocentric) components, all in meter or the same units.
  VectorError
Vector3d, Cartesian* or *Nvector issues.
  VincentyError
Error raised by Vincenty's Direct and Inverse methods for coincident points or lack of convergence.
  WGRSError
World Geographic Reference System (WGRS) encode, decode or other Georef issue.
  WebMercatorError
Web Mercator (WM) parser or Wm issue.
  Wm
Web Mercator (WM) coordinate.
  XDict
4+Item result from Intersectool and Intersector methods All, Closest, Next and Segment with the intersection offsets sA, sB and sX0 in meter and the coincidence indicator c, an int, +1 for parallel, -1 for anti-parallel or 0 otherwise.
  XDist
DEPRECATED on 2024.07.02, use class XDict.
  Xyz4Tuple
4-Tuple (x, y, z, ltp), all in meter except ltp.
  XyzLocal
Local (x, y, z) in a local tangent plane (LTP), also base class for local Enu.
  Zone
Named int representing a UTM/UPS zone number.
  a_f2Tuple
2-Tuple (a, f) specifying an ellipsoid by equatorial radius a in meter and scalar flattening f.
  property_RO
  property_ROnce
  property_ROver
Functions
 
EcefCartesian(*args, **kwds)
DEPRECATED, use class LocalCartesian.
 
Fn_rt(root, *xs, **name_RESIDUAL_raiser)
DEPRECATED on 2024.04.17, use class Froot.
 
FrechetCosineAndoyerLambert(point1s, **kwds)
DEPRECATED on 2024.12.31, use class FrechetCosineLaw with corr=1.
 
FrechetCosineForsytheAndoyerLambert(point1s, **kwds)
DEPRECATED on 2024.12.31, use class FrechetCosineLaw with corr=2.
 
Fsum2product(*xs, **kwds)
DEPRECATED on 2024.09.19, use Fsum(*xs, f2product=True, ...).
 
Geodesic_WGS84()
Get the wrapped Geodesic(WGS84) singleton, provided geographiclib is installed, otherwise an ImportError.
 
HausdorffCosineAndoyerLambert(point1s, **kwds)
DEPRECATED on 2024.12.31, use class HausdorffCosineLaw with corr=1.
 
HausdorffCosineForsytheAndoyerLambert(point1s, **kwds)
DEPRECATED on 2024.12.31, use class HausdorffCosineLaw with corr=2.
 
HeightIDW(knots, **kwds)
DEPRECATED, use class HeightIDWeuclidean.
 
HeightIDW2(knots, **kwds)
DEPRECATED, use class HeightIDWequirectangular.
 
HeightIDW3(knots, **kwds)
DEPRECATED, use class HeightIDWhaversine.
 
HeightIDWcosineAndoyerLambert(knots, **kwds)
DEPRECATED on 2024.12.31, use class HeightIDWcosineLaw with corr=1.
 
HeightIDWcosineForsytheAndoyerLambert(knots, **kwds)
DEPRECATED on 2024.12.31, use class HeightIDWcosineLaw with corr=2.
 
NM2m(nm)
Convert nautical miles to meter (m).
 
RefFrameError(*args, **kwds)
DEPRECATED, use class TRFError.
 
SM2m(sm)
Convert statute miles to meter (m).
 
SinCos2(x)
Get sin and cos of typed angle.
 
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.
 
a_b2e(a, b)
Return e, the 1st eccentricity for a given equatorial and polar radius.
 
a_b2e2(a, b)
Return e2, the 1st eccentricity squared for a given equatorial and polar radius.
 
a_b2e22(a, b)
Return e22, the 2nd eccentricity squared for a given equatorial and polar radius.
 
a_b2e32(a, b)
Return e32, the 3rd eccentricity squared for a given equatorial and polar radius.
 
a_b2f(a, b)
Return f, the flattening for a given equatorial and polar radius.
 
a_b2f2(a, b)
Return f2, the 2nd flattening for a given equatorial and polar radius.
 
a_b2f_(a, b)
Return f_, the inverse flattening for a given equatorial and polar radius.
 
a_b2n(a, b)
Return n, the 3rd flattening for a given equatorial and polar radius.
 
a_f2b(a, f)
Return b, the polar radius for a given equatorial radius and flattening.
 
a_f_2b(a, f_)
Return b, the polar radius for a given equatorial radius and inverse flattening.
 
acos1(x)
Return math.acos(max(-1, min(1, x))).
 
acre2ha(acres)
Convert acres to hectare.
 
acre2m2(acres)
Convert acres to square meter.
 
anStr(name, OKd='._-', sub='_')
DEPRECATED, use function pygeodesy.anstr.
 
angle2chord(rad, radius=6371008.771415)
Get the chord length of a (central) angle or angular distance.
 
anstr(name, OKd='._-', sub='_')
Make a valid name of alphanumeric and OKd characters.
 
antipode(lat, lon, **name)
Return the antipode, the point diametrically opposite to a given point in degrees.
 
antipode_(phi, lam, **name)
Return the antipode, the point diametrically opposite to a given point in radians.
 
areaOf(points, adjust=True, radius=6371008.771415, wrap=True)
Approximate the area of a polygon or composite.
 
areaof(points, adjust=True, radius=6371008.771415, wrap=True)
DEPRECATED, use function pygeodesy.areaOf.
 
asin1(x)
Return math.asin(max(-1, min(1, x))).
 
atan1(y, x=1.0)
Return atan(y / x) angle in radians [-PI/2..+PI/2] using atan2 for consistency and to avoid ZeroDivisionError.
 
atan1d(y, x=1.0)
Return atan(y / x) angle in degrees [-90..+90] using atan2d for consistency and to avoid ZeroDivisionError.
 
atan2(y, x)
Return the arc tangent (measured in radians) of y/x.
 
atan2b(y, x)
Return atan2(y, x) in degrees [0..+360], counter-clockwise.
 
atan2d(y, x, reverse=False)
Return atan2(y, x) in degrees [-180..+180], optionally reversed (by 180 degrees for azimuths).
 
atand(x)
DEPRECATED on 2023.09.28, use function pygeodesy.atan1d.
 
attrs(inst, *names, **Nones_True__pairs_kwds)
Get instance attributes as name=value strings, with floats formatted by function fstr.
 
b_f2a(b, f)
Return a, the equatorial radius for a given polar radius and flattening.
 
b_f_2a(b, f_)
Return a, the equatorial radius for a given polar radius and inverse flattening.
 
bearing(lat1, lon1, lat2, lon2, **final_wrap)
Compute the initial or final bearing (forward or reverse azimuth) between two (spherical) points.
 
bearingDMS(bearing, form='d', prec=None, sep='', **s_D_M_S)
Convert bearing to a string (without compass point suffix).
 
bearing_(phi1, lam1, phi2, lam2, final=False, wrap=False)
Compute the initial or final bearing (forward or reverse azimuth) between two (spherical) points.
 
bounds(geohash, LatLon=None, **LatLon_kwds)
Returns the lower-left SW and upper-right NE corners of a geohash.
 
boundsOf(points, wrap=False, LatLon=None)
Determine the bottom-left SW and top-right NE corners of a path or polygon.
 
bqrt(x)
Return the 4-th, bi-quadratic or quartic root, x**(1 / 4), preserving type(x).
 
callername(up=1, dflt='', source=False, underOK=False)
Get the name of the invoking callable.
 
cassini(pointA, pointB, pointC, alpha, beta, useZ=False, **Clas_and_kwds)
3-Point resection using Cassini's method.
 
cbrt(x)
Compute the cube root x**(1/3), preserving type(x).
 
cbrt2(x)
Compute the cube root squared x**(2/3), preserving type(x).
 
centroidOf(points, wrap=False, LatLon=None)
Determine the centroid of a polygon.
 
chain2m(chains)
Convert UK chains to meter.
 
chord2angle(chord, radius=6371008.771415)
Get the (central) angle from a chord length or distance.
 
circin6(point1, point2, point3, eps=8.881784197001252e-16, useZ=True)
Return the radius and center of the inscribed aka Incircle of a (2- or 3-D) triangle.
 
circle4(earth, lat)
Get the equatorial or a parallel circle of latitude.
 
circum3(point1, point2, point3, circum=True, eps=8.881784197001252e-16, useZ=True)
Return the radius and center of the smallest circle through or containing three (2- or 3-D) points.
 
circum4(points, useZ=True, **Vector_and_kwds)
Best-fit a sphere through three or more (3-D) points.
 
circum4_(*points, **useZ_Vector_and_kwds)
Best-fit a sphere through three or more (3-D) positional points.
 
classname(inst, prefixed=None)
Return the instance' class name optionally prefixed with the module name.
 
classnaming(prefixed=None)
Get/set the default class naming for [module.]class names.
 
clipCS3(points, lowerleft, upperright, closed=False, inull=False)
DEPRECATED, use function pygeodesy.clipCS4.
 
clipCS4(points, lowerleft, upperight, closed=False, inull=False)
Clip a path against a rectangular clip box using the Cohen-Sutherland algorithm.
 
clipDMS(deg, limit)
DEPRECATED, use function pygeodesy.clipDegrees.
 
clipDegrees(deg, limit)
Clip a lat- or longitude to the given range.
 
clipFHP4(points, corners, closed=False, inull=False, raiser=False, eps=2.220446049250313e-16)
Clip one or more polygons against a clip region or box using Forster-Hormann-Popa's C++ implementation transcoded to pure Python.
 
clipGH4(points, corners, closed=False, inull=False, raiser=True, xtend=False, eps=2.220446049250313e-16)
Clip one or more polygons against a clip region or box using the Greiner-Hormann algorithm, Correia's implementation modified and extended.
 
clipLB6(points, lowerleft, upperight, closed=False, inull=False)
Clip a path against a rectangular clip box using the Liang-Barsky algorithm.
 
clipRadians(rad, limit)
Clip a lat- or longitude to the given range.
 
clipSH(points, corners, closed=False, inull=False)
Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm.
 
clipSH3(points, corners, closed=False, inull=False)
Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm.
 
clipStr(bstr, limit=50, white='')
DEPRECATED, use function pygeodesy.clips.
 
clips(sb, limit=50, white='', length=False)
Clip a string to the given length limit.
 
collins(pointA, pointB, pointC, alpha, beta, **useZ_Clas_and_kwds)
DEPRECATED, use function pygeodesy.collins5.
 
collins5(pointA, pointB, pointC, alpha, beta, useZ=False, **Clas_and_kwds)
3-Point resection using Collins' method.
 
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='', **s_D_M_S)
Convert bearing to a string suffixed with compass point.
 
compassPoint(bearing, prec=3)
Convert a bearing from North to a compass point.
 
copysign(x, y)
DEPRECATED, use function pygeodesy.copysign0.
 
copysign0(x, y)
Like math.copysign(x, y) except zero, unsigned.
 
copytype(x, y)
Return the value of x as type of y.
 
cosineAndoyerLambert(lat1, lon1, lat2, lon2, **datum_wrap)
DEPRECATED on 2024.12.31, use function pygeodesy.cosineLaw with corr=1.
 
cosineAndoyerLambert_(phi2, phi1, lam21, **datum)
DEPRECATED on 2024.12.31, use function pygeodesy.cosineLaw_ with corr=1.
 
cosineForsytheAndoyerLambert(lat1, lon1, lat2, lon2, **datum_wrap)
DEPRECATED on 2024.12.31, use function pygeodesy.cosineLaw with corr=2.
 
cosineForsytheAndoyerLambert_(phi2, phi1, lam21, **datum)
DEPRECATED on 2024.12.31, use function pygeodesy.cosineLaw_ with corr=2.
 
cosineLaw(lat1, lon1, lat2, lon2, corr=0, earth=None, wrap=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., radius=6371008.771415)
Compute the distance between two points using the Law of Cosines formula, optionally corrected.
 
cosineLaw_(phi2, phi1, lam21, corr=0, earth=None, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)
Compute the angular distance between two points using the Law of Cosines formula, optionally corrected.
 
cot(rad, **raiser_kwds)
Return the cotangent of an angle in radians.
 
cot_(*rads, **raiser_kwds)
Yield the cotangent of angle(s) in radians.
 
cotd(deg, **raiser_kwds)
Return the cotangent of an angle in degrees.
 
cotd_(*degs, **raiser_kwds)
Yield the cotangent of angle(s) in degrees.
 
crosserrors(raiser=None)
Report or ignore vectorial cross product errors.
 
date2epoch(year, month, day)
Return the epoch for a calendar day.
 
decodeEPSG2(arg)
DEPRECATED, use function epsg.decode2.
 
degDMS(deg, prec=6, s_D='°', s_M='\xe2\x80\xb2', 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).
 
degrees2grades(deg)
Convert degrees to grades (aka gons or gradians).
 
degrees2m(deg, radius=6371008.771415, lat=0)
Convert an angle to a distance along the equator or along a parallel at (geodetic) latitude.
 
degrees360(rad)
Convert radians to degrees and wrap [0..+360).
 
degrees90(rad)
Convert radians to degrees and wrap [-90..+90).
 
deprecated_Property_RO(method)
Decorator for a DEPRECATED Property_RO.
 
deprecated_class(cls_or_class)
Use inside __new__ or __init__ of a DEPRECATED class.
 
deprecated_function(call)
Decorator for a DEPRECATED function.
 
deprecated_method(call)
Decorator for a DEPRECATED method.
 
deprecated_property_RO(method)
Decorator for a DEPRECATED property_RO.
 
e22f(e2)
Return f, the flattening for a given 1st eccentricity squared.
 
e2f(e)
Return f, the flattening for a given 1st eccentricity.
 
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)
DEPRECATED, use function pygeodesy.enstr2.
 
encodeEPSG(zone, hemipole='', band='')
DEPRECATED, use function epsg.encode.
 
enstr2(easting, northing, prec, *extras, **wide_dot)
Return an MGRS/OSGR easting, northing string representations.
 
epoch2date(epoch)
Return the date for a reference frame epoch.
 
equidistant(lat0, lon0, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., exact=False, geodsolve=False, **name)
Return an EquidistantExact, EquidistantGeodSolve or (if Karney's geographiclib package is installed) an EquidistantKarney, otherwise an Equidistant instance.
 
equirectangular(lat1, lon1, lat2, lon2, radius=6371008.771415, **adjust_limit_wrap)
Approximate the distance between two points using the Equirectangular Approximation / Projection.
 
equirectangular3(lat1, lon1, lat2, lon2, **options)
DEPRECATED, use function pygeodesy.equirectangular4.
 
equirectangular4(geohash1, geohash2, radius=6371008.771415)
Approximate the distance between two geohashes using the pygeodesy.equirectangular formula.
 
equirectangular_(lat1, lon1, lat2, lon2, **options)
DEPRECATED on 2024.05.25, use function pygeodesy.equirectangular4.
 
euclid(x, y)
Appoximate the norm sqrt(x**2 + y**2) by max(abs(x), abs(y)) + min(abs(x), abs(y)) * 0.4142....
 
euclid_(*xs)
Appoximate the norm sqrt(sum(x**2 for x in xs)) by cascaded euclid.
 
euclidean(lat1, lon1, lat2, lon2, radius=6371008.771415, adjust=True, wrap=False)
Approximate the Euclidean distance between two (spherical) points.
 
euclidean_(geohash1, geohash2, **radius_adjust_wrap)
Approximate the distance between two geohashes using the pygeodesy.euclidean formula.
 
exception_chaining(exc=None)
Get an error's cause or the exception chaining setting.
 
excessAbc(A, b, c)
DEPRECATED on 2023.04.04, use function pygeodesy.excessAbc_.
 
excessAbc_(A, b, c)
Compute the spherical excess E of a (spherical) triangle from two sides and the included (small) angle.
 
excessCagnoli_(a, b, c)
Compute the spherical excess E of a (spherical) triangle using Cagnoli's (D.34) formula.
 
excessGirard(A, B, C)
DEPRECATED on 2023.04.04, use function pygeodesy.excessGirard_.
 
excessGirard_(A, B, C)
Compute the spherical excess E of a (spherical) triangle using Girard's formula.
 
excessKarney(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)
Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method.
 
excessKarney_(phi2, phi1, lam21)
Compute the spherical excess E of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method.
 
excessLHuilier(a, b, c)
DEPRECATED on 2023.04.04, use function pygeodesy.excessLHuilier_.
 
excessLHuilier_(a, b, c)
Compute the spherical excess E of a (spherical) triangle using L'Huilier's's Theorem.
 
excessQuad(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)
Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator.
 
excessQuad_(phi2, phi1, lam21)
Compute the spherical excess E of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator.
 
f2e2(f)
Return e2, the 1st eccentricity squared for a given flattening.
 
f2e22(f)
Return e22, the 2nd eccentricity squared for a given flattening.
 
f2e32(f)
Return e32, the 3rd eccentricity squared for a given flattening.
 
f2f2(f)
Return f2, the 2nd flattening for a given flattening.
 
f2f_(f)
Return f_, the inverse flattening for a given flattening.
 
f2mul_(x, *ys, **nonfinites)
Cascaded, accurate multiplication x * y * y ... for all ys.
 
f2n(f)
Return n, the 3rd flattening for a given flattening.
 
f2product(two=None)
Turn accurate TwoProduct multiplication on or off.
 
fStr(floats, prec=6, fmt='f', ints=False, sep=', ')
DEPRECATED, use function fstr.
 
fStrzs(floatstr)
DEPRECATED, use function pygeodesy.fstrzs.
 
f_2f(f_)
Return f, the flattening for a given inverse flattening.
 
facos1(x)
Fast approximation of pygeodesy.acos1(x), scalar.
 
false2f(value, name='value', false=True, Error=<type 'exceptions.ValueError'>)
DEPRECATED, use class Easting or Northing.
 
falsed2f(falsed=True, Error=<type 'exceptions.ValueError'>, **name_value)
DEPRECATED, use class Easting or Northing.
 
fasin1(x)
Fast approximation of pygeodesy.asin1(x), scalar.
 
fatan(x)
Fast approximation of atan(x), scalar.
 
fatan1(x)
Fast approximation of atan(x) for 0 <= x < 1, unchecked.
 
fatan2(y, x)
Fast approximation of atan2(y, x), scalar.
 
fathom2m(fathoms)
Convert Imperial fathom to meter.
 
favg(a, b, f=0.5, nonfinites=True)
Return the precise average of two values.
 
fdot(xs, *ys, **start_f2product_nonfinites)
Return the precision dot product sum(xs[i] * ys[i] for i in range(len(xs))).
 
fdot3(xs, ys, zs, **start_f2product_nonfinites)
Return the (precision) dot product start + sum(xs[i] * ys[i] * zs[i] for i in range(len(xs))).
 
fdot_(*xys, **start_f2product_nonfinites)
Return the (precision) dot product sum(xys[i] * xys[i+1] for i in range(0, len(xys), 2)).
 
fhorner(x, *cs, **incx)
Horner form evaluation of polynomial sum(cs[i] * x**i for i=0..n) as in- or decreasing exponent sum(... i=n..0), where n = len(cs) - 1.
 
fidw(xs, ds, beta=2)
Interpolate using Inverse Distance Weighting (IDW).
 
flatLocal(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True, wrap=False)
Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.
 
flatLocal_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True)
Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.
 
flatPolar(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)
Compute the distance between two (spherical) points using the polar coordinate flat-Earth formula.
 
flatPolar_(phi2, phi1, lam21)
Compute the angular distance between two (spherical) points using the polar coordinate flat-Earth formula.
 
float0(*xs)
DEPRECATED on 2023.04.21, use function pygeodesy.float0_.
 
float0_(*xs)
Yield xs as a non-NEG0 float.
 
float_(*fs, **sets)
Get scalars as float or intern'ed float.
 
fma(x, y, z, **nonfinites)
Fused-multiply-add, using math.fma(x, y, z) in Python 3.13+ or an equivalent implementation.
 
fmean(xs)
Compute the accurate mean sum(xs) / len(xs).
 
fmean_(*xs, **nonfinites)
Compute the accurate mean sum(xs) / len(xs).
 
fpolynomial(x, *cs, **over_f2product_nonfinites)
Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)) [/ over].
 
fpowers(x, n, alts=0)
Return a series of powers [x**i for i=1..n], note 1..!
 
fprod(xs, start=1)
Iterable product, like math.prod or numpy.prod.
 
fractional(points, fi, j=None, wrap=None, LatLon=None, Vector=None, **kwds)
Return the point at a given fractional index.
 
frandoms(n, seeded=None)
Generate n (long) lists of random floats.
 
frange(start, number, step=1)
Generate a range of floats.
 
frechet_(point1s, point2s, distance=None, units='')
Compute the discrete Fréchet distance between two paths, each given as a set 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.
 
fremainder(x, y)
Remainder in range [-y / 2, y / 2].
 
fstr(floats, prec=6, fmt='F', ints=False, sep=', ', strepr=None, force=True)
Convert one or more floats to string, optionally stripped of trailing zero decimals.
 
fstrzs(efstr, ap1z=False)
Strip trailing zero decimals from a float string.
 
fsum(xs, nonfinites=None, **floats)
Precision floating point summation from Python's math.fsum.
 
fsum1(xs, **nonfinites)
Precision floating point summation, 1-primed.
 
fsum1_(*xs, **nonfinites)
Precision floating point summation of all positional items, 1-primed.
 
fsum1f_(*xs)
Precision floating point summation of all positional items, 1-primed and with non-finites OK.
 
fsum_(*xs, **nonfinites)
Precision floating point summation of all positional items.
 
fsumf_(*xs)
Precision floating point summation of all positional items with non-finites OK.
 
ft2m(feet, usurvey=False, pied=False, fuss=False)
Convert International, US Survey, French or German feet to meter.
 
furlong2m(furlongs)
Convert a furlong to meter.
 
geoidHeight2(lat, lon, model=0, timeout=2.0)
Get the NAVD88 geoid height at an NAD83 location.
 
gnomonic(lat0, lon0, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., exact=False, geodsolve=False, **name)
Return a GnomonicExact or (if Karney's geographiclib package is installed) a GnomonicKarney, otherwise a Gnomonic instance.
 
grades(rad)
Convert radians to grades (aka gons or gradians).
 
grades2degrees(gon)
Convert grades (aka gons or gradians) to degrees.
 
grades2radians(gon)
Convert grades (aka gons or gradians) to radians.
 
grades400(rad)
Convert radians to grades (aka gons or gradians) and wrap [0..+400).
 
ha2acre(ha)
Convert hectare to acre.
 
ha2m2(ha)
Convert hectare to square meter.
 
halfs2(str2)
Split a string in 2 halfs.
 
hartzell(pov, los=False, earth=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., **name_LatLon_and_kwds)
Compute the intersection of the earth's surface and a Line-Of-Sight from a Point-Of-View in space.
 
hartzell4(pov, los=False, tri_biax=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., **name)
Compute the intersection of a tri-/biaxial ellipsoid and a Line-Of-Sight from a Point-Of-View outside.
 
hausdorff_(model, target, both=False, early=True, seed=None, units='', distance=None, point=<function _point at 0x7f7af8a96e50>)
Compute the directed or symmetric Hausdorff distance between 2 sets of points with or without early breaking and random sampling.
 
hav(rad)
Return the haversine of an angle.
 
haversine(lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)
Compute the distance between two (spherical) points using the Haversine formula.
 
haversine_(geohash1, geohash2, **radius_wrap)
Compute the great-circle distance between two geohashes using the pygeodesy.haversine formula.
 
heightOf(angle, distance, radius=6371008.771415)
Determine the height above the (spherical) earth' surface after traveling along a straight line at a given tilt.
 
heightOrthometric(h_loc, N)
Get the orthometric height H, the height above the geoid, earth surface.
 
horizon(height, radius=6371008.771415, refraction=False)
Determine the distance to the horizon from a given altitude above the (spherical) earth.
 
hstr(height, prec=2, fmt='%+.*f', ints=False, m='')
Return a string for the height value.
 
hubeny(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True, wrap=False)
Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.
 
hubeny_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True)
Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.
 
hypot(x, y)
Return the Euclidean distance, sqrt(x*x + y*y).
 
hypot1(x)
Compute the norm sqrt(1 + x**2).
 
hypot2(x, y)
Compute the squared norm x**2 + y**2.
 
hypot2_(*xs)
Compute the squared norm fsum(x**2 for x in xs).
 
hypot3(x, y, z)
DEPRECATED, use function pygeodesy.hypot_.
 
hypot_(*xs)
Compute the norm sqrt(sum(x**2 for x in xs)).
 
inStr(inst, *args, **kwds)
DEPRECATED, use function pygeodesy.instr.
 
instr(inst, *args, **kwds)
Return the string representation of an instantiation.
 
int1s(x)
Count the number of 1-bits in an int, unsigned.
 
intersection2(lat1, lon1, bearing1, lat2, lon2, bearing2, datum=None, wrap=False, small=100000.0)
Conveniently compute the intersection of two lines each defined by a (geodetic) point and a bearing from North, using either ...
 
intersection3d3(start1, end1, start2, end2, eps=2.220446049250313e-16, useZ=True, **Vector_and_kwds)
Compute the intersection point of two (2- or 3-D) lines, each defined by two points or by a point and a bearing.
 
intersections2(center1, radius1, center2, radius2, sphere=True, **Vector_and_kwds)
Compute the intersection of two spheres or circles, each defined by a (3-D) center point and a radius.
 
isBoolean(obj)
Check for Boolean composites.
 
isCartesian(obj, ellipsoidal=None)
Is object some Cartesian?
 
isDEPRECATED(obj)
Is object a DEPRECATED class, method or function?
 
isError(exc)
Check a (caught) exception.
 
isLatLon(obj, ellipsoidal=None)
Is object some LatLon?
 
isNumpy2(obj)
Check for a Numpy2LatLon points wrapper.
 
isNvector(obj, ellipsoidal=None)
Is object some Nvector?
 
isPoints2(obj)
Check for a LatLon2psxy points wrapper.
 
isTuple2(obj)
Check for a Tuple2LatLon points wrapper.
 
isantipode(lat1, lon1, lat2, lon2, eps=2.220446049250313e-16)
Check whether two points are antipodal, on diametrically opposite sides of the earth.
 
isantipode_(phi1, lam1, phi2, lam2, eps=2.220446049250313e-16)
Check whether two points are antipodal, on diametrically opposite sides of the earth.
 
isbool(obj)
Is object a boolean?
 
isclass(obj)
Is object a Class or type?
 
isclockwise(points, adjust=False, wrap=True)
Determine the direction of a path or polygon.
 
isclose(a, b, rel_tol=1e-12, abs_tol=4.930380657631324e-32)
Like math.isclose, but with defaults such that isclose(0, EPS0) is True by default.
 
iscolinearWith(point, point1, point2, eps=2.220446049250313e-16, useZ=True)
Check whether a point is colinear with two other (2- or 3-D) points.
 
iscomplex(obj, both=False)
Is object a complex or complex literal str?
 
isconvex(points, adjust=False, wrap=False)
Determine whether a polygon is convex.
 
isconvex_(points, adjust=False, wrap=False)
Determine whether a polygon is convex and clockwise.
 
isenclosedBy(point, points, wrap=False)
Determine whether a point is enclosed by a polygon or composite.
 
isenclosedby(point, points, wrap=False)
DEPRECATED, use function pygeodesy.isenclosedBy.
 
isfinite(obj)
Check a finite scalar, complex, ...
 
isfloat(obj, both=False)
Is object a float or float literal str?
 
isidentifier(obj)
Is object a Python identifier?
bool
isinf(x)
Check if float x is infinite (positive or negative).
 
isinstanceof(obj, *Classes)
Is object an instance of one of the Classes?
 
isint(obj, both=False)
Is object an int or integer float value?
 
isint0(obj, both=False)
Check for INT0 or int(0) value.
 
isiterable(obj, strict=False)
Is object iterable?
 
isiterablen(obj, strict=False)
Is object iterable and has length?
 
isiterabletype(obj, method='__iter__')
Is object an instance of an iterable class or type?
 
iskeyword(x, y)
y in x.
 
islistuple(obj, minum=0)
Is object a list or tuple with non-zero length?
bool
isnan(x)
Check if float x is not a number (NaN).
 
isnear0(x, eps0=4.930380657631324e-32)
Is x near zero within a tolerance?
 
isnear1(x, eps1=4.930380657631324e-32)
Is x near one within a tolerance?
 
isnear90(x, eps90=4.930380657631324e-32)
Is x near 90 within a tolerance?
 
isneg0(x)
Check for NEG0, negative 0.0.
 
isninf(x)
Check for NINF, negative INF.
 
isnon0(x, eps0=4.930380657631324e-32)
Is x non-zero with a tolerance?
 
isnormal(lat, lon, eps=0)
Check whether lat and lon are within their respective normal range in degrees.
 
isnormal_(phi, lam, eps=0)
Check whether phi and lam are within their respective normal range in radians.
 
isodd(x)
Is x odd?
 
ispolar(points, wrap=False)
Check whether a polygon encloses a pole.
 
isscalar(obj, both=False)
Is object an int or integer float value?
 
issequence(obj, *excls)
Is object some sequence type?
 
isstr(obj)
Is object some string type?
 
issubclassof(Sub, *Supers)
Is Sub a class and sub-class of some other class(es)?
 
istuplist(obj, minum=0)
DEPRECATED on 2023.03.31, use function pygeodesy.islistuple.
 
itemsorted(adict, *items_args, **asorted_reverse)
Return the items of adict sorted alphabetically, case-insensitively and in ascending order.
 
iterNumpy2(obj)
Iterate over Numpy2 wrappers or other sequences exceeding the threshold.
 
iterNumpy2over(n=None)
Get or set the iterNumpy2 threshold.
 
joined(*words, **sep)
DEPRECATED, use NN(...), NN.join_ or sep.join.
 
joined_(*words, **sep)
DEPRECATED, use _SPACE_(...), _SPACE_.join_ or sep.join, sep=" ".
 
km2m(km)
Convert kilo meter to meter (m).
 
latDMS(deg, form='dms', prec=None, sep='', **s_D_M_S)
Convert latitude to a string, optionally suffixed with N or S.
 
latlon2n_xyz(lat_ll, lon=None, **name)
Convert lat-, longitude to n-vector (normal to the earth's surface) X, Y and Z components.
 
latlonDMS(lls, **m_form_prec_sep_s_D_M_S)
Convert one or more LatLon instances to strings.
 
latlonDMS_(*lls, **m_form_prec_sep_s_D_M_S)
Convert one or more LatLon instances to strings.
 
len2(items)
Make built-in function len work for generators, iterators, etc.
 
limiterrors(raiser=None)
Get/set the throwing of LimitErrors.
 
lonDMS(deg, form='dms', prec=None, sep='', **s_D_M_S)
Convert longitude to a string, optionally suffixed with E or W.
 
lrstrip(txt, lrpairs={'(': ')', '<': '>', '[': ']', '{': '}'})
Left- and right-strip parentheses, brackets, etc.
 
luneOf(lon1, lon2, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds)
Generate an ellipsoidal or spherical lune-shaped path or polygon.
 
m2NM(meter)
Convert meter to nautical miles (NM).
 
m2SM(meter)
Convert meter to statute miles (SM).
 
m2acre(meter2)
Convert square meter to acres.
 
m2chain(meter)
Convert meter to UK chains.
 
m2degrees(distance, radius=6371008.771415, lat=0)
Convert a distance to an angle along the equator or along a parallel at (geodetic) latitude.
 
m2fathom(meter)
Convert meter to Imperial fathoms.
 
m2ft(meter, usurvey=False, pied=False, fuss=False)
Convert meter to International, US Survey, French or or German feet (ft).
 
m2furlong(meter)
Convert meter to furlongs.
 
m2ha(meter2)
Convert square meter to hectare.
 
m2km(meter)
Convert meter to kilo meter (Km).
 
m2radians(distance, radius=6371008.771415, lat=0)
Convert a distance to an angle along the equator or along a parallel at (geodetic) latitude.
 
m2toise(meter)
Convert meter to French toises.
 
m2yard(meter)
Convert meter to UK yards.
 
machine()
Return standard platform.machine, but distinguishing Intel native from Intel emulation on Apple Silicon (on macOS only).
 
map1(fun1, *xs)
Call a single-argument function to each xs and return a tuple of results.
 
map2(fun, *xs, **strict)
Like Python's map but returning a tuple of results.
 
max2(*xs)
Return 2-tuple (max(xs), xs.index(max(xs))).
 
meeus2(point1, point2, point3, circum=False, useZ=True)
Return the radius and Meeus' Type of the smallest circle through or containing three (2- or 3-D) points.
 
min2(*xs)
Return 2-tuple (min(xs), xs.index(min(xs))).
 
modulename(clas, prefixed=None)
Return the class name optionally prefixed with the module name.
 
n2e2(n)
Return e2, the 1st eccentricity squared for a given 3rd flattening.
 
n2f(n)
Return f, the flattening for a given 3rd flattening.
 
n2f_(n)
Return f_, the inverse flattening for a given 3rd flattening.
 
n_xyz2latlon(x_xyz, y=0, z=0, **name)
Convert n-vector to (geodetic) lat- and longitude in degrees.
 
n_xyz2philam(x_xyz, y=0, z=0, **name)
Convert n-vector to (geodetic) lat- and longitude in radians.
 
nameof(inst)
Get the name of an instance.
 
nearestOn(point, point1, point2, within=True, useZ=True, Vector=None, **Vector_kwds)
Locate the point between two points closest to a reference (2- or 3-D).
 
nearestOn3(point, points, closed=False, wrap=False, **options)
DEPRECATED, use function pygeodesy.nearestOn5.
 
nearestOn4(point, points, closed=False, wrap=False, **options)
DEPRECATED, use function pygeodesy.nearestOn5.
 
nearestOn5(point, points, closed=False, wrap=False, adjust=True, limit=9, **LatLon_and_kwds)
Locate the point on a path or polygon closest to a reference point.
 
nearestOn6(point, points, closed=False, useZ=True, **Vector_and_kwds)
Locate the point on a path or polygon closest to a reference point.
 
neg(x, neg0=None)
Negate x and optionally, negate 0.0 and -0.0.
 
neg_(*xs)
Negate all xs with neg.
 
nonfiniterrors(raiser=None)
Throw OverflowError and ValueError exceptions for or handle non-finite floats as inf, INF, NINF, nan and NAN in summations and multiplications.
 
norm2(x, y)
Normalize a 2-dimensional vector.
 
normDMS(strDMS, norm=None, **s_D_M_S)
Normalize all degrees, minutes and seconds (DMS) symbol suffixes in a string to the default symbols S_DEG, S_MIN, S_SEC.
 
norm_(*xs)
Normalize the components of an n-dimensional vector.
 
normal(lat, lon, **name)
Normalize a lat- and longitude pair in degrees.
 
normal_(phi, lam, **name)
Normalize a lat- and longitude pair in radians.
 
notImplemented(inst, *args, **kwds)
Raise a NotImplementedError for a missing instance method or property or for a missing caller feature.
 
notOverloaded(inst, *args, **kwds)
Raise an AssertionError for a method or property not overloaded.
 
opposing(bearing1, bearing2, margin=90.0)
Compare the direction of two bearings given in degrees.
 
opposing_(radians1, radians2, margin=1.5707963267948966)
Compare the direction of two bearings given in radians.
 
pairs(items, prec=6, fmt='F', ints=False, sep='=')
Convert items to name=value strings, with floats handled like fstr.
 
parse3d(str3d, sep=',', Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds)
Parse an "x, y, z" string.
 
parse3llh(strllh, height=0, sep=',', clipLat=90, clipLon=180, wrap=False, **s_D_M_S)
Parse a string "lat, lon [, h]" representing lat-, longitude in degrees and optional height in meter.
 
parseDDDMMSS(strDDDMMSS, suffix='NSEW', sep='', clip=0, sexagecimal=False)
Parse a lat- or longitude represention forms as [D]DDMMSS in degrees.
 
parseDMS(strDMS, suffix='NSEW', sep='', clip=0, **s_D_M_S)
Parse a lat- or longitude representation in degrees.
 
parseDMS2(strLat, strLon, sep='', clipLat=90, clipLon=180, wrap=False, **s_D_M_S)
Parse a lat- and a longitude representions "lat, lon" in degrees.
 
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 "[zone]Band, EN, easting, northing".
 
parseOSGR(strOSGR, Osgr=<class 'pygeodesy.osgr.Osgr'>, **name_Osgr_kwds)
Parse a string representing an OS Grid Reference, consisting of "[GD] easting northing".
 
parseRad(strRad, suffix='NSEW', clip=0)
Parse a string representing angle in radians.
 
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=_UTM, Utm=_UTM, 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 "e n [r]" representing a WM coordinate, consisting of easting, northing and an optional radius.
 
perimeterOf(points, closed=False, adjust=True, radius=6371008.771415, wrap=True)
Approximate the perimeter of a path, polygon.
 
perimeterof(points, closed=False, adjust=True, radius=6371008.771415, wrap=True)
DEPRECATED, use function pygeodesy.perimeterOf.
 
philam2n_xyz(phi_ll, lam=None, **name)
Convert lat-, longitude to n-vector (normal to the earth's surface) X, Y and Z components.
 
pierlot(point1, point2, point3, alpha12, alpha23, useZ=False, eps=2.220446049250313e-16, **Clas_and_kwds)
3-Point resection using Pierlot's method ToTal with approximate limits for the (pseudo-)singularities.
 
pierlotx(point1, point2, point3, alpha1, alpha2, alpha3, useZ=False, **Clas_and_kwds)
3-Point resection using Pierlot's method ToTal with exact limits for the (pseudo-)singularities.
 
points2(points, closed=True, base=None, Error=<class 'pygeodesy.errors.PointsError'>)
Check a path or polygon represented by points.
 
polygon(points, closed=True, base=None)
DEPRECATED, use function pygeodesy.points2.
 
precision(res)
Determine the Georef precision to meet a required (geographic) resolution.
 
print_(*args, **nl_nt_prec_prefix__end_file_flush_sep__kwds)
Python 3+ print-like formatting and printing.
 
printf(fmt, *args, **nl_nt_prec_prefix__end_file_flush_sep__kwds)
Printf-style and Python 3+ print-like formatting and printing.
 
property_doc_(doc)
Decorator for a standard property with basic documentation.
 
quadOf(latS, lonW, latN, lonE, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds)
Generate a quadrilateral path or polygon from two points.
 
radians(x)
Convert angle x from degrees to radians.
 
radians2m(rad, radius=6371008.771415, lat=0)
Convert an angle to a distance along the equator or along a parallel at (geodetic) latitude.
 
radiansPI(deg)
Convert and wrap degrees to radians [-PI..+PI].
 
radiansPI2(deg)
Convert and wrap degrees to radians [0..+2PI).
 
radiansPI_2(deg)
Convert and wrap degrees to radians [-3PI/2..+PI/2].
 
radical2(distance, radius1, radius2, **name)
Compute the radical ratio and radical line of two intersecting circles.
 
radii11(point1, point2, point3, useZ=True)
Return the radii of the In-, Soddy and Tangent circles of a (2- or 3-D) triangle.
 
randomrangenerator(seed)
Return a seeded random range function generator.
 
rangerrors(raiser=None)
Get/set the throwing of RangeErrors.
 
remainder(x, y)
Mimick Python 3.7+ math.remainder.
 
reprs(objs, prec=6, fmt='F', ints=False)
Convert objects to repr strings, with floats handled like fstr.
 
rtp2xyz(r_rtp, theta=0, phi=0, **name_Cartesian_and_kwds)
Convert spherical, polar (r, theta, phi) to cartesian (x, y, z) coordinates.
 
rtp2xyz_(r_rtp, theta=0, phi=0, **name_Cartesian_and_kwds)
Convert spherical, polar (r, theta, phi) to cartesian (x, y, z) coordinates.
 
scalar(value, low=2.220446049250313e-16, high=1.0, name='scalar', Error=<type 'exceptions.ValueError'>)
DEPRECATED, use class Number_ or Scalar_.
 
signBit(x)
Return signbit(x), like C++.
 
signOf(x)
Return sign of x as int.
 
simplify1(points, distance=0.001, radius=6371008.771415, indices=False, **options)
Basic simplification of a path of LatLon points by eliminating any points closer together than the given distance tolerance.
 
simplify2(points, pipe=0.001, **radius_shortest_indices_options)
DEPRECATED, use function pygeodesy.simplifyRW.
 
simplifyRDP(points, distance=0.001, radius=6371008.771415, shortest=False, indices=False, modified=False, **options)
Ramer-Douglas-Peucker (RDP) simplification of a path of LatLon points by eliminating any points too close together or closer to an edge than the given distance tolerance.
 
simplifyRDPm(points, distance=0.001, **radius_shortest_indices_options)
DEPRECATED on 2024.11.28, use function pygeodesy.simplifyRDP(points, modified=True, ...).
 
simplifyRW(points, pipe=0.001, radius=6371008.771415, shortest=False, indices=False, **options)
Reumann-Witkam (RW) simplification of a path of LatLon points by eliminating any points too close together or within the given pipe tolerance along an edge.
 
simplifyVW(points, area=0.001, radius=6371008.771415, indices=False, attr=None, modified=False, **options)
Visvalingam-Whyatt (VW) simplification of a path of LatLon points by eliminating any points too close or with a triangular area not exceeding the given area tolerance squared.
 
simplifyVWm(points, area=0.001, **radius_attr_indices_options)
DEPRECATED on 2024.11.28, use function pygeodesy.simplifyVW(points, modified=True, ...).
 
sincos2(rad)
Return the sine and cosine of an angle in radians.
 
sincos2_(*rads)
Yield the sine and cosine of angle(s) in radians.
 
sincos2d(deg, adeg=0.0)
Return the sine and cosine of an angle in degrees.
 
sincos2d_(*degs)
Yield the sine and cosine of angle(s) in degrees.
 
sincostan3(rad)
Return the sine, cosine and tangent of an angle in radians.
 
sincostan3d(deg)
Return the sine, cosine and tangent of an angle in degrees.
 
snellius3(a, b, degC, alpha, beta)
Snellius' surveying using Snellius Pothenot.
 
soddy4(point1, point2, point3, eps=8.881784197001252e-16, useZ=True)
Return the radius and center of the inner Soddy circle of a (2- or 3-D) triangle.
 
splice(iterable, n=2, **fill)
Split an iterable into n slices.
 
sqrt0(x, Error=None)
Return the square root sqrt(x) iff x > EPS02, preserving type(x).
 
sqrt3(x)
Return the square root, cubed sqrt(x)**3 or sqrt(x**3), preserving type(x).
 
sqrt_a(h, b)
Compute a side of a right-angled triangle from sqrt(h**2 - b**2).
 
str2ub(arg)
(INTERNAL) Helper, no-op.
 
strs(objs, prec=6, fmt='F', ints=False)
Convert objects to str strings, with floats handled like fstr.
 
sumOf(vectors, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds)
Compute the vectorial sum of two oe more vectors.
 
tan(rad, **raiser_kwds)
Return the tangent of an angle in radians.
 
tanPI_2_2(rad)
Compute the tangent of half angle, 90 degrees rotated.
 
tan_(*rads, **raiser_kwds)
Yield the tangent of angle(s) in radians.
 
tan_2(rad, **semi)
Compute the tangent of half angle.
 
tand(deg, **raiser_kwds)
Return the tangent of an angle in degrees.
 
tand_(*degs, **raiser_kwds)
Yield the tangent of angle(s) in degrees.
 
thomas(lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=False)
Compute the distance between two (ellipsoidal) points using Thomas' formula.
 
thomas_(phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)
Compute the angular distance between two (ellipsoidal) points using Thomas' formula.
 
tienstra(pointA, pointB, pointC, alpha, **beta_gamma_useZ_Clas_and_kwds)
DEPRECATED, use function pygeodesy.tienstra7.
 
tienstra7(pointA, pointB, pointC, alpha, beta=None, gamma=None, useZ=False, **Clas_and_kwds)
3-Point resection using Tienstra's formula.
 
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='+', **s_D_M_S)
Convert signed degrees to string, without suffix.
 
toEtm8(latlon, lon=None, datum=None, Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, strict=True, zone=None, **name_cmoff)
Convert a geodetic lat-/longitude 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_Lcc_kwds)
Convert an (ellipsoidal) geodetic point to a Lambert location.
 
toMgrs(utmups, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>, **name_Mgrs_kwds)
Convert a UTM or UPS coordinate to an MGRS grid reference.
 
toOsgr(latlon, lon=None, kTM=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., Osgr=<class 'pygeodesy.osgr.Osgr'>, **prec_name_Osgr_kwds)
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=_UTM, cmoff=True, name='')
DEPRECATED, use function pygeodesy.toUtm8.
 
toUtm8(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, strict=True, zone=None, **name_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, earth=6378137.0, Wm=<class 'pygeodesy.webmercator.Wm'>, **name_Wm_kwds_radius)
Convert a lat-/longitude point to a WM coordinate.
 
toise2m(toises)
Convert French toises to meter.
 
trfTransform0(reframe, reframe2, epoch=None, epoch2=None, indirect=True, inverse=True, exhaust=False)
Get a Helmert transform to convert one reframe observed at epoch to an other reframe2 at observed at epoch2 or epoch.
 
trfTransforms(reframe, reframe2, epoch=None, epoch2=None, indirect=True, inverse=True, exhaust=False)
Yield all Helmert transform to convert one reframe observed at epoch to an other reframe2 at observed at epoch2 or epoch.
 
trfXform(reframe1, reframe2, epoch=None, xform=None, rates=None, raiser=True)
Define a new Terrestrial Reference Frame (TRF) converter or get an existing one.
 
triAngle(a, b, c)
Compute one angle of a triangle.
 
triAngle4(a, b, c)
DEPRECATED on 2023.09.14, use function pygeodesy.triAngle5.
 
triAngle5(a, b, c)
Compute the angles of a triangle.
 
triArea(a, b, c)
Compute the area of a triangle using Heron's stable formula.
 
triSide(a, b, radC)
Compute one side of a triangle.
 
triSide2(b, c, radB)
Compute a side and its opposite angle of a triangle.
 
triSide4(radA, radB, c)
Compute two sides and the height of a triangle.
 
triaxum5(points, useZ=True)
Best-fit a triaxial ellipsoid through three or more (3-D) points.
 
trilaterate2d2(x1, y1, radius1, x2, y2, radius2, x3, y3, radius3, eps=None, **Vector_and_kwds)
Trilaterate three circles, each given as a (2-D) center and a radius.
 
trilaterate3d2(center1, radius1, center2, radius2, center3, radius3, eps=2.220446049250313e-16, **Vector_and_kwds)
Trilaterate three spheres, each given as a (3-D) center and a radius.
 
truncate(x, ndigits=None)
Truncate to the given number of digits.
 
tyr3d(tilt=0, yaw=0, roll=0, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **name_Vector_kwds)
Convert an attitude pose into a (3-D) direction vector.
 
ub2str(arg)
(INTERNAL) Helper, no-op.
 
unStr(name, *args, **kwds)
DEPRECATED, use function pygeodesy.unstr.
 
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.
 
unsign0(x)
DEPRECATED, use function pygeodesy.unsigned0.
 
unsigned0(x)
Unsign if 0.0.
 
unstr(where, *args, **kwds_)
Return the string representation of an invokation.
 
upsZoneBand5(lat, lon, strict=True, **name)
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 pygeodesy.utmZoneBand5.
 
utmZoneBand5(lat, lon, cmoff=False, **name)
Return the UTM zone number, Band letter, hemisphere and (clipped) lat- and longitude for a given location.
 
utmupsValidate(coord, falsed=False, MGRS=False, Error=<class 'pygeodesy.utmups.UTMUPSError'>)
Check a UTM or UPS coordinate.
 
utmupsValidateOK(coord, falsed=False, ok=True)
Check a UTM or UPS coordinate.
 
utmupsZoneBand5(lat, lon, cmoff=False, **name)
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.771415, wrap=False)
Compute the distance between two (spherical) points using Vincenty's spherical formula.
 
vincentys_(geohash1, geohash2, **radius_wrap)
Compute the distance between two geohashes using the pygeodesy.vincentys formula.
 
wildberger3(a, b, c, alpha, beta, R3=<built-in function min>)
Snellius' surveying using Rational Trigonometry.
 
wrap180(deg)
Wrap degrees to [-180..+180].
 
wrap360(deg)
Wrap degrees to [0..+360).
 
wrap90(deg)
Wrap degrees to [-90..+90].
 
wrapPI(rad)
Wrap radians to [-PI..+PI].
 
wrapPI2(rad)
Wrap radians to [0..+2PI).
 
wrapPI_2(rad)
Wrap radians to [-PI/2..+PI/2].
 
wrap_normal(*normal)
Define the operation for the keyword argument wrap=True, across pygeodesy: wrap, normalize or no-op.
 
xyz2rtp(x_xyz, y=0, z=0, **name)
Convert cartesian (x, y, z) to spherical, polar (r, theta, phi) coordinates.
 
xyz2rtp_(x_xyz, y=0, z=0, **name)
Convert cartesian (x, y, z) to spherical, polar (r, theta, phi) coordinates.
 
yard2m(yards)
Convert UK yards to meter.
 
zcrt(x)
Return the 6-th, zenzi-cubic root, x**(1 / 6), preserving type(x).
 
zqrt(x)
Return the 8-th, zenzi-quartic or squared-quartic root, x**(1 / 8), preserving type(x).
Variables
  pygeodesy_abspath = '/Users/jean/Library/CloudStorage/Dropbox/...
Fully qualified pygeodesy directory name (str).
  version = '25.1.9'
Normalized pygeodesy version (str).
  Caps = Caps()
  Conics = Conics.WRF_Lb: Conic(name='WRF_Lb', lat0=40, lon0=-97...
Registered, predefined conics (enum-like).
  DIG = 15
System's float decimal digits = 15 (int).
  Datums = Datums.Sphere: Datum(name='Sphere', ellipsoid=Ellipso...
Registered, predefined datums (enum-like).
  DeprecationWarnings = DeprecationWarnings()
  EPS = 2.220446049250313e-16
System's epsilon ≈ 2.22044604925e-16 (float).
  EPS0 = 4.930380657631324e-32
EPS**2 ≈ 4.9e-32 for near-zero comparison
  EPS02 = 2.4308653429145085e-63
EPS**4 ≈ 2.4e-63 for near-zero squared comparison
  EPS1 = 0.9999999999999998
1 - EPS ≈ 0.9999999999999998 (float).
  EPS1_2 = 0.9999999999999999
  EPS2 = 4.440892098500626e-16
EPS * 2 ≈ 4.440892098501e-16 (float).
  EPS4 = 8.881784197001252e-16
EPS * 4 ≈ 8.881784197001e-16 (float).
  EPS_2 = 1.1102230246251565e-16
EPS / 2 ≈ 1.110223024625e-16 (float).
  Ellipsoids = Ellipsoids.Sphere: Ellipsoid(name='Sphere', a=637...
Registered, predefined ellipsoids (enum-like).
  F_D = 'd'
Format degrees as unsigned "deg°" with symbol, plus compass point suffix N, S, E or W (str).
  F_D60 = 'd60'
Format degrees as unsigned "[D]DD.MMSS" sexagecimal without symbols, plus suffix (str).
  F_D60_ = '-d60'
Format degrees as signed "-/[D]DD.MMSS" sexagecimal without symbols, without suffix (str).
  F_D60__ = '+d60'
Format degrees as signed "-/+[D]DD.MMSS" sexagecimal without symbols, without suffix (str).
  F_DEG = 'deg'
Format degrees as unsigned "[D]DD" without symbol, plus suffix (str).
  F_DEG_ = '-deg'
Format degrees as signed "-/[D]DD" without symbol, without suffix (str).
  F_DEG__ = '+deg'
Format degrees as signed "-/+[D]DD" without symbol, without suffix (str).
  F_DM = 'dm'
Format degrees as unsigned "deg°min′" with symbols, plus suffix (str).
  F_DMS = 'dms'
Format degrees as unsigned "deg°min′sec″" with symbols, plus suffix (str).
  F_DMS_ = '-dms'
Format degrees as signed "-/deg°min′sec″" with symbols, without suffix (str).
  F_DMS__ = '+dms'
Format degrees as signed "-/+deg°min′sec″" with symbols, without suffix (str).
  F_DM_ = '-dm'
Format degrees as signed "-/deg°min′" with symbols, without suffix (str).
  F_DM__ = '+dm'
Format degrees as signed "-/+deg°min′" with symbols, without suffix (str).
  F_D_ = '-d'
Format degrees as signed "-/deg°" with symbol, without suffix (str).
  F_D__ = '+d'
Format degrees as signed "-/+deg°" with symbol, without suffix (str).
  F_MIN = 'min'
Format degrees as unsigned "[D]DDMM" without symbols, plus suffix (str).
  F_MIN_ = '-min'
Format degrees as signed "-/[D]DDMM" without symbols, without suffix (str).
  F_MIN__ = '+min'
Format degrees as signed "-/+[D]DDMM" without symbols, without suffix (str).
  F_RAD = 'rad'
Convert degrees to radians and format as unsigned "RR" with symbol, plus suffix (str).
  F_RAD_ = '-rad'
Convert degrees to radians and format as signed "-/RR" without symbol, without suffix (str).
  F_RAD__ = '+rad'
Convert degrees to radians and format as signed "-/+RR" without symbol, without suffix (str).
  F_SEC = 'sec'
Format degrees as unsigned "[D]DDMMSS" without symbols, plus suffix (str).
  F_SEC_ = '-sec'
Format degrees as signed "-/[D]DDMMSS" without symbols, without suffix (str).
  F_SEC__ = '+sec'
Format degrees as signed "-/+[D]DDMMSS" without symbols, without suffix (str).
  F__E = 'e'
Format degrees as unsigned "%E" without symbols, plus suffix (str).
  F__E_ = '-e'
Format degrees as signed "-/%E" without symbols, without suffix (str).
  F__E__ = '+e'
Format degrees as signed "-/+%E" without symbols, without suffix (str).
  F__F = 'f'
Format degrees as unsigned "%F" without symbols, plus suffix (str).
  F__F_ = '-f'
Format degrees as signed "-/%F" without symbols, without suffix (str).
  F__F__ = '+f'
Format degrees as signed "-/+%F" without symbols, without suffix (str).
  F__G = 'g'
Format degrees as unsigned "%G" without symbols, plus suffix (str).
  F__G_ = '-g'
Format degrees as signed "-/%G" without symbols, without suffix (str).
  F__G__ = '+g'
Format degrees as signed "-/+%G" without symbols, without suffix (str).
  INF = inf
Infinity (float), see functions isinf and isfinite and NINF.
  INT0 = 0
int(0), missing Z-components, if z=INT0, see functions isint0, meeus2
  MANTIS = 53
  MANT_DIG = 53
System's float mantissa bits = 53 (int).
  MAX = 1.7976931348623157e+308
System's float max ≈ 1.798e+308 (float).
  MAX_EXP = 1024
  MIN = 2.2250738585072014e-308
System's float min ≈ 2.225e-308 (float).
  MIN_EXP = -1021
  NAN = nan
Not-A-Number (float), see function isnan.
  NEG0 = -0.0
Negative 0.0 (float), see function isneg0.
  NINF = -inf
Negative infinity (float), see function isninf and INF.
  NN = ''
Empty (str), Nomen Nescio.
  NorthPole = _N_vector_(0, 0, 1)
  OK = 'OK'
  PI = 3.141592653589793
Constant math.pi (float).
  PI2 = 6.283185307179586
Two PI, PI * 2, aka Tau (float).
  PI3 = 9.42477796076938
Three PI, PI * 3 (float).
  PI3_2 = 4.71238898038469
One and a half PI, PI * 3 / 2 (float).
  PI4 = 12.566370614359172
Four PI, PI * 4 (float).
  PI_2 = 1.5707963267948966
Half PI, PI / 2 (float).
  PI_3 = 1.0471975511965976
One third PI, PI / 3 (float).
  PI_4 = 0.7853981633974483
Quarter PI, PI / 4 (float).
  R_FM = 6371000.0
Former FAI-Sphere earth radius (meter).
  R_GM = 6371230.0
Average earth radius, distance to geoid surface (meter)
  R_KM = 6371.0087714149995
Mean (spherical) earth radius (Km, kilometer).
  R_M = 6371008.771415
Mean (spherical) earth radius (meter).
  R_MA = 6378137.0
Equatorial earth radius (meter), WGS84, EPSG:3785.
  R_MB = 6356752.3
Polar earth radius (meter), WGS84, EPSG:3785.
  R_NM = 3440.06953100162
Mean (spherical) earth radius (NM, nautical miles).
  R_QM = 6372797.560856
Earth' (triaxial) quadratic mean radius (meter)
  R_SM = 3958.7613160486508
Mean (spherical) earth radius (SM, statute miles).
  R_VM = 6366707.0194937
Aviation/Navigation earth radius (meter).
  RefFrames = RefFrames.ETRF89: RefFrame(name='ETRF89', epoch=19...
Registered, predefined reference frames (enum-like).
  S_DEG = '°'
Degrees symbol, default "°"
  S_DMS = True
If True, include, otherwise cancel all DMS symbols, default True.
  S_MIN = '\xe2\x80\xb2'
Minutes symbol, default "′" aka PRIME
  S_RAD = ''
Radians symbol, default "" aka NN
  S_SEC = ''
Seconds symbol, default "″" aka DOUBLE_PRIME
  S_SEP = ''
Separator between deg°|min′|sec″|suffix, default "" aka NN
  SouthPole = _N_vector_(0, 0, -1)
  Transforms = Transforms.OSGB36: Transform(name='OSGB36', tx=-4...
Registered, predefined transforms (enum-like).
  Triaxials =
Registered, predefined triaxial ellipsoids (enum-like).
  isLazy = None
Lazy import setting (int 0, 1, 2 or 3+) from env variable PYGEODESY_LAZY_IMPORT, or None if lazy import is not supported or not enabled, or False if initializing lazy import failed.
Function Details

Fsum2product (*xs, **kwds)

 

DEPRECATED on 2024.09.19, use Fsum(*xs, f2product=True, ...).

Decorators:
  • @deprecated_function

NM2m (nm)

 

Convert nautical miles to meter (m).

Arguments:
  • nm - Value in nautical miles (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid nm.

SM2m (sm)

 

Convert statute miles to meter (m).

Arguments:
  • sm - Value in statute miles (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid sm.

SinCos2 (x)

 

Get sin and cos of typed angle.

Arguments:
Returns:
2-Tuple (sin(x), cos(x)).

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.

Arguments:
  • zone - The UTM zone with/-out longitudinal Band or UPS zone 0 or "00" with/-out polar Band (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 'C'|'D'|..|'W'|'X' or UPS polar Band letter 'A'|'B'|'Y'|'Z' Band letter (str).
  • datum - The coordinate's datum (Datum).
  • falsed - If True, both easting and northing are falsed (bool).
  • name - Optional Utm or Ups name=NN (str).
Returns:
New UTM or UPS instance (Utm or Ups).
Raises:
  • TypeError - Invalid datum.
  • UTMUPSError - UTM or UPS validation failed.

See Also: Classes Utm and Ups and Karney's UTMUPS.

a_b2e (a, b)

 

Return e, the 1st eccentricity for a given equatorial and polar radius.

Arguments:
  • a - Equatorial radius (scalar > 0).
  • b - Polar radius (scalar > 0).
Returns:
The unsigned, (1st) eccentricity (float or 0), sqrt(1 - (b / a)**2).

Note: The result is always non-negative and 0 for near-spherical ellipsoids.

a_b2e2 (a, b)

 

Return e2, the 1st eccentricity squared for a given equatorial and polar radius.

Arguments:
  • a - Equatorial radius (scalar > 0).
  • b - Polar radius (scalar > 0).
Returns:
The signed, (1st) eccentricity squared (float or 0), 1 - (b / a)**2.

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

a_b2e22 (a, b)

 

Return e22, the 2nd eccentricity squared for a given equatorial and polar radius.

Arguments:
  • a - Equatorial radius (scalar > 0).
  • b - Polar radius (scalar > 0).
Returns:
The signed, 2nd eccentricity squared (float or 0), (a / b)**2 - 1.

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

a_b2e32 (a, b)

 

Return e32, the 3rd eccentricity squared for a given equatorial and polar radius.

Arguments:
  • a - Equatorial radius (scalar > 0).
  • b - Polar radius (scalar > 0).
Returns:
The signed, 3rd eccentricity squared (float or 0), (a**2 - b**2) / (a**2 + b**2).

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

a_b2f (a, b)

 

Return f, the flattening for a given equatorial and polar radius.

Arguments:
  • a - Equatorial radius (scalar > 0).
  • b - Polar radius (scalar > 0).
Returns:
The flattening (scalar or 0), (a - b) / a.

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

a_b2f2 (a, b)

 

Return f2, the 2nd flattening for a given equatorial and polar radius.

Arguments:
  • a - Equatorial radius (scalar > 0).
  • b - Polar radius (scalar > 0).
Returns:
The signed, 2nd flattening (scalar or 0), (a - b) / b.

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

a_b2f_ (a, b)

 

Return f_, the inverse flattening for a given equatorial and polar radius.

Arguments:
  • a - Equatorial radius (scalar > 0).
  • b - Polar radius (scalar > 0).
Returns:
The inverse flattening (scalar or 0), a / (a - b).

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

a_b2n (a, b)

 

Return n, the 3rd flattening for a given equatorial and polar radius.

Arguments:
  • a - Equatorial radius (scalar > 0).
  • b - Polar radius (scalar > 0).
Returns:
The signed, 3rd flattening (scalar or 0), (a - b) / (a + b).

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

a_f2b (a, f)

 

Return b, the polar radius for a given equatorial radius and flattening.

Arguments:
  • a - Equatorial radius (scalar > 0).
  • f - Flattening (scalar < 1, negative for prolate).
Returns:
The polar radius (float), a * (1 - f).

a_f_2b (a, f_)

 

Return b, the polar radius for a given equatorial radius and inverse flattening.

Arguments:
  • a - Equatorial radius (scalar > 0).
  • f_ - Inverse flattening (scalar >>> 1).
Returns:
The polar radius (float), a * (f_ - 1) / f_.

acre2ha (acres)

 

Convert acres to hectare.

Arguments:
  • acres - Value in acres (scalar).
Returns:
Value in hectare (float).
Raises:
  • ValueError - Invalid acres.

acre2m2 (acres)

 

Convert acres to square meter.

Arguments:
  • acres - Value in acres (scalar).
Returns:
Value in meter^2 (float).
Raises:
  • ValueError - Invalid acres.

anStr (name, OKd='._-', sub='_')

 

DEPRECATED, use function pygeodesy.anstr.

Decorators:
  • @deprecated_function

angle2chord (rad, radius=6371008.771415)

 

Get the chord length of a (central) angle or angular distance.

Arguments:
Returns:
Chord length (meter, same units as radius or if radius is None, radians).

See Also: Function chord2angle, method intermediateChordTo and great-circle-distance.

anstr (name, OKd='._-', sub='_')

 

Make a valid name of alphanumeric and OKd characters.

Arguments:
  • 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, intermediate whitespace characters are coalesced and substituted.

antipode (lat, lon, **name)

 

Return the antipode, the point diametrically opposite to a given point in degrees.

Arguments:
  • lat - Latitude (degrees).
  • lon - Longitude (degrees).
  • name - Optional name=NN (str).
Returns:
A LatLon2Tuple(lat, lon).

See Also: Functions antipode_ and normal and Geosphere.

antipode_ (phi, lam, **name)

 

Return the antipode, the point diametrically opposite to a given point in radians.

Arguments:
  • phi - Latitude (radians).
  • lam - Longitude (radians).
  • name - Optional name=NN (str).
Returns:
A PhiLam2Tuple(phi, lam).

See Also: Functions antipode and normal_ and Geosphere.

areaOf (points, adjust=True, radius=6371008.771415, wrap=True)

 

Approximate the area of a polygon or composite.

Arguments:
  • points - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
  • adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
  • radius - Mean earth radius (meter) or None.
  • wrap - If True, wrap or normalize and unroll the points (bool).
Returns:
Approximate area (square meter, same units as radius or radians squared if radius is None).
Raises:
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid radius.

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, ellipsoidalExact.areaOf and ellipsoidalKarney.areaOf.

areaof (points, adjust=True, radius=6371008.771415, wrap=True)

 

DEPRECATED, use function pygeodesy.areaOf.

Decorators:
  • @deprecated_function

atan1d (y, x=1.0)

 

Return atan(y / x) angle in degrees [-90..+90] using atan2d for consistency and to avoid ZeroDivisionError.

See Also: Function pygeodesy.atan2d.

atan2 (y, x)

 

Return the arc tangent (measured in radians) of y/x. Unlike atan(y/x), the signs of both x and y are considered.

atan2b (y, x)

 

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

See Also: Function pygeodesy.atan2d.

atan2d (y, x, reverse=False)

 

Return atan2(y, x) in degrees [-180..+180], optionally reversed (by 180 degrees for azimuths).

See Also: Karney's C++ function Math.atan2d.

atand (x)

 

DEPRECATED on 2023.09.28, use function pygeodesy.atan1d.

Decorators:
  • @deprecated_function

attrs (inst, *names, **Nones_True__pairs_kwds)

 

Get instance attributes as name=value strings, with floats formatted by function fstr.

Arguments:
  • inst - The instance (any type).
  • names - The attribute names, all other positional (str).
  • Nones_True__pairs_kwds - Keyword argument for function pairs, except Nones=True to in-/exclude missing or None-valued attributes.
Returns:
A tuple(sep.join(t) for t in zip(names, reprs(values, ...))) of strs.

b_f2a (b, f)

 

Return a, the equatorial radius for a given polar radius and flattening.

Arguments:
  • b - Polar radius (scalar > 0).
  • f - Flattening (scalar < 1, negative for prolate).
Returns:
The equatorial radius (float), b / (1 - f).

b_f_2a (b, f_)

 

Return a, the equatorial radius for a given polar radius and inverse flattening.

Arguments:
  • b - Polar radius (scalar > 0).
  • f_ - Inverse flattening (scalar >>> 1).
Returns:
The equatorial radius (float), b * f_ / (f_ - 1).

bearing (lat1, lon1, lat2, lon2, **final_wrap)

 

Compute the initial or final bearing (forward or reverse azimuth) between two (spherical) points.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • final_wrap - Optional keyword arguments for function pygeodesy.bearing_.
Returns:
Initial or final bearing (compass degrees360) or zero if both points coincide.

bearingDMS (bearing, form='d', prec=None, sep='', **s_D_M_S)

 

Convert bearing to a string (without compass point suffix).

Arguments:
  • bearing - Bearing from North (compass degrees360).
  • form - Format specifier for deg (str or F_...).
  • prec - Number of decimal digits (0..9 or None for default).
  • sep - Separator between degrees, minutes, seconds, suffix (str).
  • s_D_M_S - Optional keyword arguments to override any or cancel all DMS symbol suffixes, see function pygeodesy.toDMS.
Returns:
Compass degrees per the specified form (str).

See Also: Function pygeodesy.toDMS and its Notes for further details.

bearing_ (phi1, lam1, phi2, lam2, final=False, wrap=False)

 

Compute the initial or final bearing (forward or reverse azimuth) between two (spherical) points.

Arguments:
  • phi1 - Start latitude (radians).
  • lam1 - Start longitude (radians).
  • phi2 - End latitude (radians).
  • lam2 - End longitude (radians).
  • final - If True, return the final, otherwise the initial bearing (bool).
  • wrap - If True, wrap or normalize and unroll phi2 and lam2 (bool).
Returns:
Initial or final bearing (compass radiansPI2) or zero if both points coincide.

bounds (geohash, LatLon=None, **LatLon_kwds)

 

Returns the lower-left SW and upper-right NE corners of a geohash.

Arguments:
  • geohash - To be "bound" (Geohash).
  • LatLon - Optional class to return the bounds (LatLon) or None.
  • LatLon_kwds - Optional, additional LatLon keyword arguments, ignored if LatLon is None.
Returns:
A Bounds2Tuple(latlonSW, latlonNE), each a LatLon or if LatLon is None, a Bounds4Tuple(latS, lonW, latN, lonE).
Raises:
  • TypeError - The geohash is not a Geohash, LatLon or str or invalid LatLon or invalid LatLon_kwds.
  • GeohashError - Invalid or null geohash.

boundsOf (points, wrap=False, LatLon=None)

 

Determine the bottom-left SW and top-right NE corners of a path or polygon.

Arguments:
  • points - The path or polygon points (LatLon[]).
  • wrap - If True, wrap or normalize and unroll the points (bool).
  • LatLon - Optional class to return the bounds corners (LatLon) or None.
Returns:
A Bounds2Tuple(latlonSW, latlonNE), each a LatLon or if LatLon is None, a Bounds4Tuple(latS, lonW, latN, lonE).
Raises:
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.

See Also: Function quadOf.

bqrt (x)

 

Return the 4-th, bi-quadratic or quartic root, x**(1 / 4), preserving type(x).

Arguments:
Returns:
Quartic root (float or an Fsum).
Raises:
  • TypeeError - Invalid x.
  • ValueError - Negative x.

See Also: Functions zcrt and zqrt.

callername (up=1, dflt='', source=False, underOK=False)

 

Get the name of the invoking callable.

Arguments:
  • up - Number of call stack frames up (int).
  • dflt - Default return value (any).
  • source - Include source file name and line number (bool).
  • underOK - If True, private, internal callables are OK, otherwise private callables are skipped (bool).
Returns:
The callable name (str) or dflt if none found.

cassini (pointA, pointB, pointC, alpha, beta, useZ=False, **Clas_and_kwds)

 

3-Point resection using Cassini's method.

Arguments:
  • pointA - First point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • pointB - Second point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • pointC - Center point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • alpha - Angle subtended by triangle side pointA to pointC (degrees, non-negative).
  • beta - Angle subtended by triangle side pointB to pointC (degrees, non-negative).
  • useZ - If True, use and interpolate the Z component, otherwise force z=INT0 (bool).
  • Clas_and_kwds - Optional class Clas=pointA.classof to return the survey point with optionally other Clas keyword arguments to instantiate the survey point.
Returns:
The survey point, an instance of Clas or pointA's (sub-)class.
Raises:
  • ResectionError - Near-coincident, -colinear or -concyclic points or negative or invalid alpha or beta.
  • TypeError - Invalid pointA, pointB or pointM.

Note: Typically, pointC is between pointA and pointB.

See Also: Three Point Resection Problem and functions collins5, pierlot, pierlotx and tienstra7.

cbrt (x)

 

Compute the cube root x**(1/3), preserving type(x).

Arguments:
Returns:
Cubic root (float or Fsum).

See Also: Functions cbrt2 and sqrt3.

cbrt2 (x)

 

Compute the cube root squared x**(2/3), preserving type(x).

Arguments:
Returns:
Cube root squared (float or Fsum).

See Also: Functions cbrt and sqrt3.

centroidOf (points, wrap=False, LatLon=None)

 

Determine the centroid of a polygon.

Arguments:
  • points - The polygon points (LatLon[]).
  • wrap - If True, wrap or normalize and unroll the points (bool).
  • LatLon - Optional class to return the centroid (LatLon) or None.
Returns:
Centroid (LatLon) or a LatLon2Tuple(lat, lon) if LatLon is None.
Raises:
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.
  • ValueError - The points enclose a pole or near-zero area.

See Also: Centroid and Paul Bourke's Calculating The Area And Centroid Of A Polygon, 1988.

chain2m (chains)

 

Convert UK chains to meter.

Arguments:
  • chains - Value in chains (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid chains.

chord2angle (chord, radius=6371008.771415)

 

Get the (central) angle from a chord length or distance.

Arguments:
  • chord - Length or distance (meter, same units as radius).
  • radius - Mean earth radius (meter, conventionally), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
Returns:
Angle (radians with sign of chord) or 0 if radius=0.

Note: The angle will exceed PI if chord > radius * 2.

See Also: Function angle2chord.

circin6 (point1, point2, point3, eps=8.881784197001252e-16, useZ=True)

 

Return the radius and center of the inscribed aka Incircle of a (2- or 3-D) triangle.

Arguments:
  • point1 - First point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point2 - Second point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point3 - Third point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • eps - Tolerance for function pygeodesy.trilaterate3d2 if useZ is True else pygeodesy.trilaterate2d2.
  • useZ - If True, use the Z components, otherwise force z=INT0 (bool).
Returns:
Circin6Tuple(radius, center, deltas, cA, cB, cC). The center and contact points cA, cB and cC, each an instance of point1's (sub-)class, are co-planar with the three given points.
Raises:
  • ImportError - Package numpy not found, not installed or older than version 1.10 and useZ is True.
  • IntersectionError - Near-coincident or -colinear points or a trilateration or numpy issue.
  • TypeError - Invalid point1, point2 or point3.

See Also: Functions radii11 and circum3, Contact Triangle and Incircle.

circle4 (earth, lat)

 

Get the equatorial or a parallel circle of latitude.

Arguments:
Returns:
A Circle4Tuple(radius, height, lat, beta).
Raises:
  • RangeError - Latitude lat outside valid range and rangerrors is True.
  • TypeError - Invalid earth.
  • ValueError - earth or lat.

circum3 (point1, point2, point3, circum=True, eps=8.881784197001252e-16, useZ=True)

 

Return the radius and center of the smallest circle through or containing three (2- or 3-D) points.

Arguments:
  • point1 - First point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • point2 - Second point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • point3 - Third point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • circum - If True, return the circumradius and circumcenter always, ignoring the Meeus' Type I case (bool).
  • eps - Tolerance for function pygeodesy.trilaterate3d2 if useZ is True else pygeodesy.trilaterate2d2.
  • useZ - If True, use the Z components, otherwise force z=INT0 (bool).
Returns:
A Circum3Tuple(radius, center, deltas). The center, an instance of point1's (sub-)class, is co-planar with the three given points.
Raises:
  • ImportError - Package numpy not found, not installed or older than version 1.10 and useZ is True.
  • IntersectionError - Near-coincident or -colinear points or a trilateration or numpy issue.
  • TypeError - Invalid point1, point2 or point3.

See Also: Functions pygeodesy.circum4_ and pygeodesy.meeus2 and Meeus, J. Astronomical Algorithms, 2nd Ed. 1998, page 127ff, circumradius and circumcircle.

circum4 (points, useZ=True, **Vector_and_kwds)

 

Best-fit a sphere through three or more (3-D) points.

Arguments:
  • points - Iterable of points (each a Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • useZ - If True, use the points' Z component, otherwise force z=INT0 (bool).
  • Vector_and_kwds - Optional class Vector=None to return the center point and optionally, additional Vector keyword arguments, otherwise the points' (sub-)class.
Returns:
Circum4Tuple(radius, center, rank, residuals) with center an instance of points[0]' (sub-)class or Vector if specified.
Raises:
  • ImportError - Package numpy not found, not installed or older than version 1.10.
  • NumPyError - Some numpy issue.
  • PointsError - Too few points.
  • TypeError - One of the points is invalid.

circum4_ (*points, **useZ_Vector_and_kwds)

 

Best-fit a sphere through three or more (3-D) positional points.

Arguments:
  • points - The points (each a Cartesian, Vector3d, Vector3Tuple or Vector4Tuple), all positional.
  • useZ_Vector_and_kwds - Keyword arguments useZ=True and Vector=None, see function circum4.

See Also: Function circum4 for further details.

classname (inst, prefixed=None)

 

Return the instance' class name optionally prefixed with the module name.

Arguments:
  • 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 class naming for [module.]class names.

Arguments:
  • prefixed - Include the module name (bool).
Returns:
Previous class naming setting (bool).

clipCS3 (points, lowerleft, upperright, closed=False, inull=False)

 

DEPRECATED, use function pygeodesy.clipCS4.

Returns:
Yield a ClipCS3Tuple(start, end, index) for each edge of the clipped path.
Decorators:
  • @deprecated_function

clipCS4 (points, lowerleft, upperight, closed=False, inull=False)

 

Clip a path against a rectangular clip box using the Cohen-Sutherland algorithm.

Arguments:
  • points - The points (LatLon[]).
  • lowerleft - Bottom-left corner of the clip box (LatLon).
  • upperight - Top-right corner of the clip box (LatLon).
  • closed - Optionally, close the path (bool).
  • inull - Optionally, retain null edges if inside (bool).
Returns:
Yield a ClipCS4Tuple(start, end, i, j) for each edge of the clipped path.
Raises:
  • ClipError - The lowerleft and upperight corners specify an invalid clip box.
  • PointsError - Insufficient number of points.

clipDMS (deg, limit)

 

DEPRECATED, use function pygeodesy.clipDegrees.

Decorators:
  • @deprecated_function

clipDegrees (deg, limit)

 

Clip a lat- or longitude to the given range.

Arguments:
  • deg - Unclipped lat- or longitude (scalar degrees).
  • limit - Valid -/+limit range (degrees).
Returns:
Clipped value (degrees).
Raises:

clipFHP4 (points, corners, closed=False, inull=False, raiser=False, eps=2.220446049250313e-16)

 

Clip one or more polygons against a clip region or box using Forster-Hormann-Popa's C++ implementation transcoded to pure Python.

Arguments:
  • points - The polygon points and clips (LatLon[]).
  • corners - Three or more points defining the clip regions (LatLon[]) or two points to specify a single, rectangular clip box.
  • closed - If True, close each result clip (bool).
  • inull - If True, retain null edges in result clips (bool).
  • raiser - If True, throw ClipError exceptions (bool).
  • esp - Tolerance for eliminating null edges (degrees, same units as the points and corners coordinates).
Returns:
Yield a ClipFHP4Tuple(lat, lon, height, clipid) for each clipped point. The result may consist of several clips, each a (closed) polygon with a unique clipid.
Raises:
  • ClipError - Insufficient points or corners or an open clip.

See Also: Forster, Hormann and Popa, class BooleanFHP and function clipGH4.

clipGH4 (points, corners, closed=False, inull=False, raiser=True, xtend=False, eps=2.220446049250313e-16)

 

Clip one or more polygons against a clip region or box using the Greiner-Hormann algorithm, Correia's implementation modified and extended.

Arguments:
  • points - The polygon points and clips (LatLon[]).
  • corners - Three or more points defining the clip regions (LatLon[]) or two points to specify a single, rectangular clip box.
  • closed - If True, close each result clip (bool).
  • inull - If True, retain null edges in result clips (bool).
  • raiser - If True, throw ClipError exceptions (bool).
  • xtend - If True, extend edges of degenerate cases, an attempt to handle the latter (bool).
  • esp - Tolerance for eliminating null edges (degrees, same units as the points and corners coordinates).
Returns:
Yield a ClipGH4Tuple(lat, lon, height, clipid) for each clipped point. The result may consist of several clips, each a (closed) polygon with a unique clipid.
Raises:
  • ClipError - Insufficient points or corners, an open clip, a degenerate case or unhandled intersection.

Note: To handle degenerate cases like point-edge and point-point intersections, use function clipFHP4.

See Also: Greiner-Hormann, Ionel Daniel Stroe, Correia's univ-polyclip, class BooleanGH and function clipFHP4.

clipLB6 (points, lowerleft, upperight, closed=False, inull=False)

 

Clip a path against a rectangular clip box using the Liang-Barsky algorithm.

Arguments:
  • points - The points (LatLon[]).
  • lowerleft - Bottom-left corner of the clip box (LatLon).
  • upperight - Top-right corner of the clip box (LatLon).
  • closed - Optionally, close the path (bool).
  • inull - Optionally, retain null edges if inside (bool).
Returns:
Yield a ClipLB6Tuple(start, end, i, fi, fj, j) for each edge of the clipped path.
Raises:
  • ClipError - The lowerleft and upperight corners specify an invalid clip box.
  • PointsError - Insufficient number of points.

clipRadians (rad, limit)

 

Clip a lat- or longitude to the given range.

Arguments:
  • rad - Unclipped lat- or longitude (radians).
  • limit - Valid -/+limit range (radians).
Returns:
Clipped value (radians).
Raises:

clipSH (points, corners, closed=False, inull=False)

 

Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm.

Arguments:
  • 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.
  • closed - Close the clipped points (bool).
  • inull - Optionally, include null edges (bool).
Returns:
Yield the clipped points (LatLon[]).
Raises:
  • ClipError - The corners specify a polar, zero-area, non-convex or otherwise invalid clip box or region.
  • PointsError - Insufficient number of points.

clipSH3 (points, corners, closed=False, inull=False)

 

Clip a polygon against a clip region or box using the Sutherland-Hodgman algorithm.

Arguments:
  • 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.
  • closed - Close the clipped points (bool).
  • inull - Optionally, include null edges (bool).
Returns:
Yield a ClipSH3Tuple(start, end, original) for each edge of the clipped polygon.
Raises:
  • ClipError - The corners specify a polar, zero-area, non-convex or otherwise invalid clip box or region.
  • PointsError - Insufficient number of points or corners.

clipStr (bstr, limit=50, white='')

 

DEPRECATED, use function pygeodesy.clips.

Decorators:
  • @deprecated_function

clips (sb, limit=50, white='', length=False)

 

Clip a string to the given length limit.

Arguments:
  • sb - String (str or bytes).
  • limit - Length limit (int).
  • white - Optionally, replace all whitespace (str).
  • length - If True, append the original [length] (bool).
Returns:
The clipped or unclipped sb.

collins (pointA, pointB, pointC, alpha, beta, **useZ_Clas_and_kwds)

 

DEPRECATED, use function pygeodesy.collins5.

Decorators:
  • @deprecated_function

collins5 (pointA, pointB, pointC, alpha, beta, useZ=False, **Clas_and_kwds)

 

3-Point resection using Collins' method.

Arguments:
  • pointA - First point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • pointB - Second point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • pointC - Center point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • alpha - Angle subtended by triangle side b from pointA to pointC (degrees, non-negative).
  • beta - Angle subtended by triangle side a from pointB to pointC (degrees, non-negative).
  • useZ - If True, use and interpolate the Z component, otherwise force z=INT0 (bool).
  • Clas_and_kwds - Optional class Clas=pointA.classof to return the survey point with optionally other Clas keyword arguments to instantiate the survey point.
Returns:
Collins5Tuple(pointP, pointH, a, b, c) with survey pointP, auxiliary pointH, each an instance of Clas or pointA's (sub-)class and triangle sides a, b and c in meter, conventionally.
Raises:
  • ResectionError - Near-coincident, -colinear or -concyclic points or negative or invalid alpha or beta.
  • TypeError - Invalid pointA, pointB or pointM.

Note: Typically, pointC is between pointA and pointB.

See Also: Collins' methode and functions cassini, pierlot, pierlotx and tienstra7.

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, not near-polar vectors up to a few hundred Km or Miles. Use function pygeodesy.bearing for longer vectors.

Arguments:
  • 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 - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Compass angle from North (degrees360).

Note: Courtesy of Martin Schultz.

See Also: Local, flat earth approximation.

compassDMS (bearing, form='d', prec=None, sep='', **s_D_M_S)

 

Convert bearing to a string suffixed with compass point.

Arguments:
  • bearing - Bearing from North (compass degrees360).
  • form - Format specifier for deg (str or F_...).
  • prec - Number of decimal digits (0..9 or None for default).
  • sep - Separator between degrees, minutes, seconds, suffix (str).
  • s_D_M_S - Optional keyword arguments to override any or cancel all DMS symbol suffixes, see function pygeodesy.toDMS.
Returns:
Compass degrees and point in the specified form (str).

See Also: Function pygeodesy.toDMS and its Notes for further details.

compassPoint (bearing, prec=3)

 

Convert a bearing from North to a compass point.

Arguments:
  • bearing - Bearing (compass degrees360).
  • prec - Precision, number of compass point characters: 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 bearing or prec.

copysign (x, y)

 

DEPRECATED, use function pygeodesy.copysign0.

Decorators:
  • @deprecated_function

copysign0 (x, y)

 

Like math.copysign(x, y) except zero, unsigned.

Returns:
math.copysign(x, y) if x else type(x)(0).

copytype (x, y)

 

Return the value of x as type of y.

Returns:
type(y)(x).

cosineAndoyerLambert (lat1, lon1, lat2, lon2, **datum_wrap)

 

DEPRECATED on 2024.12.31, use function pygeodesy.cosineLaw with corr=1.

Decorators:
  • @deprecated_function

cosineAndoyerLambert_ (phi2, phi1, lam21, **datum)

 

DEPRECATED on 2024.12.31, use function pygeodesy.cosineLaw_ with corr=1.

Decorators:
  • @deprecated_function

cosineForsytheAndoyerLambert (lat1, lon1, lat2, lon2, **datum_wrap)

 

DEPRECATED on 2024.12.31, use function pygeodesy.cosineLaw with corr=2.

Decorators:
  • @deprecated_function

cosineForsytheAndoyerLambert_ (phi2, phi1, lam21, **datum)

 

DEPRECATED on 2024.12.31, use function pygeodesy.cosineLaw_ with corr=2.

Decorators:
  • @deprecated_function

cosineLaw (lat1, lon1, lat2, lon2, corr=0, earth=None, wrap=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., radius=6371008.771415)

 

Compute the distance between two points using the Law of Cosines formula, optionally corrected.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • corr - Use corr=2 to apply the Forsythe-Andoyer-Lambert, corr=1 for the Andoyer-Lambert corrected (ellipsoidal) or keep corr=0 for the uncorrected (spherical) Law of Cosines formula (int).
  • earth - Mean earth radius (meter) or datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and lat2 and lon2 (bool).
  • datum - Default ellipsiodal earth (and for backward compatibility).
  • radius - Default spherical earth (and for backward compatibility).
Returns:
Distance (meter, same units as radius or the datum's or ellipsoid axes).
Raises:
  • TypeError - Invalid earth, datum or radius.
  • ValueError - Invalid corr.

See Also: Functions cosineLaw_, equirectangular, euclidean, flatLocal / hubeny, flatPolar, haversine, thomas and vincentys and method Ellipsoid.distance2.

Note: See note at function vincentys_.

cosineLaw_ (phi2, phi1, lam21, corr=0, earth=None, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)

 

Compute the angular distance between two points using the Law of Cosines formula, optionally corrected.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
  • corr - Use corr=2 to apply the Forsythe-Andoyer-Lambert, corr=1 for the Andoyer-Lambert corrected (ellipsoidal) or keep corr=0 for the uncorrected (spherical) Law of Cosines formula (int).
  • earth - Mean earth radius (meter) or datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • datum - Default ellipsoidal earth (and for backward compatibility).
Returns:
Angular distance (radians).
Raises:
  • TypeError - Invalid earth or datum.
  • ValueError - Invalid corr.

cot (rad, **raiser_kwds)

 

Return the cotangent of an angle in radians.

Arguments:
  • rad - Angle (radians).
  • raiser_kwds - Use raiser=False to avoid ValueErrors or optionally, additional ValueError keyword argments.
Returns:
cot(rad).
Raises:

cot_ (*rads, **raiser_kwds)

 

Yield the cotangent of angle(s) in radians.

Arguments:
  • rads - One or more angles (each in radians).
Returns:
Yield cot(rad) for each angle.

See Also: Function pygeodesy.cot for further details.

cotd (deg, **raiser_kwds)

 

Return the cotangent of an angle in degrees.

Arguments:
  • deg - Angle (degrees).
  • raiser_kwds - Use raiser=False to avoid ValueErrors or optionally, additional ValueError keyword argments.
Returns:
cot(deg).
Raises:

cotd_ (*degs, **raiser_kwds)

 

Yield the cotangent of angle(s) in degrees.

Arguments:
  • degs - One or more angles (each in degrees).
Returns:
Yield cotd(deg) for each angle.

See Also: Function pygeodesy.cotd for further details.

crosserrors (raiser=None)

 

Report or ignore vectorial cross product errors.

Arguments:
  • raiser - Use True to throw or False to ignore CrossError exceptions. Use None to leave the setting unchanged.
Returns:
Previous setting (bool).

See Also: Property Vector3d[Base].crosserrors.

date2epoch (year, month, day)

 

Return the epoch for a calendar day.

Arguments:
  • 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)
Decorators:
  • @deprecated_function

degDMS (deg, prec=6, s_D='°', s_M='\xe2\x80\xb2', s_S='', neg='-', pos='')

 

Convert degrees to a string in degrees, minutes or seconds.

Arguments:
  • deg - Value in degrees (scalar degrees).
  • prec - Number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec=1 and above, but kept for negative prec.
  • s_D - D symbol for degrees (str).
  • s_M - M symbol for minutes (str) or "" aka pygeodesy.NN.
  • s_S - S symbol for seconds (str) or "" aka pygeodesy.NN.
  • neg - Optional sign for negative ('-').
  • pos - Optional sign for positive ("") aka pygeodesy.NN.
Returns:
Either degrees, minutes or seconds (str).

See Also: Function pygeodesy.toDMS.

degrees180 (rad)

 

Convert radians to degrees and wrap [-180..+180).

Arguments:
  • rad - Angle (radians).
Returns:
Angle, wrapped (degrees180).

degrees2grades (deg)

 

Convert degrees to grades (aka gons or gradians).

Arguments:
  • deg - Angle (degrees).
Returns:
Angle (grades).

degrees2m (deg, radius=6371008.771415, lat=0)

 

Convert an angle to a distance along the equator or along a parallel at (geodetic) latitude.

Arguments:
  • deg - The angle (degrees).
  • radius - Mean earth radius (meter), an ellipsoid or datum (Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
  • lat - Parallel latitude (degrees90, str).
Returns:
Distance (meter, same units as radius or polar and equatorial radii) or 0.0 for near-polar lat.
Raises:
  • RangeError - Latitude lat outside valid range and rangerrors is True.
  • TypeError - Invalid radius.
  • ValueError - Invalid deg, radius or lat.

See Also: Function radians2m and m2degrees.

degrees360 (rad)

 

Convert radians to degrees and wrap [0..+360).

Arguments:
  • rad - Angle (radians).
Returns:
Angle, wrapped (degrees360).

degrees90 (rad)

 

Convert radians to degrees and wrap [-90..+90).

Arguments:
  • rad - Angle (radians).
Returns:
Angle, wrapped (degrees90).

deprecated_Property_RO (method)

 

Decorator for a DEPRECATED Property_RO.

Arguments:
  • method - The Property_RO.fget method (callable).
Returns:
The method DEPRECATED.

deprecated_class (cls_or_class)

 

Use inside __new__ or __init__ of a DEPRECATED class.

Arguments:
  • cls_or_class - The class (cls or Class).

Note: NOT a decorator!

deprecated_function (call)

 

Decorator for a DEPRECATED function.

Arguments:
  • call - The deprecated function (callable).
Returns:
The call DEPRECATED.

deprecated_method (call)

 

Decorator for a DEPRECATED method.

Arguments:
  • call - The deprecated method (callable).
Returns:
The call DEPRECATED.

deprecated_property_RO (method)

 

Decorator for a DEPRECATED property_RO.

Arguments:
  • method - The property_RO.fget method (callable).
Returns:
The method DEPRECATED.

e22f (e2)

 

Return f, the flattening for a given 1st eccentricity squared.

Arguments:
  • e2 - The (1st) eccentricity squared, signed (NINF < float < 1)
Returns:
The flattening (float or 0), e2 / (sqrt(e2 - 1) + 1).

e2f (e)

 

Return f, the flattening for a given 1st eccentricity.

Arguments:
  • e - The (1st) eccentricity (0 <= float < 1)
Returns:
The flattening (scalar or 0).

See Also: Function e22f.

egmGeoidHeights (GeoidHeights_dat)

 

Generate geoid egm*.pgm height tests from GeoidHeights.dat Test data for Geoids.

Arguments:
  • 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:

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.

Arguments:
  • lat - Latitude (degrees).
  • lon - Longitude (degrees).
  • timeout - Optional, query timeout (seconds).
Returns:
An Elevation2Tuple(elevation, data_source) or (None, "error") in case of errors.
Raises:
  • ValueError - Invalid timeout.

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- or other -Error as a string (str).

See Also: USGS Elevation Point Query Service, the FAQ, geoid.py, module geoids, classes GeoidG2012B, GeoidKarney and GeoidPGM.

enStr2 (easting, northing, prec, *extras)

 

DEPRECATED, use function pygeodesy.enstr2.

Decorators:
  • @deprecated_function

encodeEPSG (zone, hemipole='', band='')

 

DEPRECATED, use function epsg.encode.

Returns:
EPSG code (int).
Decorators:
  • @deprecated_function

enstr2 (easting, northing, prec, *extras, **wide_dot)

 

Return an MGRS/OSGR easting, northing string representations.

Arguments:
  • easting - Easting from false easting (meter).
  • northing - Northing from from false northing (meter).
  • prec - Precision, the number of decimal digits (int) or if negative, the number of units to drop, like MGRS PRECISION.
  • extras - Optional leading items (strs).
  • wide_dot - Optional keword argument wide=5 for the number of unit digits (int) and dot=False (bool) to insert a decimal point.
Returns:
extras + 2-tuple (str(easting), str(northing)) or + 2-tuple ("", "") for prec <= -wide.
Raises:
  • ValueError - Invalid easting, northing or prec.

Note: The easting and northing values are truncated, not rounded.

epoch2date (epoch)

 

Return the date for a reference frame epoch.

Arguments:
  • epoch - Fractional year (scalar).
Returns:
3-Tuple (year, month, day).
Raises:

Note: Any year is considered a leap year, i.e. having 29 days in February.

equidistant (lat0, lon0, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., exact=False, geodsolve=False, **name)

 

Return an EquidistantExact, EquidistantGeodSolve or (if Karney's geographiclib package is installed) an EquidistantKarney, otherwise an Equidistant instance.

Arguments:
  • lat0 - Latitude of center point (degrees90).
  • lon0 - Longitude of center point (degrees180).
  • datum - Optional datum or ellipsoid (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple) or scalar earth radius (meter).
  • exact - Return an EquidistantExact instance.
  • geodsolve - Return an EquidistantGeodSolve instance.
  • name - Optional name=NN for the projection (str).
Returns:
An EquidistantExact, EquidistantGeodSolve, EquidistantKarney or Equidistant instance.
Raises:

equirectangular (lat1, lon1, lat2, lon2, radius=6371008.771415, **adjust_limit_wrap)

 

Approximate the distance between two points using the Equirectangular Approximation / Projection.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple).
  • adjust_limit_wrap - Optionally, keyword arguments for function equirectangular4.
Returns:
Distance (meter, same units as radius or the datum's ellipsoid axes).
Raises:
  • TypeError - Invalid radius.

See Also: Function equirectangular4 for more details, the available options, errors, restrictions and other, approximate or accurate distance functions.

equirectangular3 (lat1, lon1, lat2, lon2, **options)

 

DEPRECATED, use function pygeodesy.equirectangular4.

Returns:
3-Tuple (distance2, delta_lat, delta_lon).
Decorators:
  • @deprecated_function

equirectangular4 (geohash1, geohash2, radius=6371008.771415)

 

Approximate the distance between two geohashes using the pygeodesy.equirectangular formula.

Arguments:
Returns:
Approximate distance (meter, same units as radius), see method Geohash.equirectangularTo.
Raises:
  • TypeError - If geohash1 or geohash2 is not a Geohash, LatLon or str.

equirectangular_ (lat1, lon1, lat2, lon2, **options)

 

DEPRECATED on 2024.05.25, use function pygeodesy.equirectangular4.

Decorators:
  • @deprecated_function

euclid (x, y)

 

Appoximate the norm sqrt(x**2 + y**2) by max(abs(x), abs(y)) + min(abs(x), abs(y)) * 0.4142....

Arguments:
Returns:
Appoximate norm (float or Fsum).

See Also: Function euclid_.

euclid_ (*xs)

 

Appoximate the norm sqrt(sum(x**2 for x in xs)) by cascaded euclid.

Arguments:
  • xs - X arguments (each scalar, an Fsum or Fsum2Tuple), all positional.
Returns:
Appoximate norm (float or Fsum).

See Also: Function euclid.

euclidean (lat1, lon1, lat2, lon2, radius=6371008.771415, adjust=True, wrap=False)

 

Approximate the Euclidean distance between two (spherical) points.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • adjust - Adjust the longitudinal delta by the cosine of the mean latitude (bool).
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as radius or the ellipsoid or datum axes).
Raises:
  • TypeError - Invalid radius.

See Also: Distance between two (spherical) points, functions euclid, euclidean_, cosineLaw, equirectangular, flatLocal / hubeny, flatPolar, haversine, thomas and vincentys and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

euclidean_ (geohash1, geohash2, **radius_adjust_wrap)

 

Approximate the distance between two geohashes using the pygeodesy.euclidean formula.

Arguments:
  • geohash1 - First geohash (Geohash, LatLon or str).
  • geohash2 - Second geohash (Geohash, LatLon or str).
  • radius_adjust_wrap - Optional keyword arguments for function pygeodesy.euclidean.
Returns:
Approximate distance (meter, same units as radius).
Raises:
  • TypeError - If geohash1 or geohash2 is not a Geohash, LatLon or str.

exception_chaining (exc=None)

 

Get an error's cause or the exception chaining setting.

Arguments:
  • exc - An error instance (Exception) or None.
Returns:
If exc is None, return True if exception chaining is enabled for PyGeodesy errors, False if turned off and None if not available. If exc is not None, return it's error cause or None if there is none.

Note: To enable exception chaining for pygeodesy errors, set env var PYGEODESY_EXCEPTION_CHAINING to any non-empty value prior to import pygeodesy.

excessAbc (A, b, c)

 

DEPRECATED on 2023.04.04, use function pygeodesy.excessAbc_.

Decorators:
  • @deprecated_function

excessAbc_ (A, b, c)

 

Compute the spherical excess E of a (spherical) triangle from two sides and the included (small) angle.

Arguments:
  • A - An interior triangle angle (radians).
  • b - Frist adjacent triangle side (radians).
  • c - Second adjacent triangle side (radians).
Returns:
Spherical excess (radians).
Raises:

excessCagnoli_ (a, b, c)

 

Compute the spherical excess E of a (spherical) triangle using Cagnoli's (D.34) formula.

Arguments:
  • a - First triangle side (radians).
  • b - Second triangle side (radians).
  • c - Third triangle side (radians).
Returns:
Spherical excess (radians).
Raises:

See Also: Function excessLHuilier_ and Spherical trigonometry.

excessGirard (A, B, C)

 

DEPRECATED on 2023.04.04, use function pygeodesy.excessGirard_.

Decorators:
  • @deprecated_function

excessGirard_ (A, B, C)

 

Compute the spherical excess E of a (spherical) triangle using Girard's formula.

Arguments:
  • A - First interior triangle angle (radians).
  • B - Second interior triangle angle (radians).
  • C - Third interior triangle angle (radians).
Returns:
Spherical excess (radians).
Raises:

See Also: Function excessLHuilier_ and Spherical trigonometry.

excessKarney (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or None.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Surface area, signed (square meter or the same units as radius squared) or the spherical excess (radians) if radius=0 or None.
Raises:
  • TypeError - Invalid radius.
  • UnitError - Invalid lat2 or lat1.
  • ValueError - Semi-circular longitudinal delta.

See Also: Functions excessKarney_ and excessQuad.

excessKarney_ (phi2, phi1, lam21)

 

Compute the spherical excess E of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator using Karney's method.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
Returns:
Spherical excess, signed (radians).
Raises:
  • ValueError - Semi-circular longitudinal delta lam21.

See Also: Function excessKarney and Area of a spherical polygon.

excessLHuilier (a, b, c)

 

DEPRECATED on 2023.04.04, use function pygeodesy.excessLHuilier_.

Decorators:
  • @deprecated_function

excessLHuilier_ (a, b, c)

 

Compute the spherical excess E of a (spherical) triangle using L'Huilier's's Theorem.

Arguments:
  • a - First triangle side (radians).
  • b - Second triangle side (radians).
  • c - Third triangle side (radians).
Returns:
Spherical excess (radians).
Raises:

excessQuad (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the surface area of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or None.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Surface area, signed (square meter or the same units as radius squared) or the spherical excess (radians) if radius=0 or None.
Raises:
  • TypeError - Invalid radius.
  • UnitError - Invalid lat2 or lat1.

See Also: Function excessQuad_ and excessKarney.

excessQuad_ (phi2, phi1, lam21)

 

Compute the spherical excess E of a (spherical) quadrilateral bounded by a segment of a great circle, two meridians and the equator.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
Returns:
Spherical excess, signed (radians).

See Also: Function excessQuad and Spherical trigonometry.

f2e2 (f)

 

Return e2, the 1st eccentricity squared for a given flattening.

Arguments:
  • f - Flattening (scalar < 1, negative for prolate).
Returns:
The signed, (1st) eccentricity squared (float < 1), f * (2 - f).

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

See Also: Eccentricity conversions and Flattening.

f2e22 (f)

 

Return e22, the 2nd eccentricity squared for a given flattening.

Arguments:
  • f - Flattening (scalar < 1, negative for prolate).
Returns:
The signed, 2nd eccentricity squared (float > -1 or INF), f * (2 - f) / (1 - f)**2.

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

See Also: Eccentricity conversions.

f2e32 (f)

 

Return e32, the 3rd eccentricity squared for a given flattening.

Arguments:
  • f - Flattening (scalar < 1, negative for prolate).
Returns:
The signed, 3rd eccentricity squared (float), f * (2 - f) / (1 + (1 - f)**2).

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

See Also: Eccentricity conversions.

f2f2 (f)

 

Return f2, the 2nd flattening for a given flattening.

Arguments:
  • f - Flattening (scalar < 1, negative for prolate).
Returns:
The signed, 2nd flattening (scalar or INF), f / (1 - f).

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

See Also: Eccentricity conversions and Flattening.

f2f_ (f)

 

Return f_, the inverse flattening for a given flattening.

Arguments:
  • f - Flattening (scalar < 1, negative for prolate).
Returns:
The inverse flattening (scalar or 0), 1 / f.

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

f2mul_ (x, *ys, **nonfinites)

 

Cascaded, accurate multiplication x * y * y ... for all ys.

Arguments:
Returns:
The cascaded TwoProduct (float, int or Fsum).

See Also: Equations 2.3

f2n (f)

 

Return n, the 3rd flattening for a given flattening.

Arguments:
  • f - Flattening (scalar < 1, negative for prolate).
Returns:
The signed, 3rd flattening (-1 <= float < 1), f / (2 - f).

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

See Also: Eccentricity conversions and Flattening.

f2product (two=None)

 

Turn accurate TwoProduct multiplication on or off.

Arguments:
  • two - If True, turn TwoProduct on, if False off or if None or omitted, keep the current setting.
Returns:
The previous setting (bool).

See Also: TwoProduct multiplication is based on the TwoProductFMA Algorithm 3.5 using function math.fma from Python 3.13 and later or an equivalent, slower implementation when not available.

fStr (floats, prec=6, fmt='f', ints=False, sep=', ')

 

DEPRECATED, use function fstr.

Decorators:
  • @deprecated_function

fStrzs (floatstr)

 

DEPRECATED, use function pygeodesy.fstrzs.

Decorators:
  • @deprecated_function

f_2f (f_)

 

Return f, the flattening for a given inverse flattening.

Arguments:
  • f_ - Inverse flattening (scalar >>> 1).
Returns:
The flattening (scalar or 0), 1 / f_.

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

facos1 (x)

 

Fast approximation of pygeodesy.acos1(x), scalar.

See Also: ShaderFastLibs.h.

false2f (value, name='value', false=True, Error=<type 'exceptions.ValueError'>)

 

DEPRECATED, use class Easting or Northing.

Decorators:
  • @deprecated_function

falsed2f (falsed=True, Error=<type 'exceptions.ValueError'>, **name_value)

 

DEPRECATED, use class Easting or Northing.

Convert a falsed east-/northing to non-negative float.

Arguments:
  • falsed - Value includes false origin (bool).
  • Error - Optional, overriding error (Exception).
  • name_value - One name=value pair.
Returns:
The value (float).
Decorators:
  • @deprecated_function
Raises:
  • Error - Invalid or negative name=value.

fasin1 (x)

 

Fast approximation of pygeodesy.asin1(x), scalar.

See Also: facos1.

fatan1 (x)

 

Fast approximation of atan(x) for 0 <= x < 1, unchecked.

See Also: ShaderFastLibs.h and Efficient approximations for the arctangent function, IEEE Signal Processing Magazine, 111, May 2006.

fatan2 (y, x)

 

Fast approximation of atan2(y, x), scalar.

fathom2m (fathoms)

 

Convert Imperial fathom to meter.

Arguments:
  • fathoms - Value in fathoms (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid fathoms.

See Also: Function toise2m, Fathom and Klafter.

favg (a, b, f=0.5, nonfinites=True)

 

Return the precise average of two values.

Arguments:
  • a - One (scalar, an Fsum or Fsum2Tuple).
  • b - Other (scalar, an Fsum or Fsum2Tuple).
  • f - Optional fraction (float).
  • nonfinites - Optional setting, see function fma.
Returns:
a + f * (b - a) (float).

fdot (xs, *ys, **start_f2product_nonfinites)

 

Return the precision dot product sum(xs[i] * ys[i] for i in range(len(xs))).

Arguments:
  • xs - Iterable of values (each scalar, an Fsum or Fsum2Tuple).
  • ys - Other values (each scalar, an Fsum or Fsum2Tuple), all positional.
  • start_f2product_nonfinites - Optional bias start=0 (scalar, an Fsum or Fsum2Tuple) and settings f2product=None (bool) and nonfinites=True (bool), see class Fsum.
Returns:
Dot product (float).
Raises:
  • LenError - Unequal len(xs) and len(ys).

See Also: Class Fdot, Algorithm 5.10 DotK and function math.sumprod in Python 3.12 and later.

fdot3 (xs, ys, zs, **start_f2product_nonfinites)

 

Return the (precision) dot product start + sum(xs[i] * ys[i] * zs[i] for i in range(len(xs))).

Arguments:
Returns:
Dot product (float).
Raises:
  • LenError - Unequal len(xs), len(ys) and/or len(zs).

See Also: Function fdot for further details.

fdot_ (*xys, **start_f2product_nonfinites)

 

Return the (precision) dot product sum(xys[i] * xys[i+1] for i in range(0, len(xys), 2)).

Arguments:
  • xys - Pairwise values (each scalar, an Fsum or Fsum2Tuple), all positional.
Returns:
Dot product (float).

See Also: Function fdot for further details.

fhorner (x, *cs, **incx)

 

Horner form evaluation of polynomial sum(cs[i] * x**i for i=0..n) as in- or decreasing exponent sum(... i=n..0), where n = len(cs) - 1.

Returns:
Horner sum (float).

See Also: Class Fhorner for further details.

fidw (xs, ds, beta=2)

 

Interpolate using Inverse Distance Weighting (IDW).

Arguments:
  • xs - Known values (each scalar, an Fsum or Fsum2Tuple).
  • ds - Non-negative distances (each scalar, an Fsum or Fsum2Tuple).
  • beta - Inverse distance power (int, 0, 1, 2, or 3).
Returns:
Interpolated value x (float).
Raises:
  • LenError - Unequal or zero len(ds) and len(xs).
  • TypeError - An invalid ds or xs.
  • ValueError - Invalid beta, negative ds or weighted ds below EPS.

Note: Using beta=0 returns the mean of xs.

flatLocal (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True, wrap=False)

 

Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • datum - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • scaled - Scale prime_vertical by cos(phi) (bool), see method pygeodesy.Ellipsoid.roc2_.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as the datum's or ellipsoid axes).
Raises:
  • TypeError - Invalid datum.

Note: The meridional and prime_vertical radii of curvature are taken and scaled at the mean of both latitude.

See Also: Functions flatLocal_ or hubeny_, cosineLaw, equirectangular, euclidean, flatPolar, haversine, thomas and vincentys, method Ellipsoid.distance2 and local, flat earth approximation.

flatLocal_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True)

 

Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.

Arguments:
Returns:
Angular distance (radians).
Raises:
  • TypeError - Invalid datum.

Note: The meridional and prime_vertical radii of curvature are taken and scaled at the mean of both latitude.

See Also: Functions flatLocal or hubeny, cosineLaw_, flatPolar_, euclidean_, haversine_, thomas_ and vincentys_ and local, flat earth approximation.

flatPolar (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the distance between two (spherical) points using the polar coordinate flat-Earth formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and lat2 and lon2 (bool).
Returns:
Distance (meter, same units as radius or the datum's or ellipsoid axes).
Raises:
  • TypeError - Invalid radius.

flatPolar_ (phi2, phi1, lam21)

 

Compute the angular distance between two (spherical) points using the polar coordinate flat-Earth formula.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
Returns:
Angular distance (radians).

float0 (*xs)

 

DEPRECATED on 2023.04.21, use function pygeodesy.float0_.

Decorators:
  • @deprecated_function

float_ (*fs, **sets)

 

Get scalars as float or intern'ed float.

Arguments:
  • fs - One more values (scalar), all positional.
  • sets - Use sets=True to intern each fs, otherwise don't intern.
Returns:
A single float if only one fs is given, otherwise a tuple of floats.
Raises:
  • TypeError - Some fs is not scalar.

fma (x, y, z, **nonfinites)

 

Fused-multiply-add, using math.fma(x, y, z) in Python 3.13+ or an equivalent implementation.

Arguments:
Returns:
(x * y) + z (float or Fsum).

fmean (xs)

 

Compute the accurate mean sum(xs) / len(xs).

Arguments:
Returns:
Mean value (float).
Raises:
  • LenError - No xs values.
  • OverflowError - Partial 2sum overflow.

fmean_ (*xs, **nonfinites)

 

Compute the accurate mean sum(xs) / len(xs).

See Also: Function fmean for further details.

fpolynomial (x, *cs, **over_f2product_nonfinites)

 

Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)) [/ over].

Arguments:
  • over_f2product_nonfinites - Optional final divisor over=None (non-zero scalar) and other settings, see class Fpolynomial.
Returns:
Polynomial value (float or Fpolynomial).

fpowers (x, n, alts=0)

 

Return a series of powers [x**i for i=1..n], note 1..!

Arguments:
  • x - Value (scalar, an Fsum or Fsum2Tuple).
  • n - Highest exponent (int).
  • alts - Only alternating powers, starting with this exponent (int).
Returns:
Tuple of powers of x (each type(x)).
Raises:
  • TypeError - Invalid x or n not int.
  • ValueError - Non-finite x or invalid n.

fprod (xs, start=1)

 

Iterable product, like math.prod or numpy.prod.

Arguments:
  • xs - Iterable of values to be multiplied (each scalar, an Fsum or Fsum2Tuple).
  • start - Initial value, also the value returned for an empty xs (scalar).
Returns:
The product (float or Fsum).

See Also: NumPy.prod.

fractional (points, fi, j=None, wrap=None, LatLon=None, Vector=None, **kwds)

 

Return the point at a given fractional index.

Arguments:
  • points - The points (LatLon[], Numpy2LatLon[], Tuple2LatLon[], Cartesian[], Vector3d[], Vector3Tuple[]).
  • fi - The fractional index (FIx, float or int).
  • j - Optionally, index of the other point (int).
  • wrap - If True, wrap or normalize and unroll the {points} (bool) or None for a backward compatible LatLon2Tuple or LatLon with averaged lat- and longitudes. Use True or False to get the fractional point computed by method points[fi].intermediateTo.
  • LatLon - Optional class to return the intermediate, fractional point (LatLon) or None.
  • Vector - Optional class to return the intermediate, fractional point (Cartesian, Vector3d) or None.
  • kwds - Optional, additional LatLon or Vector keyword arguments, ignored if both LatLon and Vector are None.
Returns:
A LatLon2Tuple(lat, lon) if wrap, LatLon and Vector all are None, the defaults.

An instance of LatLon if not None or an instance of Vector if not None.

Otherwise with wrap either True or False and LatLon and Vector both None, an instance of points' (sub-)class intermediateTo fractional.

Summarized as follows:

>>>  wrap  | LatLon | Vector | returned type/value
#   -------+--------+--------+--------------+------
#          |        |        | LatLon2Tuple | favg
#    None  |  None  |  None  |   or**       |
#          |        |        | Vector3Tuple | favg
#    None  | LatLon |  None  | LatLon       | favg
#    None  |  None  | Vector | Vector       | favg
#   -------+--------+--------+--------------+------
#    True  |  None  |  None  | points'      | .iTo
#    True  | LatLon |  None  | LatLon       | .iTo
#    True  |  None  | Vector | Vector       | .iTo
#   -------+--------+--------+--------------+------
#    False |  None  |  None  | points'      | .iTo
#    False | LatLon |  None  | LatLon       | .iTo
#    False |  None  | Vector | Vector       | .iTo
# _____
# favg) averaged lat, lon or x, y, z values
# .iTo) value from points[fi].intermediateTo
# **) depends on base class of points[fi]
Raises:
  • IndexError - Fractional index fi invalid or points not subscriptable or not closed.
  • TypeError - Invalid LatLon, Vector or kwds argument.

See Also: Class FIx and method FIx.fractional.

frandoms (n, seeded=None)

 

Generate n (long) lists of random floats.

Arguments:
  • n - Number of lists to generate (int, non-negative).
  • seeded - If scalar, use random.seed(seeded) or if True, seed using today's year-day.

See Also: Hettinger.

frange (start, number, step=1)

 

Generate a range of floats.

Arguments:
  • start - First value (float).
  • number - The number of floats to generate (int).
  • step - Increment value (float).
Returns:
A generator (floats).

See Also: NumPy.prod.

frechet_ (point1s, point2s, distance=None, units='')

 

Compute the discrete Fréchet distance between two paths, each given as a set of points.

Arguments:
  • point1s - First set of points (LatLon[], Numpy2LatLon[], Tuple2LatLon[] or other[]).
  • point2s - Second set of points (LatLon[], Numpy2LatLon[], Tuple2LatLon[] or other[]).
  • distance - Callable returning the distance between a point1s and a point2s point (signature (point1, point2)).
  • units - Optional, the distance units (Unit or str).
Returns:
A Frechet6Tuple(fd, fi1, fi2, r, n, units) where fi1 and fi2 are type int indices into point1s respectively point2s.
Raises:

Note: Function frechet_ does not support fractional indices for intermediate point1s and point2s.

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

fremainder (x, y)

 

Remainder in range [-y / 2, y / 2].

Arguments:
  • x - Numerator (scalar).
  • y - Modulus, denominator (scalar).
Returns:
Remainder (scalar, preserving signed 0.0) or NAN for any non-finite x.
Raises:
  • ValueError - Infinite or near-zero y.

See Also: Karney's Math.remainder and Python 3.7+ math.remainder.

fstr (floats, prec=6, fmt='F', ints=False, sep=', ', strepr=None, force=True)

 

Convert one or more floats to string, optionally stripped of trailing zero decimals.

Arguments:
  • floats - Single or a list, sequence, tuple, etc. (scalars).
  • prec - The float precision, number of decimal digits (0..9). Trailing zero decimals are stripped if prec is positive, but kept for negative prec values. In addition, trailing decimal zeros are stripped for alternate, form '#'.
  • fmt - Optional float format (letter).
  • ints - Optionally, remove the decimal dot for int values (bool).
  • sep - Separator joining the floats (str).
  • strepr - Optional callable to format non-floats (typically repr, str) or None to raise a TypeError and used only if force is not True.
  • force - If True, format all floats using fmt, otherwise use strepr for non-floats (bool).
Returns:
The sep.join(strs(floats, ...) joined (str) or single strs((floats,), ...) (str) if floats is scalar.

fstrzs (efstr, ap1z=False)

 

Strip trailing zero decimals from a float string.

Arguments:
  • efstr - Float with or without exponent (str).
  • ap1z - Append the decimal point and one zero decimal if the efstr is all digits (bool).
Returns:
Float (str).

fsum (xs, nonfinites=None, **floats)

 

Precision floating point summation from Python's math.fsum.

Arguments:
  • xs - Iterable of items to add (each scalar, an Fsum or Fsum2Tuple).
  • nonfinites - Use nonfinites=True if non-finites are OK, if False non-finites raise an Overflow-/ValueError or if None, nonfiniterrors applies (bool or None).
  • floats - DEPRECATED keyword argument floats=False (bool), use keyword argument nonfinites=False instead.
Returns:
Precision fsum (float).
Raises:
  • OverflowError - Infinite xs item or intermediate math.fsum overflow.
  • TypeError - Invalid xs item.
  • ValueError - Invalid or NAN xs item.

See Also: Function nonfiniterrors, class Fsum and methods Fsum.nonfinites, Fsum.fsum, Fsum.fadd and Fsum.fadd_.

fsum1 (xs, **nonfinites)

 

Precision floating point summation, 1-primed.

Arguments:
  • xs - Iterable of items to add (each scalar, an Fsum or Fsum2Tuple).
  • nonfinites - Use nonfinites=True if non-finites are OK (bool).

See Also: Function fsum for further details.

fsum1_ (*xs, **nonfinites)

 

Precision floating point summation of all positional items, 1-primed.

Arguments:
  • xs - Items to add (each scalar, an Fsum or Fsum2Tuple), all positional.
  • nonfinites - Use nonfinites=True if non-finites are OK (bool).

See Also: Function fsum_ for further details.

fsum1f_ (*xs)

 

Precision floating point summation of all positional items, 1-primed and with non-finites OK.

See Also: Function fsum_ for further details.

fsum_ (*xs, **nonfinites)

 

Precision floating point summation of all positional items.

Arguments:
  • xs - Items to add (each scalar, an Fsum or Fsum2Tuple), all positional.
  • nonfinites - Use nonfinites=True if non-finites are OK (bool).

See Also: Function fsum for further details.

fsumf_ (*xs)

 

Precision floating point summation of all positional items with non-finites OK.

Arguments:
  • xs - Items to add (each scalar, an Fsum or Fsum2Tuple), all positional.

See Also: Function fsum_ for further details.

ft2m (feet, usurvey=False, pied=False, fuss=False)

 

Convert International, US Survey, French or German feet to meter.

Arguments:
  • feet - Value in feet (scalar).
  • usurvey - If True, convert US Survey foot else ...
  • pied - If True, convert French pied-du-Roi else ...
  • fuss - If True, convert German Fuss, otherwise International foot to meter.
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid feet.

furlong2m (furlongs)

 

Convert a furlong to meter.

Arguments:
  • furlongs - Value in furlongs (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid furlongs.

geoidHeight2 (lat, lon, model=0, timeout=2.0)

 

Get the NAVD88 geoid height at an NAD83 location.

Arguments:
  • 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.
Raises:
  • ValueError - Invalid timeout.

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-, URL- or other -Error as a string (str).

See Also: NOAA National Geodetic Survey, Geoid, USGS10mElev.py, module geoids, classes GeoidG2012B, GeoidKarney and GeoidPGM.

gnomonic (lat0, lon0, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., exact=False, geodsolve=False, **name)

 

Return a GnomonicExact or (if Karney's geographiclib package is installed) a GnomonicKarney, otherwise a Gnomonic instance.

Arguments:
  • lat0 - Latitude of center point (degrees90).
  • lon0 - Longitude of center point (degrees180).
  • datum - Optional datum or ellipsoid (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple) or scalar earth radius (meter).
  • exact - Return a GnomonicExact instance.
  • geodsolve - Return a GnomonicGeodSolve instance.
  • name - Optional name=NN for the projection (str).
Returns:
A GnomonicExact, GnomonicGeodSolve, GnomonicKarney or Gnomonic instance.
Raises:

grades (rad)

 

Convert radians to grades (aka gons or gradians).

Arguments:
  • rad - Angle (radians).
Returns:
Angle (grades).

grades2degrees (gon)

 

Convert grades (aka gons or gradians) to degrees.

Arguments:
  • gon - Angle (grades).
Returns:
Angle (degrees).

grades2radians (gon)

 

Convert grades (aka gons or gradians) to radians.

Arguments:
  • gon - Angle (grades).
Returns:
Angle (radians).

grades400 (rad)

 

Convert radians to grades (aka gons or gradians) and wrap [0..+400).

Arguments:
  • rad - Angle (radians).
Returns:
Angle, wrapped (grades).

ha2acre (ha)

 

Convert hectare to acre.

Arguments:
  • ha - Value in hectare (scalar).
Returns:
Value in acres (float).
Raises:
  • ValueError - Invalid ha.

ha2m2 (ha)

 

Convert hectare to square meter.

Arguments:
  • ha - Value in hectare (scalar).
Returns:
Value in meter^2 (float).
Raises:
  • ValueError - Invalid ha.

halfs2 (str2)

 

Split a string in 2 halfs.

Arguments:
  • str2 - String to split (str).
Returns:
2-Tuple (_1st, _2nd) half (str).
Raises:
  • ValueError - Zero or odd len(str2).

hartzell (pov, los=False, earth=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., **name_LatLon_and_kwds)

 

Compute the intersection of the earth's surface and a Line-Of-Sight from a Point-Of-View in space.

Arguments:
  • pov - Point-Of-View outside the earth (LatLon, Cartesian, Ecef9Tuple or Vector3d).
  • los - Line-Of-Sight, direction to earth (Los, Vector3d), True for the normal, plumb onto the surface or False or None to point to the center of the earth.
  • earth - The earth model (Datum, Ellipsoid, Ellipsoid2, a_f2Tuple or a scalar earth radius in meter).
  • name_LatLon_and_kwds - Optional name="hartzell" (str), class LatLon=None to return the intersection and optionally, additional LatLon keyword arguments, include the datum if different from and to convert from earth.
Returns:
The intersection (Vector3d, pov's cartesian type or the given LatLon instance) with attribute height set to the distance to the pov.
Raises:
  • IntersectionError - Invalid pov or pov inside the earth or invalid los or los points outside or away from the earth.
  • TypeError - Invalid earth, ellipsoid or datum.

See Also: Class Los, functions tyr3d and hartzell4 and methods Ellipsoid.hartzell4, any Cartesian.hartzell and LatLon.hartzell.

hartzell4 (pov, los=False, tri_biax=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., **name)

 

Compute the intersection of a tri-/biaxial ellipsoid and a Line-Of-Sight from a Point-Of-View outside.

Arguments:
Returns:
Vector4Tuple(x, y, z, h) on the tri-/biaxial's surface, with h the distance from pov to (x, y, z) along the los, all in meter, conventionally.
Raises:
  • TriaxialError - Invalid pov or pov inside the tri-/biaxial or invalid los or los points outside or away from the tri-/biaxial.
  • TypeError - Invalid tri_biax, ellipsoid or datum.

hausdorff_ (model, target, both=False, early=True, seed=None, units='', distance=None, point=<function _point at 0x7f7af8a96e50>)

 

Compute the directed or symmetric Hausdorff distance between 2 sets of points with or without early breaking and random sampling.

Arguments:
  • 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, the distance units (Unit or 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.

hav (rad)

 

Return the haversine of an angle.

Arguments:
  • rad - Angle (radians).
Returns:
sin(rad / 2)**2.

haversine (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the distance between two (spherical) points using the Haversine formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as radius).
Raises:
  • TypeError - Invalid radius.

See Also: Distance between two (spherical) points, functions cosineLaw, equirectangular, euclidean, flatLocal / hubeny, flatPolar, thomas and vincentys and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

Note: See note at function vincentys_.

haversine_ (geohash1, geohash2, **radius_wrap)

 

Compute the great-circle distance between two geohashes using the pygeodesy.haversine formula.

Arguments:
  • geohash1 - First geohash (Geohash, LatLon or str).
  • geohash2 - Second geohash (Geohash, LatLon or str).
  • radius_wrap - Optional keyword arguments for function pygeodesy.haversine.
Returns:
Great-circle distance (meter, same units as radius).
Raises:
  • TypeError - If geohash1 or geohash2 is not a Geohash, LatLon or str.

heightOf (angle, distance, radius=6371008.771415)

 

Determine the height above the (spherical) earth' surface after traveling along a straight line at a given tilt.

Arguments:
  • 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.

heightOrthometric (h_loc, N)

 

Get the orthometric height H, the height above the geoid, earth surface.

Arguments:
  • h_loc - The height above the ellipsoid (meter) or an ellipsoidal location (LatLon or Cartesian with a height or h attribute), otherwise 0 meter.
  • N - The geoid height (meter), the height of the geoid above the ellipsoid at the same h_loc location.
Returns:
Orthometric height H = h - N (meter, same units as h and N).

horizon (height, radius=6371008.771415, refraction=False)

 

Determine the distance to the horizon from a given altitude above the (spherical) earth.

Arguments:
  • 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.

hstr (height, prec=2, fmt='%+.*f', ints=False, m='')

 

Return a string for the height value.

Arguments:
  • height - Height value (float).
  • prec - The float precision, number of decimal digits (0..9). Trailing zero decimals are stripped if prec is positive, but kept for negative prec values.
  • fmt - Optional float format (letter).
  • ints - Optionally, remove the decimal dot for int values (bool).
  • m - Optional unit of the height (str).

hubeny (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True, wrap=False)

 

Compute the distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • datum - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • scaled - Scale prime_vertical by cos(phi) (bool), see method pygeodesy.Ellipsoid.roc2_.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as the datum's or ellipsoid axes).
Raises:
  • TypeError - Invalid datum.

Note: The meridional and prime_vertical radii of curvature are taken and scaled at the mean of both latitude.

See Also: Functions flatLocal_ or hubeny_, cosineLaw, equirectangular, euclidean, flatPolar, haversine, thomas and vincentys, method Ellipsoid.distance2 and local, flat earth approximation.

hubeny_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., scaled=True)

 

Compute the angular distance between two (ellipsoidal) points using the ellipsoidal Earth to plane projection aka Hubeny formula.

Arguments:
Returns:
Angular distance (radians).
Raises:
  • TypeError - Invalid datum.

Note: The meridional and prime_vertical radii of curvature are taken and scaled at the mean of both latitude.

See Also: Functions flatLocal or hubeny, cosineLaw_, flatPolar_, euclidean_, haversine_, thomas_ and vincentys_ and local, flat earth approximation.

hypot1 (x)

 

Compute the norm sqrt(1 + x**2).

Arguments:
Returns:
Norm (float or Fhypot).

hypot2 (x, y)

 

Compute the squared norm x**2 + y**2.

Arguments:
Returns:
x**2 + y**2 (float).

hypot2_ (*xs)

 

Compute the squared norm fsum(x**2 for x in xs).

Arguments:
  • xs - Components (each scalar, an Fsum or Fsum2Tuple), all positional.
Returns:
Squared norm (float).

See Also: Class Fpowers for further details.

hypot3 (x, y, z)

 

DEPRECATED, use function pygeodesy.hypot_.

Decorators:
  • @deprecated_function

hypot_ (*xs)

 

Compute the norm sqrt(sum(x**2 for x in xs)).

Similar to Python 3.8+ n-dimension math.hypot, but exceptions, nan and infinite values are handled differently.

Arguments:
  • xs - X arguments (scalars), all positional.
Returns:
Norm (float).
Raises:
  • OverflowError - Partial 2sum overflow.
  • ValueError - Invalid or no xs values.

Note: The Python 3.8+ Euclidian distance math.dist 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)

 

DEPRECATED, use function pygeodesy.instr.

Decorators:
  • @deprecated_function

instr (inst, *args, **kwds)

 

Return the string representation of an instantiation.

Arguments:
  • inst - The instance (any type).
  • args - Optional positional arguments.
  • kwds - Optional keyword arguments.
Returns:
Representation (str).

int1s (x)

 

Count the number of 1-bits in an int, unsigned.

Note: int1s(-x) == int1s(abs(x)).

intersection2 (lat1, lon1, bearing1, lat2, lon2, bearing2, datum=None, wrap=False, small=100000.0)

 

Conveniently compute the intersection of two lines each defined by a (geodetic) point and a bearing from North, using either ...

1) vector3d.intersection3d3 for small distances (below 100 Km or about 0.88 degrees) or if no datum is specified, or ...

2) sphericalTrigonometry.intersection for a spherical datum or a scalar datum representing the earth radius, conventionally in meter or ...

3) sphericalNvector.intersection if datum is a negative scalar, (negative) earth radius, conventionally in meter or ...

4) ellipsoidalKarney.intersection3 for an ellipsoidal datum and if Karney's geographiclib is installed, otherwise ...

5) ellipsoidalExact.intersection3, provided datum is ellipsoidal.

Arguments:
  • lat1 - Latitude of the first point (degrees).
  • lon1 - Longitude of the first point (degrees).
  • bearing1 - Bearing at the first point (compass degrees360).
  • lat2 - Latitude of the second point (degrees).
  • lon2 - Longitude of the second point (degrees).
  • bearing2 - Bearing at the second point (compass degrees360).
  • datum - Optional datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) or scalar earth radius (meter, same units as radius1 and radius2) or None.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
  • small - Upper limit for small distances (meter).
Returns:
Intersection point (LatLon2Tuple(lat, lon)).
Raises:
  • IntersectionError - No or an ambiguous intersection or colinear, parallel or otherwise non-intersecting lines.
  • TypeError - Invalid datum.
  • UnitError - Invalid lat1, lon1, bearing1, lat2, lon2 or bearing2.

See Also: Method RhumbLine.intersection2.

intersection3d3 (start1, end1, start2, end2, eps=2.220446049250313e-16, useZ=True, **Vector_and_kwds)

 

Compute the intersection point of two (2- or 3-D) lines, each defined by two points or by a point and a bearing.

Arguments:
  • start1 - Start point of the first line (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • end1 - End point of the first line (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple) or the bearing at start1 (compass degrees).
  • start2 - Start point of the second line (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • end2 - End point of the second line (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple) or the bearing at start2 (Ccompass degrees).
  • eps - Tolerance for skew line distance and length (EPS).
  • useZ - If True, use the Z components, otherwise force z=INT0 (bool).
  • Vector_and_kwds - Optional class Vector=None to return the intersection points and optional, additional Vector keyword arguments, otherwise start1's (sub-)class.
Returns:
An Intersection3Tuple(point, outside1, outside2) with point an instance of Vector or start1's (sub-)class.
Raises:
  • IntersectionError - Invalid, skew, non-co-planar or otherwise non-intersecting lines.

Note: The outside values is 0 for lines specified by point and bearing.

See Also: Line-line intersection and line-line distance, skew lines and point-line distance.

intersections2 (center1, radius1, center2, radius2, sphere=True, **Vector_and_kwds)

 

Compute the intersection of two spheres or circles, each defined by a (3-D) center point and a radius.

Arguments:
  • center1 - Center of the first sphere or circle (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • radius1 - Radius of the first sphere or circle (same units as the center1 coordinates).
  • center2 - Center of the second sphere or circle (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • radius2 - Radius of the second sphere or circle (same units as the center1 and center2 coordinates).
  • sphere - If True, compute the center and radius of the intersection of two spheres. If False, ignore the z-component and compute the intersection of two circles (bool).
  • Vector_and_kwds - Optional class Vector=None to return the intersection points and optionally, additional Vector keyword arguments, otherwise center1's (sub-)class.
Returns:
If sphere is True, a 2-tuple of the center and radius of the intersection of the spheres. For abutting circles, radius is 0.0 and center is the radical center.

If sphere is False, a 2-tuple with the two intersection points of the circles. For abutting circles, both points are the same instance, aka the radical center.

Raises:
  • IntersectionError - Concentric, invalid or non-intersecting spheres or circles.
  • TypeError - Invalid center1 or center2.
  • UnitError - Invalid radius1 or radius2.

See Also: Sphere-Sphere and Circle-Circle Intersection.

isBoolean (obj)

 

Check for Boolean composites.

Arguments:
  • obj - The object (any type).
Returns:
True if obj is BooleanFHP, BooleanGH or some other composite, False otherwise.

isCartesian (obj, ellipsoidal=None)

 

Is object some Cartesian?

Arguments:
  • obj - The object (any type).
  • ellipsoidal - If None, return the type of any Cartesian, if True, only an ellipsoidal Cartesian type or if False, only a spherical Cartesian type.
Returns:
type(obj if a Cartesian of the required type, False if a Cartesian of an other type or {None} otherwise.

isDEPRECATED (obj)

 

Is object a DEPRECATED class, method or function?

Returns:
True if DEPRECATED, {False} if not or None if undetermined.

isError (exc)

 

Check a (caught) exception.

Arguments:
  • exc - The exception C({Exception}).
Returns:
True if exc is a pygeodesy error, False if exc is a standard Python error of None if neither.

isLatLon (obj, ellipsoidal=None)

 

Is object some LatLon?

Arguments:
  • obj - The object (any type).
  • ellipsoidal - If None, return the type of any LatLon, if True, only an ellipsoidal LatLon type or if False, only a spherical LatLon type.
Returns:
type(obj if a LatLon of the required type, False if a LatLon of an other type or {None} otherwise.

isNumpy2 (obj)

 

Check for a Numpy2LatLon points wrapper.

Arguments:
  • obj - The object (any type).
Returns:
True if obj is a Numpy2LatLon instance, False otherwise.

isNvector (obj, ellipsoidal=None)

 

Is object some Nvector?

Arguments:
  • obj - The object (any type).
  • ellipsoidal - If None, return the type of any Nvector, if True, only an ellipsoidal Nvector type or if False, only a spherical Nvector type.
Returns:
type(obj if an Nvector of the required type, False if an Nvector of an other type or {None} otherwise.

isPoints2 (obj)

 

Check for a LatLon2psxy points wrapper.

Arguments:
  • obj - The object (any type).
Returns:
True if obj is a LatLon2psxy instance, False otherwise.

isTuple2 (obj)

 

Check for a Tuple2LatLon points wrapper.

Arguments:
  • obj - The object (any).
Returns:
True if obj is a Tuple2LatLon instance, False otherwise.

isantipode (lat1, lon1, lat2, lon2, eps=2.220446049250313e-16)

 

Check whether two points are antipodal, on diametrically opposite sides of the earth.

Arguments:
  • 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: Functions isantipode_ and antipode.

isantipode_ (phi1, lam1, phi2, lam2, eps=2.220446049250313e-16)

 

Check whether two points are antipodal, on diametrically opposite sides of the earth.

Arguments:
  • phi1 - Latitude of one point (radians).
  • lam1 - Longitude of one point (radians).
  • phi2 - Latitude of the other point (radians).
  • lam2 - Longitude of the other point (radians).
  • eps - Tolerance for near-equality (radians).
Returns:
True if points are antipodal within the eps tolerance, False otherwise.

See Also: Functions isantipode and antipode_.

isbool (obj)

 

Is object a boolean?

Arguments:
  • obj - The object (any type).
Returns:
True if boolean, False otherwise.

isclockwise (points, adjust=False, wrap=True)

 

Determine the direction of a path or polygon.

Arguments:
  • points - The path or polygon points (LatLon[]).
  • adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
  • wrap - If True, wrap or normalize and unroll the points (bool).
Returns:
True if points are clockwise, False otherwise.
Raises:
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.
  • ValueError - The points enclose a pole or zero area.

iscolinearWith (point, point1, point2, eps=2.220446049250313e-16, useZ=True)

 

Check whether a point is colinear with two other (2- or 3-D) points.

Arguments:
  • point - The point (Vector3d, Vector3Tuple or Vector4Tuple).
  • point1 - First point (Vector3d, Vector3Tuple or Vector4Tuple).
  • point2 - Second point (Vector3d, Vector3Tuple or Vector4Tuple).
  • eps - Tolerance (scalar), same units as x, y and z.
  • useZ - If True, use the Z components, otherwise force z=INT0 (bool).
Returns:
True if point is colinear point1 and point2, False otherwise.
Raises:
  • TypeError - Invalid point, point1 or point2.

See Also: Function nearestOn.

iscomplex (obj, both=False)

 

Is object a complex or complex literal str?

Arguments:
  • obj - The object (any type).
  • both - If True, check complex str (bool).
Returns:
True if complex, False otherwise.

isconvex (points, adjust=False, wrap=False)

 

Determine whether a polygon is convex.

Arguments:
  • points - The polygon points (LatLon[]).
  • adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
  • wrap - If True, wrap or normalize and unroll the points (bool).
Returns:
True if points are convex, False otherwise.
Raises:
  • CrossError - Some points are colinear.
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.

isconvex_ (points, adjust=False, wrap=False)

 

Determine whether a polygon is convex and clockwise.

Arguments:
  • points - The polygon points (LatLon[]).
  • adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
  • wrap - If True, wrap or normalize and unroll the points (bool).
Returns:
+1 if points are convex clockwise, -1 for convex counter-clockwise points, 0 otherwise.
Raises:
  • CrossError - Some points are colinear.
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.

isenclosedBy (point, points, wrap=False)

 

Determine whether a point is enclosed by a polygon or composite.

Arguments:
  • point - The point (LatLon or 2-tuple (lat, lon)).
  • points - The polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
  • wrap - If True, wrap or normalize and unroll the points (bool).
Returns:
True if the point is inside the polygon or composite, False otherwise.
Raises:
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid point, lat- or longitude.

See Also: Functions pygeodesy.isconvex and pygeodesy.ispolar especially if the points may enclose a pole or wrap around the earth longitudinally, methods sphericalNvector.LatLon.isenclosedBy, sphericalTrigonometry.LatLon.isenclosedBy and MultiDop GeogContainPt (Shapiro et.al. 2009, JTECH and Potvin et al. 2012, JTECH).

isenclosedby (point, points, wrap=False)

 

DEPRECATED, use function pygeodesy.isenclosedBy.

Decorators:
  • @deprecated_function

isfinite (obj)

 

Check a finite scalar, complex, ... value.

Arguments:
Returns:
False if obj is INF, NINF or NAN, True otherwise.
Raises:
  • TypeError - Non-scalar and non-complex obj.

isfloat (obj, both=False)

 

Is object a float or float literal str?

Arguments:
  • obj - The object (any type).
  • both - If True, check float str (bool).
Returns:
True if float, False otherwise.

isinstanceof (obj, *Classes)

 

Is object an instance of one of the Classes?

Arguments:
  • obj - The object (any type).
  • Classes - One or more classes (Class).
Returns:
type(obj if one of the Classes, None otherwise.

isint (obj, both=False)

 

Is object an int or integer float value?

Arguments:
  • obj - The object (any type).
  • both - If True, check float and Fsum type and value (bool).
Returns:
True if int or integer float or Fsum, False otherwise.

Note: Both isint(True) and isint(False) return False (and no longer True).

isint0 (obj, both=False)

 

Check for INT0 or int(0) value.

Arguments:
  • obj - The object (any type).
  • both - If true, also check float(0) (bool).
Returns:
True if obj is INT0, int(0) or float(0), False otherwise.

isiterable (obj, strict=False)

 

Is object iterable?

Arguments:
  • obj - The object (any type).
  • strict - If True, check class attributes (bool).
Returns:
True if iterable, False otherwise.

isiterablen (obj, strict=False)

 

Is object iterable and has length?

Arguments:
  • obj - The object (any type).
  • strict - If True, check class attributes (bool).
Returns:
True if iterable with length, False otherwise.

isiterabletype (obj, method='__iter__')

 

Is object an instance of an iterable class or type?

Arguments:
  • obj - The object (any type).
  • method - The name of the required method (str).
Returns:
The base-class if iterable, None otherwise.

islistuple (obj, minum=0)

 

Is object a list or tuple with non-zero length?

Arguments:
  • obj - The object (any type).
  • minum - Minimal len required C({int}).
Returns:
True if a list or tuple with len at least minum, False otherwise.

isnear0 (x, eps0=4.930380657631324e-32)

 

Is x near zero within a tolerance?

Arguments:
  • x - Value (scalar).
  • eps0 - Near-zero tolerance (EPS0).
Returns:
True if abs(x) < eps0, False otherwise.

See Also: Function isnon0.

isnear1 (x, eps1=4.930380657631324e-32)

 

Is x near one within a tolerance?

Arguments:
  • x - Value (scalar).
  • eps1 - Near-one tolerance (EPS0).
Returns:
isnear0(x - 1, eps0=eps1).

See Also: Function isnear0.

isnear90 (x, eps90=4.930380657631324e-32)

 

Is x near 90 within a tolerance?

Arguments:
  • x - Value (scalar).
  • eps90 - Near-90 tolerance (EPS0).
Returns:
isnear0(x - 90, eps0=eps90).

See Also: Function isnear0.

isneg0 (x)

 

Check for NEG0, negative 0.0.

Arguments:
  • x - Value (scalar).
Returns:
True if x is NEG0 or -0.0, False otherwise.

isninf (x)

 

Check for NINF, negative INF.

Arguments:
  • x - Value (scalar).
Returns:
True if x is NINF or -inf, False otherwise.

isnon0 (x, eps0=4.930380657631324e-32)

 

Is x non-zero with a tolerance?

Arguments:
  • x - Value (scalar).
  • eps0 - Non-zero tolerance (EPS0).
Returns:
True if abs(x) > eps0, False otherwise.

See Also: Function isnear0.

isnormal (lat, lon, eps=0)

 

Check whether lat and lon are within their respective normal range in degrees.

Arguments:
  • lat - Latitude (degrees).
  • lon - Longitude (degrees).
  • eps - Optional tolerance degrees).
Returns:
True if (abs(lat) + eps) <= 90 and (abs(lon) + eps) <= 180, False otherwise.

See Also: Functions isnormal_ and normal.

isnormal_ (phi, lam, eps=0)

 

Check whether phi and lam are within their respective normal range in radians.

Arguments:
  • phi - Latitude (radians).
  • lam - Longitude (radians).
  • eps - Optional tolerance radians).
Returns:
True if (abs(phi) + eps) <= PI/2 and (abs(lam) + eps) <= PI, False othwerwise.

See Also: Functions isnormal and normal_.

isodd (x)

 

Is x odd?

Arguments:
  • x - Value (scalar).
Returns:
True if odd, False otherwise.

ispolar (points, wrap=False)

 

Check whether a polygon encloses a pole.

Arguments:
  • points - The polygon points (LatLon[]).
  • wrap - If True, wrap or normalize and unroll the points (bool).
Returns:
True if the polygon encloses a pole, False otherwise.
Raises:
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon or don't have bearingTo2, initialBearingTo and finalBearingTo methods.

isscalar (obj, both=False)

 

Is object an int or integer float value?

Arguments:
  • obj - The object (any type).
  • both - If True, check Fsum and Fsum2Tuple residuals.
Returns:
True if int, float or Fsum/-2Tuple with zero residual, False otherwise.

issequence (obj, *excls)

 

Is object some sequence type?

Arguments:
  • obj - The object (any type).
  • excls - Classes to exclude (type), all positional.
Returns:
True if a sequence, False otherwise.

Note: Excluding tuple implies excluding namedtuple.

isstr (obj)

 

Is object some string type?

Arguments:
  • obj - The object (any type).
Returns:
True if a str, bytes, ..., False otherwise.

issubclassof (Sub, *Supers)

 

Is Sub a class and sub-class of some other class(es)?

Arguments:
  • Sub - The sub-class (Class).
  • Supers - One or more C(super) classes (Class).
Returns:
True if a sub-class of any Supers, False if not (bool) or None if not a class or if no Supers are given or none of those are a class.

istuplist (obj, minum=0)

 

DEPRECATED on 2023.03.31, use function pygeodesy.islistuple.

Decorators:
  • @deprecated_function

itemsorted (adict, *items_args, **asorted_reverse)

 

Return the items of adict sorted alphabetically, case-insensitively and in ascending order.

Arguments:
  • items_args - Optional positional argument(s) for method adict.items(B*{items_args}).
  • asorted_reverse - Use asorted=False for alphabetical, case-sensitive sorting and reverse=True for sorting in descending order.

iterNumpy2 (obj)

 

Iterate over Numpy2 wrappers or other sequences exceeding the threshold.

Arguments:
  • obj - Points array, list, sequence, set, etc. (any).
Returns:
True do, False don't iterate.

iterNumpy2over (n=None)

 

Get or set the iterNumpy2 threshold.

Arguments:
  • n - Optional, new threshold (int).
Returns:
Previous threshold (int).
Raises:
  • ValueError - Invalid n.

joined (*words, **sep)

 

DEPRECATED, use NN(...), NN.join_ or sep.join.

Decorators:
  • @deprecated_function

joined_ (*words, **sep)

 

DEPRECATED, use _SPACE_(...), _SPACE_.join_ or sep.join, sep=" ".

Decorators:
  • @deprecated_function

km2m (km)

 

Convert kilo meter to meter (m).

Arguments:
  • km - Value in kilo meter (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid km.

latDMS (deg, form='dms', prec=None, sep='', **s_D_M_S)

 

Convert latitude to a string, optionally suffixed with N or S.

Arguments:
  • deg - Latitude to be formatted (scalar degrees).
  • form - Format specifier for deg (str or F_...).
  • prec - Number of decimal digits (0..9 or None for default).
  • sep - Separator between degrees, minutes, seconds, suffix (str).
  • s_D_M_S - Optional keyword arguments to override any or cancel all DMS symbol suffixes, see function pygeodesy.toDMS.
Returns:
Degrees in the specified form (str).

See Also: Function pygeodesy.toDMS and its Notes for further details.

latlon2n_xyz (lat_ll, lon=None, **name)

 

Convert lat-, longitude to n-vector (normal to the earth's surface) X, Y and Z components.

Arguments:
  • lat_ll - Latitude (degrees) or a LatLon instance, LatLon2Tuple or other LatLon*Tuple.
  • lon - Longitude (degrees), required if lon_ll is degrees, ignored otherwise.
  • name - Optional name=NN (str).
Returns:
A Vector3Tuple(x, y, z).

See Also: Function philam2n_xyz.

Note: These are n-vector x, y and z components, NOT geocentric x, y and z (ECEF) coordinates!

latlonDMS (lls, **m_form_prec_sep_s_D_M_S)

 

Convert one or more LatLon instances to strings.

Arguments:
  • lls - Single (LatLon) or an iterable (LatLons).
  • m_form_prec_sep_s_D_M_S - Optional keyword arguments meter, format, precision, s_D, s_M, s_S, s_DMS and DEPRECATED sep=None, see function pygeodesy.toDMS and method LatLon.toStr for more details.
Returns:
A tuple of strs if lls is a list, sequence, tuple, etc. of LatLons or a single str if lls is a single LatLon.

See Also: Functions pygeodesy.latlonDMS_, pygeodesy.latDMS, pygeodesy.lonDMS and pygeodesy.toDMS and method LatLon.toStr.

Note: Keyword argument sep=None to join the resturned tuple has been DEPRECATED, use sep.join(latlonDMS_(...)) instead.

latlonDMS_ (*lls, **m_form_prec_sep_s_D_M_S)

 

Convert one or more LatLon instances to strings.

Arguments:
  • lls - The instances (LatLons), all positional arguments.
  • m_form_prec_sep_s_D_M_S - Optional keyword arguments meter, format, precision, s_D, s_M, s_S, s_DMS and DEPRECATED sep=None, see function pygeodesy.toDMS and method LatLon.toStr for more details.
Returns:
A tuple of strs if 2 or more LatLon instances or a single str if only a single LatLon instance is given in lls.

See Also: Functions pygeodesy.latlonDMS, pygeodesy.latDMS and pygeodesy.lonDMS and pygeodesy.toDMS and method LatLon.toStr.

Note: Keyword argument sep=None to join the resturned tuple has been DEPRECATED, use sep.join(latlonDMS_(...)) instead.

len2 (items)

 

Make built-in function len work for generators, iterators, etc. since those can only be started exactly once.

Arguments:
  • items - Generator, iterator, list, range, tuple, etc.
Returns:
2-Tuple (n, items) of the number of items (int) and the items (list or tuple).

limiterrors (raiser=None)

 

Get/set the throwing of LimitErrors.

Arguments:
  • 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=None, sep='', **s_D_M_S)

 

Convert longitude to a string, optionally suffixed with E or W.

Arguments:
  • deg - Longitude to be formatted (scalar degrees).
  • form - Format specifier for deg (str or F_...).
  • prec - Number of decimal digits (0..9 or None for default).
  • sep - Separator between degrees, minutes, seconds, suffix (str).
  • s_D_M_S - Optional keyword arguments to override any or cancel all DMS symbol suffixes.
Returns:
Degrees in the specified form (str).

See Also: Function pygeodesy.toDMS and its Notes for further details.

lrstrip (txt, lrpairs={'(': ')', '<': '>', '[': ']', '{': '}'})

 

Left- and right-strip parentheses, brackets, etc. from a string.

Arguments:
  • txt - String to be stripped (str).
  • lrpairs - Parentheses, etc. to remove (dict of one or several (Left, Right) pairs).
Returns:
Stripped txt (str).

luneOf (lon1, lon2, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds)

 

Generate an ellipsoidal or spherical lune-shaped path or polygon.

Arguments:
  • lon1 - Left longitude (degrees90).
  • lon2 - Right longitude (degrees90).
  • closed - Optionally, close the path (bool).
  • LatLon - Class to use (LatLon_).
  • LatLon_kwds - Optional, additional LatLon keyword arguments.
Returns:
A tuple of 4 or 5 LatLon instances outlining the lune shape.

m2NM (meter)

 

Convert meter to nautical miles (NM).

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in NM (float).
Raises:
  • ValueError - Invalid meter.

m2SM (meter)

 

Convert meter to statute miles (SM).

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in SM (float).
Raises:
  • ValueError - Invalid meter.

m2acre (meter2)

 

Convert square meter to acres.

Arguments:
  • meter2 - Value in meter^2 (scalar).
Returns:
Value in acres (float).
Raises:
  • ValueError - Invalid meter2.

m2chain (meter)

 

Convert meter to UK chains.

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in chains (float).
Raises:
  • ValueError - Invalid meter.

m2degrees (distance, radius=6371008.771415, lat=0)

 

Convert a distance to an angle along the equator or along a parallel at (geodetic) latitude.

Arguments:
  • distance - Distance (meter, same units as radius).
  • radius - Mean earth radius (meter), an ellipsoid or datum (Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
  • lat - Parallel latitude (degrees90, str).
Returns:
Angle (degrees) or INF for near-polar lat.
Raises:
  • RangeError - Latitude lat outside valid range and rangerrors is True.
  • TypeError - Invalid radius.
  • ValueError - Invalid distance, radius or lat.

See Also: Function m2radians and degrees2m.

m2fathom (meter)

 

Convert meter to Imperial fathoms.

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in fathoms (float).
Raises:
  • ValueError - Invalid meter.

See Also: Function m2toise, Fathom and Klafter.

m2ft (meter, usurvey=False, pied=False, fuss=False)

 

Convert meter to International, US Survey, French or or German feet (ft).

Arguments:
  • meter - Value in meter (scalar).
  • usurvey - If True, convert to US Survey foot else ...
  • pied - If True, convert to French pied-du-Roi else ...
  • fuss - If True, convert to German Fuss, otherwise to International foot.
Returns:
Value in feet (float).
Raises:
  • ValueError - Invalid meter.

m2furlong (meter)

 

Convert meter to furlongs.

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in furlongs (float).
Raises:
  • ValueError - Invalid meter.

m2ha (meter2)

 

Convert square meter to hectare.

Arguments:
  • meter2 - Value in meter^2 (scalar).
Returns:
Value in hectare (float).
Raises:
  • ValueError - Invalid meter2.

m2km (meter)

 

Convert meter to kilo meter (Km).

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in Km (float).
Raises:
  • ValueError - Invalid meter.

m2radians (distance, radius=6371008.771415, lat=0)

 

Convert a distance to an angle along the equator or along a parallel at (geodetic) latitude.

Arguments:
  • distance - Distance (meter, same units as radius).
  • radius - Mean earth radius (meter, an ellipsoid or datum (Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
  • lat - Parallel latitude (degrees90, str).
Returns:
Angle (radians) or INF for near-polar lat.
Raises:
  • RangeError - Latitude lat outside valid range and rangerrors is True.
  • TypeError - Invalid radius.
  • ValueError - Invalid distance, radius or lat.

See Also: Function m2degrees and radians2m.

m2toise (meter)

 

Convert meter to French toises.

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in toises (float).
Raises:
  • ValueError - Invalid meter.

See Also: Function m2fathom.

m2yard (meter)

 

Convert meter to UK yards.

Arguments:
  • meter - Value in meter (scalar).
Returns:
Value in yards (float).
Raises:
  • ValueError - Invalid meter.

machine()

 

Return standard platform.machine, but distinguishing Intel native from Intel emulation on Apple Silicon (on macOS only).

Returns:
Machine 'arm64' for Apple Silicon native, 'x86_64' for Intel native, "arm64_x86_64" for Intel emulation, etc. (str with commas replaced by underscores).

map1 (fun1, *xs)

 

Call a single-argument function to each xs and return a tuple of results.

Arguments:
  • fun1 - 1-Arg function (callable).
  • xs - Arguments (any positional).
Returns:
Function results (tuple).

map2 (fun, *xs, **strict)

 

Like Python's map but returning 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 the Python 2 behavior.

Arguments:
  • fun - Function (callable).
  • xs - Arguments (all positional).
  • strict - See Python 3.14+ map (bool).
Returns:
Function results (tuple).

meeus2 (point1, point2, point3, circum=False, useZ=True)

 

Return the radius and Meeus' Type of the smallest circle through or containing three (2- or 3-D) points.

Arguments:
  • point1 - First point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point2 - Second point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point3 - Third point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • circum - If True, return the circumradius and circumcenter always, overriding Meeus' Type II case (bool).
  • useZ - If True, use the Z components, otherwise force z=INT0 (bool).
Returns:
Meeus2Tuple(radius, Type), with Type the circumcenter iff circum=True.
Raises:
  • IntersectionError - Near-coincident or -colinear points, iff circum=True.
  • TypeError - Invalid point1, point2 or point3.

See Also: Functions pygeodesy.circum3 and pygeodesy.circum4_ and Meeus, J. Astronomical Algorithms, 2nd Ed. 1998, page 127ff, circumradius and circumcircle.

modulename (clas, prefixed=None)

 

Return the class name optionally prefixed with the module name.

Arguments:
  • clas - The class (any class).
  • prefixed - Include the module name (bool), see function classnaming.
Returns:
The class's [module.]class name (str).

n2e2 (n)

 

Return e2, the 1st eccentricity squared for a given 3rd flattening.

Arguments:
  • n - The 3rd flattening (-1 <= scalar < 1).
Returns:
The signed, (1st) eccentricity squared (float or NINF), 4 * n / (1 + n)**2.

Note: The result is positive for oblate, negative for prolate or 0 for near-spherical ellipsoids.

See Also: Flattening.

n2f (n)

 

Return f, the flattening for a given 3rd flattening.

Arguments:
  • n - The 3rd flattening (-1 <= scalar < 1).
Returns:
The flattening (scalar or NINF), 2 * n / (1 + n).

n2f_ (n)

 

Return f_, the inverse flattening for a given 3rd flattening.

Arguments:
  • n - The 3rd flattening (-1 <= scalar < 1).
Returns:
The inverse flattening (scalar or 0), 1 / f.

See Also: n2f and f2f_.

n_xyz2latlon (x_xyz, y=0, z=0, **name)

 

Convert n-vector to (geodetic) lat- and longitude in degrees.

Arguments:
  • x_xyz - X component (scalar) or (3-D) vector (Nvector, Vector3d, Vector3Tuple or Vector4Tuple).
  • y - Y component of vector (scalar), required if x_xyz is scalar and same units as x_xyz, ignored otherwise.
  • z - Z component of vector (scalar), like y.
  • name - Optional name=NN (str).
Returns:
A LatLon2Tuple(lat, lon).

See Also: Function n_xyz2philam.

n_xyz2philam (x_xyz, y=0, z=0, **name)

 

Convert n-vector to (geodetic) lat- and longitude in radians.

Arguments:
  • x_xyz - X component (scalar) or (3-D) vector (Nvector, Vector3d, Vector3Tuple or Vector4Tuple).
  • y - Y component of vector (scalar), required if x_xyz is scalar and same units as x_xyz, ignored otherwise.
  • z - Z component of vector (scalar), like y.
  • name - Optional name=NN (str).
Returns:
A PhiLam2Tuple(phi, lam).

See Also: Function n_xyz2latlon.

nameof (inst)

 

Get the name of an instance.

Arguments:
  • inst - The object (any type).
Returns:
The instance' name (str) or "".

nearestOn (point, point1, point2, within=True, useZ=True, Vector=None, **Vector_kwds)

 

Locate the point between two points closest to a reference (2- or 3-D).

Arguments:
  • point - Reference point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • point1 - Start point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • point2 - End point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • within - If True, return the closest point between both given points, otherwise the closest point on the extended line through both points (bool).
  • useZ - If True, use the Z components, otherwise force z=INT0 (bool).
  • Vector - Class to return closest point (Cartesian, Vector3d or Vector3Tuple) or None.
  • Vector_kwds - Optional, additional Vector keyword arguments, ignored if Vector is None.
Returns:
Closest point, either point1 or point2 or an instance of the point's (sub-)class or Vector if not None.
Raises:
  • TypeError - Invalid point, point1 or point2.

See Also: 3-D Point-Line Distance, Cartesian and LatLon methods nearestOn, method sphericalTrigonometry.LatLon.nearestOn3 and function sphericalTrigonometry.nearestOn3.

nearestOn3 (point, points, closed=False, wrap=False, **options)

 

DEPRECATED, use function pygeodesy.nearestOn5.

Returns:
3-Tuple (lat, lon, distance)
Decorators:
  • @deprecated_function

nearestOn4 (point, points, closed=False, wrap=False, **options)

 

DEPRECATED, use function pygeodesy.nearestOn5.

Returns:
4-Tuple (lat, lon, distance, angle)
Decorators:
  • @deprecated_function

nearestOn5 (point, points, closed=False, wrap=False, adjust=True, limit=9, **LatLon_and_kwds)

 

Locate the point on a path or polygon closest to a reference point.

The closest point on each polygon edge is either the nearest of that edge's end points or a point in between.

Arguments:
  • point - The reference point (LatLon).
  • points - The path or polygon points (LatLon[]).
  • closed - Optionally, close the path or polygon (bool).
  • wrap - If True, wrap or normalize and unroll the points (bool).
  • adjust - See function pygeodesy.equirectangular4 (bool).
  • limit - See function pygeodesy.equirectangular4 (degrees), default 9 degrees is about 1,000 Kmeter (for mean spherical earth radius R_KM).
  • LatLon_and_kwds - Optional, LatLon=None class to use for the closest point and additional LatLon keyword arguments, ignored if LatLon is None or not given.
Returns:
A NearestOn3Tuple(closest, distance, angle) with the {closest} point (LatLon) or if LatLon is None, a NearestOn5Tuple(lat, lon, distance, angle, height). The distance is the pygeodesy.equirectangular distance between the closest and reference point in degrees. The angle from the point to the closest is in compass degrees, like function pygeodesy.compassAngle.
Raises:

Note: Distances are approximated by function pygeodesy.equirectangular4. For more accuracy use one of the LatLon.nearestOn6 methods.

See Also: Function pygeodesy.degrees2m.

nearestOn6 (point, points, closed=False, useZ=True, **Vector_and_kwds)

 

Locate the point on a path or polygon closest to a reference point.

The closest point on each polygon edge is either the nearest of that edge's end points or a point in between.

Arguments:
  • point - Reference point (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • points - The path or polygon points (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple[]).
  • closed - Optionally, close the path or polygon (bool).
  • useZ - If True, use the Z components, otherwise force z=INT0 (bool).
  • Vector_and_kwds - Optional class Vector=None to return the closest point and optionally, additional Vector keyword arguments, otherwise point's (sub-)class.
Returns:
A NearestOn6Tuple(closest, distance, fi, j, start, end) with the closest, the start and the end point each an instance of the Vector keyword argument or if {Vector=None} or not specified, an instance of the reference point's (sub-)class.
Raises:
  • PointsError - Insufficient number of points
  • TypeError - Non-cartesian point and points.

Note: Distances measured with method Vector3d.equirectangular. For geodetic distances use function nearestOn5 or one of the LatLon.nearestOn6 methods.

neg (x, neg0=None)

 

Negate x and optionally, negate 0.0 and -0.0.

Arguments:
  • neg0 - Defines the return value for zero x: if None return 0.0, if True return NEG0 if x=0.0 and 0.0 if x=NEG0 or if False return x as-is (bool or None).
Returns:
-x if x else 0.0, NEG0 or x.

neg_ (*xs)

 

Negate all xs with neg.

Returns:
A map(neg, xs).

nonfiniterrors (raiser=None)

 

Throw OverflowError and ValueError exceptions for or handle non-finite floats as inf, INF, NINF, nan and NAN in summations and multiplications.

Arguments:
  • raiser - If True, throw exceptions, if False handle non-finites or if None or omitted, leave the setting unchanged.
Returns:
Previous setting (bool).

Note: inf, INF and NINF throw an OverflowError, nan and NAN a ValueError.

norm2 (x, y)

 

Normalize a 2-dimensional vector.

Arguments:
  • x - X component (scalar).
  • y - Y component (scalar).
Returns:
2-Tuple (x, y), normalized.
Raises:
  • ValueError - Invalid x or y or zero norm.

normDMS (strDMS, norm=None, **s_D_M_S)

 

Normalize all degrees, minutes and seconds (DMS) symbol suffixes in a string to the default symbols S_DEG, S_MIN, S_SEC.

Arguments:
  • strDMS - Original DMS string (str).
  • norm - Optional replacement symbol (str) or None for the default DMS symbol). Use norm="" to remove all DMS symbols.
  • s_D_M_S - Optional, alternate DMS symbol suffixes s_D=S_DEG, s_M=S_MIN, s_S=S_SEC and s_R=S_RAD for radians, each to be replaced by norm.
Returns:
Normalized DMS (str).

norm_ (*xs)

 

Normalize the components of an n-dimensional vector.

Arguments:
  • xs - Components (each scalar, an Fsum or Fsum2Tuple), all positional.
Returns:
Yield each component, normalized.
Raises:
  • ValueError - Invalid or insufficent xs or zero norm.

normal (lat, lon, **name)

 

Normalize a lat- and longitude pair in degrees.

Arguments:
  • lat - Latitude (degrees).
  • lon - Longitude (degrees).
  • name - Optional name="normal" (str).
Returns:
LatLon2Tuple(lat, lon) with -90 <= lat <= 90 and -180 <= lon <= 180.

See Also: Functions normal_ and isnormal.

normal_ (phi, lam, **name)

 

Normalize a lat- and longitude pair in radians.

Arguments:
  • phi - Latitude (radians).
  • lam - Longitude (radians).
  • name - Optional name="normal_" (str).
Returns:
PhiLam2Tuple(phi, lam) with abs(phi) <= PI/2 and abs(lam) <= PI.

See Also: Functions normal and isnormal_.

notImplemented (inst, *args, **kwds)

 

Raise a NotImplementedError for a missing instance method or property or for a missing caller feature.

Arguments:
  • inst - Caller instance (any) or None for function.
  • args - Method or property positional arguments (any types).
  • kwds - Method or property keyword arguments (any types), except callername=NN, underOK=False and up=2.

notOverloaded (inst, *args, **kwds)

 

Raise an AssertionError for a method or property not overloaded.

Arguments:
  • inst - Instance (any).
  • args - Method or property positional arguments (any types).
  • kwds - Method or property keyword arguments (any types), except callername=NN, underOK=False and up=2.

opposing (bearing1, bearing2, margin=90.0)

 

Compare the direction of two bearings given in degrees.

Arguments:
  • bearing1 - First bearing (compass degrees).
  • bearing2 - Second bearing (compass degrees).
  • margin - Optional, interior angle bracket (degrees).
Returns:
True if both bearings point in opposite, False if in similar or None if in perpendicular directions.

See Also: Function opposing_.

opposing_ (radians1, radians2, margin=1.5707963267948966)

 

Compare the direction of two bearings given in radians.

Arguments:
  • radians1 - First bearing (radians).
  • radians2 - Second bearing (radians).
  • margin - Optional, interior angle bracket (radians).
Returns:
True if both bearings point in opposite, False if in similar or None if in perpendicular directions.

See Also: Function opposing.

pairs (items, prec=6, fmt='F', ints=False, sep='=')

 

Convert items to name=value strings, with floats handled like fstr.

Arguments:
  • items - Name-value pairs (dict or 2-{tuple}s of any types).
  • prec - The float precision, number of decimal digits (0..9). Trailing zero decimals are stripped if prec is positive, but kept for negative prec values.
  • fmt - Optional float format (letter).
  • ints - Optionally, remove the decimal dot for int values (bool).
  • sep - Separator joining names and values (str).
Returns:
A tuple(sep.join(t) for t in items)) of strs.

parse3d (str3d, sep=',', Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds)

 

Parse an "x, y, z" string.

Arguments:
  • str3d - X, y and z values (str).
  • sep - Optional separator (str).
  • Vector - Optional class (Vector3d).
  • Vector_kwds - Optional Vector keyword arguments, ignored if Vector is None.
Returns:
A Vector instance or if Vector is None, a named Vector3Tuple(x, y, z).
Raises:

parse3llh (strllh, height=0, sep=',', clipLat=90, clipLon=180, wrap=False, **s_D_M_S)

 

Parse a string "lat, lon [, h]" representing lat-, longitude in degrees and optional height in meter.

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.

Arguments:
  • strllh - Latitude, longitude[, height] (str, ...).
  • height - Optional, default height (meter) or None.
  • sep - Optional separator between "lat lon [h] suffix" (str).
  • clipLat - Limit latitude to range -/+clipLat (degrees).
  • clipLon - Limit longitude to range -/+clipLon (degrees).
  • wrap - If True, wrap or normalize the lat- and longitude, overriding clipLat and clipLon (bool).
  • s_D_M_S - Optional, alternate DMS symbol suffixes for degrees s_D=S_DEG, minutes s_M=S_MIN and seconds s_S=S_SEC, see function pygeodesy.toDMS.
Returns:
A LatLon3Tuple(lat, lon, height) in degrees, degrees and float.
Raises:
  • RangeError - Lat- or longitude value of strllh outside the valid -/+clipLat or -/+clipLon range and rangerrors is True.
  • ValueError - Invalid strllh or height.

Note: See the Notes at function parseDMS.

See Also: Functions pygeodesy.parseDDDMMSS, pygeodesy.parseDMS, pygeodesy.parseDMS2 and pygeodesy.toDMS.

parseDDDMMSS (strDDDMMSS, suffix='NSEW', sep='', clip=0, sexagecimal=False)

 

Parse a lat- or longitude represention forms as [D]DDMMSS in degrees.

Arguments:
  • strDDDMMSS - Degrees in any of several forms (str) and types (float, int, other).
  • suffix - Optional compass points (str), valid in strDDDMMSS.
  • sep - Optional separator between "[D]DD", "MM", "SS", suffix (S_SEP) in strDDDMMSS.
  • clip - Optionally, limit value to range -/+clip (degrees).
  • sexagecimal - If True, convert "D.MMSS" or float(D.MMSS) to base-60 "MM" and "SS" digits. See forms F_D60, F_D60_ and F_D60__.
Returns:
Degrees (float).
Raises:
  • ParseError - Invalid strDDDMMSS or clip or the form of strDDDMMSS is incompatible with or invalid for the given suffix compass point(s).
  • RangeError - Value of strDDDMMSS outside the valid -/+clip range and rangerrors is True.
Notes:
  • Type str values "[D]DD", "[D]DDMM", "[D]DDMMSS" and "[D]DD.MMSS" for strDDDMMSS are parsed properly only if either unsigned and suffixed with a valid, compatible, cardinal compassPoint or signed or unsigned, unsuffixed and with keyword argument suffix="NS", suffix="EW" or a compatible compassPoint.
  • Unlike function parseDMS, type float, int and other non-str strDDDMMSS values are interpreted as form [D]DDMMSS or [D]DD.MMSS. For example, int(1230) is returned as 12.5 and not 1230.0 degrees. However, int(345) is considered form "DDD" 345 and not "DDMM" 0345, unless suffix specifies the compass point. Also, float(15.0523) is returned as 15.0523 decimal degrees and not 15°5′23″ sexagecimal. To consider the latter, use float(15.0523) or "15.0523" and specify the keyword argument sexagecimal=True.

See Also: Functions pygeodesy.parseDMS, pygeodesy.parseDMS2 and pygeodesy.parse3llh.

parseDMS (strDMS, suffix='NSEW', sep='', clip=0, **s_D_M_S)

 

Parse a lat- or longitude representation in degrees.

This is very flexible on formats, allowing signed decimal degrees, degrees and minutes or degrees minutes and seconds optionally suffixed by a cardinal compass point.

A variety of symbols, separators and suffixes are accepted, for example "3°37′09″W". Minutes and seconds may be omitted.

Arguments:
  • strDMS - Degrees in any of several forms (str) and types (float, int, other).
  • suffix - Optional, valid compass points (str, tuple).
  • sep - Optional separator between deg°, min′, sec″, suffix ('').
  • clip - Optionally, limit value to range -/+clip (degrees).
  • s_D_M_S - Optional, alternate DMS symbol suffixes for degrees s_D=S_DEG, minutes s_M=S_MIN and seconds s_S=S_SEC, see function pygeodesy.toDMS.
Returns:
Degrees (float).
Raises:

Note: Unlike function parseDDDMMSS, type float, int and other non-str strDMS values are considered decimal (and not sexagecimal) degrees. For example, int(1230) is returned as 1230.0 and not as 12.5 degrees and float(345) as 345.0 and not as 3.75 degrees!

See Also: Functions pygeodesy.parseDDDMMSS, pygeodesy.parseDMS2, pygeodesy.parse3llh and pygeodesy.toDMS.

parseDMS2 (strLat, strLon, sep='', clipLat=90, clipLon=180, wrap=False, **s_D_M_S)

 

Parse a lat- and a longitude representions "lat, lon" in degrees.

Arguments:
  • 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′, sec″, suffix ('').
  • clipLat - Limit latitude to range -/+clipLat (degrees).
  • clipLon - Limit longitude to range -/+clipLon (degrees).
  • wrap - If True, wrap or normalize the lat- and longitude, overriding clipLat and clipLon (bool).
  • s_D_M_S - Optional, alternate DMS symbol suffixes for degrees s_D=S_DEG, minutes s_M=S_MIN and seconds s_S=S_SEC, see function pygeodesy.toDMS.
Returns:
A LatLon2Tuple(lat, lon) in degrees.
Raises:
  • ParseError - Invalid strLat or strLon.
  • RangeError - Value of strLat or strLon outside the valid -/+clipLat or -/+clipLon range and rangerrors is True.

Note: See the Notes at function parseDMS.

See Also: Functions pygeodesy.parseDDDMMSS, pygeodesy.parseDMS, pygeodesy.parse3llh and pygeodesy.toDMS.

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

Arguments:
  • strUTM - A UTM coordinate (str).
  • datum - Optional datum to use (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple).
  • Etm - Optional class to return the UTM coordinate (Etm) or None.
  • falsed - Both easting and northing are falsed (bool).
  • name - Optional Etm name=NN (str).
Returns:
The UTM coordinate (Etm) or if Etm is None, a UtmUps5Tuple(zone, hemipole, easting, northing, band) with hemipole is the hemisphere 'N'|'S'.
Raises:
  • ETMError - Invalid strUTM.
  • TypeError - Invalid or near-spherical datum.

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 "[zone]Band, EN, easting, northing".

Arguments:
  • strMGRS - MGRS grid reference (str).
  • datum - Optional datum to use (Datum).
  • Mgrs - Optional class to return the MGRS grid reference (Mgrs) or None.
  • name - Optional Mgrs name=NN (str).
Returns:
The MGRS grid reference as Mgrs or if Mgrs is None as an Mgrs4Tuple(zone, EN, easting, northing).
Raises:

parseOSGR (strOSGR, Osgr=<class 'pygeodesy.osgr.Osgr'>, **name_Osgr_kwds)

 

Parse a string representing an OS Grid Reference, consisting of "[GD] easting northing".

Accepts standard OS Grid References like "SU 387 148", with or without whitespace separators, from 2- up to 22-digit references, or all-numeric, comma-separated references in meters, for example "438700,114800".

Arguments:
  • strOSGR - An OSGR coordinate (str).
  • Osgr - Optional class to return the OSGR coordinate (Osgr) or None.
  • name_Osgr_kwds - Optional name=NN (str) and optionally, additional Osgr keyword arguments, ignored if Osgr is None.
Returns:
An (Osgr) instance or if Osgr is None, an EasNor2Tuple(easting, northing).
Raises:

parseRad (strRad, suffix='NSEW', clip=0)

 

Parse a string representing angle in radians.

Arguments:
  • strRad - Degrees in any of several forms (str or radians).
  • suffix - Optional, valid compass points (str, tuple).
  • clip - Optionally, limit value to range -/+clip (radians).
Returns:
Radians (float).
Raises:

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

Arguments:
  • strUPS - A UPS coordinate (str).
  • datum - Optional datum to use (Datum).
  • Ups - Optional class to return the UPS coordinate (Ups) or None.
  • falsed - If True, both easting and northing are falsed (bool).
  • name - Optional Ups name=NN (str).
Returns:
The UPS coordinate (Ups) or if Ups is None, a UtmUps5Tuple(zone, hemipole, easting, northing, band). The hemipole is the 'N'|'S' pole, the UPS projection top/center.
Raises:

parseUTM (strUTM, datum=_UTM, Utm=_UTM, name='')

 

DEPRECATED, use function parseUTM5.

Returns:
The UTM coordinate (Utm) or 4-tuple (zone, hemisphere, easting, northing) if Utm is None.
Decorators:
  • @deprecated_function

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

Arguments:
  • strUTM - A UTM coordinate (str).
  • datum - Optional datum to use (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple).
  • Utm - Optional class to return the UTM coordinate (Utm) or None.
  • falsed - Use falsed=False if both easting and northing are not falsed (bool).
  • name - Optional name=NN (str).
Returns:
The UTM coordinate (Utm) or if Utm is None, a UtmUps5Tuple(zone, hemipole, easting, northing, band). The hemipole is the 'N'|'S' hemisphere.
Raises:
  • UTMError - Invalid strUTM.
  • TypeError - Invalid datum.

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

Arguments:
  • strUTMUPS - A UTM or UPS coordinate (str).
  • datum - Optional datum to use (Datum).
  • Utm - Optional class to return the UTM coordinate (Utm) or None.
  • Ups - Optional class to return the UPS coordinate (Ups) or None.
  • name - Optional Utm or Ups name=NN (str).
Returns:
The UTM or UPS instance (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:

See Also: Functions pygeodesy.parseUTM5 and pygeodesy.parseUPS5.

parseWM (strWM, radius=6378137.0, Wm=<class 'pygeodesy.webmercator.Wm'>, **name)

 

Parse a string "e n [r]" representing a WM coordinate, consisting of easting, northing and an optional radius.

Arguments:
  • strWM - A WM coordinate (str).
  • radius - Optional earth radius (meter), needed in case strWM doesn't include r.
  • Wm - Optional class to return the WM coordinate (Wm) or None.
  • name - Optional name=NN (str).
Returns:
The WM coordinate (Wm) or if Wm is None, an EasNorRadius3Tuple(easting, northing, radius).
Raises:

perimeterOf (points, closed=False, adjust=True, radius=6371008.771415, wrap=True)

 

Approximate the perimeter of a path, polygon. or composite.

Arguments:
  • points - The path or polygon points or clips (LatLon[], BooleanFHP or BooleanGH).
  • closed - Optionally, close the path or polygon (bool).
  • adjust - Adjust the wrapped, unrolled longitudinal delta by the cosine of the mean latitude (bool).
  • radius - Mean earth radius (meter).
  • wrap - If True, wrap or normalize and unroll the points (bool).
Returns:
Approximate perimeter (meter, same units as radius).
Raises:
  • PointsError - Insufficient number of points
  • TypeError - Some points are not LatLon.
  • ValueError - Invalid radius or closed=False with points a composite.

Note: This perimeter is based on the pygeodesy.equirectangular4 distance approximation and is ill-suited for regions exceeding several hundred Km or Miles or with near-polar latitudes.

See Also: Functions sphericalTrigonometry.perimeterOf and ellipsoidalKarney.perimeterOf.

perimeterof (points, closed=False, adjust=True, radius=6371008.771415, wrap=True)

 

DEPRECATED, use function pygeodesy.perimeterOf.

Decorators:
  • @deprecated_function

philam2n_xyz (phi_ll, lam=None, **name)

 

Convert lat-, longitude to n-vector (normal to the earth's surface) X, Y and Z components.

Arguments:
  • phi_ll - Latitude (radians) or a LatLon instance with phi, lam or philam attributes.
  • lam - Longitude (radians), required if phi_ll is radians, ignored otherwise.
  • name - Optional name (str).
Returns:
A Vector3Tuple(x, y, z).

See Also: Function latlon2n_xyz.

Note: These are n-vector x, y and z components, NOT geocentric x, y and z (ECEF) coordinates!

pierlot (point1, point2, point3, alpha12, alpha23, useZ=False, eps=2.220446049250313e-16, **Clas_and_kwds)

 

3-Point resection using Pierlot's method ToTal with approximate limits for the (pseudo-)singularities.

Arguments:
  • point1 - First point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point2 - Second point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point3 - Third point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • alpha12 - Angle subtended from point1 to point2 or alpha2 - alpha1 (degrees).
  • alpha23 - Angle subtended from point2 to point3 or alpha3 - alpha2(degrees).
  • useZ - If True, interpolate the survey point's Z component, otherwise use z=INT0 (bool).
  • eps - Tolerance for cotangent (pseudo-)singularities (float).
  • Clas_and_kwds - Optional class Clas=point1.classof to return the survey point with optionally other Clas keyword arguments to instantiate the survey point.
Returns:
The survey (or robot) point, an instance of Clas or point1's (sub-)class.
Raises:
  • ResectionError - Near-coincident, -colinear or -concyclic points or invalid alpha12 or alpha23 or non-positive eps.
  • TypeError - Invalid point1, point2 or point3.

pierlotx (point1, point2, point3, alpha1, alpha2, alpha3, useZ=False, **Clas_and_kwds)

 

3-Point resection using Pierlot's method ToTal with exact limits for the (pseudo-)singularities.

Arguments:
  • point1 - First point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point2 - Second point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point3 - Third point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • alpha1 - Angle at point1 (degrees, counter-clockwise).
  • alpha2 - Angle at point2 (degrees, counter-clockwise).
  • alpha3 - Angle at point3 (degrees, counter-clockwise).
  • useZ - If True, interpolate the survey point's Z component, otherwise use z=INT0 (bool).
  • Clas_and_kwds - Optional class Clas=point1.classof to return the survey point with optionally other Clas keyword arguments to instantiate the survey point.
Returns:
The survey (or robot) point, an instance of Clas or point1's (sub-)class.
Raises:
  • ResectionError - Near-coincident, -colinear or -concyclic points or invalid alpha1, alpha2 or alpha3.
  • TypeError - Invalid point1, point2 or point3.

See Also: Pierlot's C function triangulationPierlot2 and function pierlot, cassini, collins5 and tienstra7.

points2 (points, closed=True, base=None, Error=<class 'pygeodesy.errors.PointsError'>)

 

Check a path or polygon represented by points.

Arguments:
  • points - The path or polygon points (LatLon[])
  • closed - Optionally, consider the polygon closed, ignoring any duplicate or closing final points (bool).
  • base - Optionally, check all points against this base class, if None don't check.
  • Error - Exception to raise (ValueError).
Returns:
A Points2Tuple(number, points) with the number of points and the points list or tuple.
Raises:
  • PointsError - Insufficient number of points.
  • TypeError - Some points are not base compatible or composite points.

polygon (points, closed=True, base=None)

 

DEPRECATED, use function pygeodesy.points2.

Decorators:
  • @deprecated_function

precision (res)

 

Determine the Georef precision to meet a required (geographic) resolution.

Arguments:
  • res - The required resolution (degrees).
Returns:
The Georef precision (int 0..11).
Raises:
  • ValueError - Invalid res.

See Also: Function wgrs.encode for more precision details.

print_ (*args, **nl_nt_prec_prefix__end_file_flush_sep__kwds)

 

Python 3+ print-like formatting and printing.

Arguments:
  • args - Values to be converted to str and joined by sep, all positional.

See Also: Function printf for further details.

printf (fmt, *args, **nl_nt_prec_prefix__end_file_flush_sep__kwds)

 

Printf-style and Python 3+ print-like formatting and printing.

Arguments:
  • fmt - Printf-style format specification (str).
  • args - Arguments to be formatted (any type, all positional).
  • nl_nt_prec_prefix__end_file_flush_sep__kwds - Optional keyword arguments nl=0 for the number of leading blank lines (int), nt=0 the number of trailing blank lines (int), prefix=NN to be inserted before the formatted text (str) and Python 3+ print keyword arguments end, sep, file and flush. Any remaining kwds are printf-style name-value pairs to be formatted, iff no args are present using prec=6 for the number of decimal digits (int).
Returns:
Number of bytes written.

property_doc_ (doc)

 

Decorator for a standard property with basic documentation.

Arguments:
  • doc - The property documentation (str).

Example:

>>>class Clas(object): >>> >>> @property_doc_("documentation text.") >>> def name(self): >>> ... >>> >>> @name.setter >>> def name(self, value): >>> ...

quadOf (latS, lonW, latN, lonE, closed=False, LatLon=<class 'pygeodesy.points.LatLon_'>, **LatLon_kwds)

 

Generate a quadrilateral path or polygon from two points.

Arguments:
  • latS - Souther-nmost latitude (degrees90).
  • lonW - Western-most longitude (degrees180).
  • latN - Norther-nmost latitude (degrees90).
  • lonE - Eastern-most longitude (degrees180).
  • closed - Optionally, close the path (bool).
  • LatLon - Class to use (LatLon_).
  • LatLon_kwds - Optional, additional LatLon keyword arguments.
Returns:
Return a tuple of 4 or 5 LatLon instances outlining the quadrilateral.

See Also: Function boundsOf.

radians2m (rad, radius=6371008.771415, lat=0)

 

Convert an angle to a distance along the equator or along a parallel at (geodetic) latitude.

Arguments:
  • rad - The angle (radians).
  • radius - Mean earth radius (meter) or an ellipsoid or datum (Ellipsoid, Ellipsoid2, Datum or a_f2Tuple).
  • lat - Parallel latitude (degrees90, str).
Returns:
Distance (meter, same units as radius or polar and equatorial radii) or 0.0 for near-polar lat.
Raises:
  • RangeError - Latitude lat outside valid range and rangerrors is True.
  • TypeError - Invalid radius.
  • ValueError - Invalid rad, radius or lat.

See Also: Function degrees2m and m2radians.

radiansPI (deg)

 

Convert and wrap degrees to radians [-PI..+PI].

Arguments:
  • deg - Angle (degrees).
Returns:
Radians, wrapped (radiansPI)

radiansPI2 (deg)

 

Convert and wrap degrees to radians [0..+2PI).

Arguments:
  • deg - Angle (degrees).
Returns:
Radians, wrapped (radiansPI2)

radiansPI_2 (deg)

 

Convert and wrap degrees to radians [-3PI/2..+PI/2].

Arguments:
  • deg - Angle (degrees).
Returns:
Radians, wrapped (radiansPI_2)

radical2 (distance, radius1, radius2, **name)

 

Compute the radical ratio and radical line of two intersecting circles.

The radical line is perpendicular to the axis thru the centers of the circles at (0, 0) and (distance, 0).

Arguments:
  • distance - Distance between the circle centers (scalar).
  • radius1 - Radius of the first circle (scalar).
  • radius2 - Radius of the second circle (scalar).
  • name - Optional name=NN (str).
Returns:
A Radical2Tuple(ratio, xline) where 0.0 <= ratio <= 1.0 and xline is along the distance.
Raises:

radii11 (point1, point2, point3, useZ=True)

 

Return the radii of the In-, Soddy and Tangent circles of a (2- or 3-D) triangle.

Arguments:
  • point1 - First point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point2 - Second point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point3 - Third point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • useZ - If True, use the Z components, otherwise force z=INT0 (bool).
Returns:
Radii11Tuple(rA, rB, rC, cR, rIn, riS, roS, a, b, c, s).
Raises:
  • TriangleError - Near-coincident or -colinear points.
  • TypeError - Invalid point1, point2 or point3.

randomrangenerator (seed)

 

Return a seeded random range function generator.

Arguments:
  • seed - Initial, internal Random state (hashable or None).
Returns:
A function to generate random ranges.

Note: Random with seed is 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)

 

Get/set the throwing of RangeErrors.

Arguments:
  • raiser - Choose True to raise or False to ignore RangeError exceptions. Use None to leave the setting unchanged.
Returns:
Previous setting (bool).

reprs (objs, prec=6, fmt='F', ints=False)

 

Convert objects to repr strings, with floats handled like fstr.

Arguments:
  • objs - List, sequence, tuple, etc. (any types).
  • prec - The float precision, number of decimal digits (0..9). Trailing zero decimals are stripped if prec is positive, but kept for negative prec values.
  • fmt - Optional float format (letter).
  • ints - Optionally, remove the decimal dot for int values (bool).
Returns:
A tuple(map(fstr|repr, objs)) of strs.

rtp2xyz (r_rtp, theta=0, phi=0, **name_Cartesian_and_kwds)

 

Convert spherical, polar (r, theta, phi) to cartesian (x, y, z) coordinates.

Arguments:
  • theta - Inclination theta (degrees with respect to the positive z-axis), required if r_rtp is scalar, ignored otherwise.
  • phi - Azimuthal angle phi (degrees), like theta.

See Also: Function rtp2xyz_ for further details.

rtp2xyz_ (r_rtp, theta=0, phi=0, **name_Cartesian_and_kwds)

 

Convert spherical, polar (r, theta, phi) to cartesian (x, y, z) coordinates.

Arguments:
  • r_rtp - Radial distance (scalar, conventially meter) or a previous RadiusThetaPhi3Tuple instance.
  • theta - Inclination theta (radians with respect to the positive z-axis), required if r_rtp is scalar, ignored otherwise.
  • phi - Azimuthal angle phi (radians), like theta.
  • name_Cartesian_and_kwds - Optional name=NN (str), Cartesian=None class to return the coordinates and optionally, additional Cartesian keyword arguments.
Returns:
A Cartesian(x, y, z) instance or if no Cartesian keyword argument is given a Vector3Tuple(x, y, z), with x, y and z in the same units as radius r, meter conventionally.
Raises:
  • TypeError - Invalid r_rtp, theta, phi or name_Cartesian_and_kwds item.

See Also: Physics convention (ISO 80000-2:2019), class RadiusThetaPhi3Tuple and functions rtp2xyz and xyz2rtp.

scalar (value, low=2.220446049250313e-16, high=1.0, name='scalar', Error=<type 'exceptions.ValueError'>)

 

DEPRECATED, use class Number_ or Scalar_.

Returns:
New value (float or int for int low).
Decorators:
  • @deprecated_function
Raises:
  • Error - Invalid value.

signBit (x)

 

Return signbit(x), like C++.

Returns:
True if x < 0 or NEG0 (bool).

signOf (x)

 

Return sign of x as int.

Returns:
-1, 0 or +1 (int).

simplify1 (points, distance=0.001, radius=6371008.771415, indices=False, **options)

 

Basic simplification of a path of LatLon points by eliminating any points closer together than the given distance tolerance.

Arguments:
  • points - Iterable with the path points (LatLon[]).
  • distance - Tolerance (meter, same units as radius).
  • radius - Mean earth radius (meter, conventionally).
  • indices - If True, return points indices instead of the simplified points (bool).
  • options - Optional keyword arguments passed thru to function pygeodesy.equirectangular4.
Returns:
Simplified points (LatLon[]) or points indices.
Raises:

simplify2 (points, pipe=0.001, **radius_shortest_indices_options)

 

DEPRECATED, use function pygeodesy.simplifyRW.

Decorators:
  • @deprecated_function

simplifyRDP (points, distance=0.001, radius=6371008.771415, shortest=False, indices=False, modified=False, **options)

 

Ramer-Douglas-Peucker (RDP) simplification of a path of LatLon points by eliminating any points too close together or closer to an edge than the given distance tolerance.

Arguments:
  • points - Iterable with the path points (LatLon[]).
  • distance - Tolerance (meter, same units as radius).
  • radius - Mean earth radius (meter, conventionally).
  • shortest - If True, use the shortest otherwise the perpendicular distance (bool).
  • indices - If True, return points indices instead of the simplified points (bool).
  • modified - If True, use the modified RDP method (bool), see the note.
  • options - Optional keyword arguments passed thru to function pygeodesy.equirectangular4.
Returns:
Simplified points (LatLon[]) or points indices.
Raises:

Note: The original RDP method exhaustively searches for the point with the largest distance (resulting in complexity O(n**2) with n is the number of points). The modified RDP method stops at the first point farther than the distance tolerance, significantly reducing the run time (but producing results different from the original RDP method).

simplifyRDPm (points, distance=0.001, **radius_shortest_indices_options)

 

DEPRECATED on 2024.11.28, use function pygeodesy.simplifyRDP(points, modified=True, ...).

Decorators:
  • @deprecated_function

simplifyRW (points, pipe=0.001, radius=6371008.771415, shortest=False, indices=False, **options)

 

Reumann-Witkam (RW) simplification of a path of LatLon points by eliminating any points too close together or within the given pipe tolerance along an edge.

Arguments:
  • points - Iterable with the path points (LatLon[]).
  • pipe - Pipe radius, half-width (meter, same units as radius).
  • radius - Mean earth radius (meter, conventionally).
  • shortest - If True, use the shortest otherwise the perpendicular distance (bool).
  • indices - If True, return points indices instead of the simplified points (bool).
  • options - Optional keyword arguments passed thru to function pygeodesy.equirectangular4.
Returns:
Simplified points (LatLon[]) or points indices.
Raises:

simplifyVW (points, area=0.001, radius=6371008.771415, indices=False, attr=None, modified=False, **options)

 

Visvalingam-Whyatt (VW) simplification of a path of LatLon points by eliminating any points too close or with a triangular area not exceeding the given area tolerance squared.

Arguments:
  • points - Iterable with the path points (LatLon[]).
  • area - Tolerance (meter, same units as radius).
  • radius - Mean earth radius (meter, conventionally).
  • indices - If True, return points indices instead of the simplified points (bool).
  • attr - Optional, points attribute to save the area value (str).
  • modified - If True, use the modified VW method (bool), see the note.
  • options - Optional keyword arguments passed thru to function pygeodesy.equirectangular4.
Returns:
Simplified points (LatLon[]) or points indices.
Raises:
  • AttributeError - An attr isinvalid for Numpy2 points.
  • LimitError - Lat- and/or longitudinal delta exceeds the limit, see function pygeodesy.equirectangular4.
  • ValueError - Tolerance area or radius too small.

Note: The original VW method exhaustively searches for the point with the smallest triangular area (resulting in complexity O(n**2) with n the number of points). The modified VW 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).

simplifyVWm (points, area=0.001, **radius_attr_indices_options)

 

DEPRECATED on 2024.11.28, use function pygeodesy.simplifyVW(points, modified=True, ...).

Decorators:
  • @deprecated_function

sincos2 (rad)

 

Return the sine and cosine of an angle in radians.

Arguments:
  • rad - Angle (radians).
Returns:
2-Tuple (sin(rad), cos(rad)).

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

sincos2_ (*rads)

 

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

Arguments:
  • rads - One or more angles (radians).
Returns:
Yield sin(rad) and cos(rad) for each angle.

See Also: Function sincos2.

sincos2d (deg, adeg=0.0)

 

Return the sine and cosine of an angle in degrees.

Arguments:
  • deg - Angle (degrees).
  • adeg - Optional correction (degrees).
Returns:
2-Tuple (sin(deg_), cos(deg_), deg_ = deg + adeg).

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

sincos2d_ (*degs)

 

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

Arguments:
  • degs - One or more angles (degrees).
Returns:
Yield sind(deg) and cosd(deg) for each angle.

See Also: Function sincos2d.

sincostan3 (rad)

 

Return the sine, cosine and tangent of an angle in radians.

Arguments:
  • rad - Angle (radians).
Returns:
3-Tuple (sin(rad), cos(rad), tan(rad)).

See Also: Function sincos2.

sincostan3d (deg)

 

Return the sine, cosine and tangent of an angle in degrees.

Arguments:
  • deg - Angle (degrees).
Returns:
3-Tuple (sind(deg), cosd(deg), tand(deg)).

See Also: Function sincos2d.

snellius3 (a, b, degC, alpha, beta)

 

Snellius' surveying using Snellius Pothenot.

Arguments:
  • a - Length of the triangle side between corners B and C and opposite of triangle corner A (scalar, non-negative meter, conventionally).
  • b - Length of the triangle side between corners C and A and opposite of triangle corner B (scalar, non-negative meter, conventionally).
  • degC - Angle at triangle corner C, opposite triangle side c (non-negative degrees).
  • alpha - Angle subtended by triangle side b (non-negative degrees).
  • beta - Angle subtended by triangle side a (non-negative degrees).
Returns:
Survey3Tuple(PA, PB, PC) with distance from survey point P to each of the triangle corners A, B and C, same units as triangle sides a, b and c.
Raises:
  • TriangleError - Invalid a, b or degC or negative alpha or beta.

See Also: Function wildberger3.

soddy4 (point1, point2, point3, eps=8.881784197001252e-16, useZ=True)

 

Return the radius and center of the inner Soddy circle of a (2- or 3-D) triangle.

Arguments:
  • point1 - First point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point2 - Second point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • point3 - Third point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • eps - Tolerance for function pygeodesy.trilaterate3d2 if useZ is True otherwise pygeodesy.trilaterate2d2.
  • useZ - If True, use the Z components, otherwise force z=INT0 (bool).
Returns:
Soddy4Tuple(radius, center, deltas, outer). The center, an instance of point1's (sub-)class, is co-planar with the three given points. The outer Soddy radius may be INF.
Raises:
  • ImportError - Package numpy not found, not installed or older than version 1.10 and useZ is True.
  • IntersectionError - Near-coincident or -colinear points or a trilateration or numpy issue.
  • TypeError - Invalid point1, point2 or point3.

See Also: Functions radii11 and circum3 and Soddy Circles.

splice (iterable, n=2, **fill)

 

Split an iterable into n slices.

Arguments:
  • iterable - Items to be spliced (list, tuple, ...).
  • n - Number of slices to generate (int).
  • fill - Optional fill value for missing items.
Returns:
A generator for each of n slices, iterable[i::n] for i=0..n.
Raises:
  • TypeError - Invalid n.

Note: Each generated slice is a tuple or a list, the latter only if the iterable is a list.

Example:

>>> from pygeodesy import splice
>>> a, b = splice(range(10))
>>> a, b
((0, 2, 4, 6, 8), (1, 3, 5, 7, 9))
>>> a, b, c = splice(range(10), n=3)
>>> a, b, c
((0, 3, 6, 9), (1, 4, 7), (2, 5, 8))
>>> a, b, c = splice(range(10), n=3, fill=-1)
>>> a, b, c
((0, 3, 6, 9), (1, 4, 7, -1), (2, 5, 8, -1))
>>> tuple(splice(list(range(9)), n=5))
([0, 5], [1, 6], [2, 7], [3, 8], [4])
>>> splice(range(9), n=1)
<generator object splice at 0x0...>

sqrt0 (x, Error=None)

 

Return the square root sqrt(x) iff x > EPS02, preserving type(x).

Arguments:
  • x - Value (scalar, an Fsum or Fsum2Tuple).
  • Error - Error to raise for negative x.
Returns:
Square root (float or Fsum) or 0.0.
Raises:
  • TypeeError - Invalid x.

Note: Any x < EPS02 including x < 0 returns 0.0.

sqrt3 (x)

 

Return the square root, cubed sqrt(x)**3 or sqrt(x**3), preserving type(x).

Arguments:
Returns:
Square root cubed (float or Fsum).
Raises:
  • TypeeError - Invalid x.
  • ValueError - Negative x.

See Also: Functions cbrt and cbrt2.

sqrt_a (h, b)

 

Compute a side of a right-angled triangle from sqrt(h**2 - b**2).

Arguments:
  • h - Hypotenuse or outer annulus radius (scalar).
  • b - Triangle side or inner annulus radius (scalar).
Returns:
copysign(a, h) or unsigned 0.0 (float).
Raises:
  • TypeError - Non-scalar h or b.
  • ValueError - If abs(h) < abs(b).

See Also: Inner tangent chord d of an annulus and function annulus_area.

strs (objs, prec=6, fmt='F', ints=False)

 

Convert objects to str strings, with floats handled like fstr.

Arguments:
  • objs - List, sequence, tuple, etc. (any types).
  • prec - The float precision, number of decimal digits (0..9). Trailing zero decimals are stripped if prec is positive, but kept for negative prec values.
  • fmt - Optional float format (letter).
  • ints - Optionally, remove the decimal dot for int values (bool).
Returns:
A tuple(map(fstr|str, objs)) of strs.

sumOf (vectors, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **Vector_kwds)

 

Compute the vectorial sum of two oe more vectors.

Arguments:
  • vectors - Vectors to be added (Vector3d[]).
  • Vector - Optional class for the vectorial sum (Vector3d).
  • Vector_kwds - Optional Vector keyword arguments, ignored if Vector is None.
Returns:
Vectorial sum as Vector or if Vector is None, a named Vector3Tuple(x, y, z).
Raises:

tan (rad, **raiser_kwds)

 

Return the tangent of an angle in radians.

Arguments:
  • rad - Angle (radians).
  • raiser_kwds - Use raiser=False to avoid ValueErrors or optionally, additional ValueError keyword argments.
Returns:
tan(rad).
Raises:

tanPI_2_2 (rad)

 

Compute the tangent of half angle, 90 degrees rotated.

Arguments:
  • rad - Angle (radians).
Returns:
tan((rad + PI/2) / 2) (float).

tan_ (*rads, **raiser_kwds)

 

Yield the tangent of angle(s) in radians.

Arguments:
  • rads - One or more angles (each in radians).
Returns:
Yield tan(rad) for each angle.

See Also: Function pygeodesy.tan for futher details.

tan_2 (rad, **semi)

 

Compute the tangent of half angle.

Arguments:
  • rad - Angle (radians).
  • semi - Angle or edge name and index for semi-circular error.
Returns:
tan(rad / 2) (float).
Raises:
  • ValueError - If rad is semi-circular and semi is given.

tand (deg, **raiser_kwds)

 

Return the tangent of an angle in degrees.

Arguments:
  • deg - Angle (degrees).
  • raiser_kwds - Use raiser=False to avoid ValueErrors or optionally, additional ValueError keyword argments.
Returns:
tan(deg).
Raises:

tand_ (*degs, **raiser_kwds)

 

Yield the tangent of angle(s) in degrees.

Arguments:
  • degs - One or more angles (each in degrees).
Returns:
Yield tand(deg) for each angle.

See Also: Function pygeodesy.tand for futher details.

thomas (lat1, lon1, lat2, lon2, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., wrap=False)

 

Compute the distance between two (ellipsoidal) points using Thomas' formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • datum - Datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as the datum's or ellipsoid axes).
Raises:
  • TypeError - Invalid datum.

thomas_ (phi2, phi1, lam21, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)

 

Compute the angular distance between two (ellipsoidal) points using Thomas' formula.

Arguments:
  • phi2 - End latitude (radians).
  • phi1 - Start latitude (radians).
  • lam21 - Longitudinal delta, end-start (radians).
  • datum - Datum (Datum) ?or ellipsoid to use (Ellipsoid, Ellipsoid2 or a_f2Tuple).
Returns:
Angular distance (radians).
Raises:
  • TypeError - Invalid datum.

tienstra (pointA, pointB, pointC, alpha, **beta_gamma_useZ_Clas_and_kwds)

 

DEPRECATED, use function pygeodesy.tienstra7.

Decorators:
  • @deprecated_function

tienstra7 (pointA, pointB, pointC, alpha, beta=None, gamma=None, useZ=False, **Clas_and_kwds)

 

3-Point resection using Tienstra's formula.

Arguments:
  • pointA - First point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • pointB - Second point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • pointC - Third point (Cartesian, Vector3d, Vector3Tuple, Vector4Tuple or Vector2Tuple if useZ=False).
  • alpha - Angle subtended by triangle side a from pointB to pointC (degrees, non-negative).
  • beta - Angle subtended by triangle side b from pointA to pointC (degrees, non-negative) or None if gamma is not None.
  • gamma - Angle subtended by triangle side c from pointA to pointB (degrees, non-negative) or None if beta is not None.
  • useZ - If True, use and interpolate the Z component, otherwise force z=INT0 (bool).
  • Clas_and_kwds - Optional class Clas=pointA.classof to return the survey point with optionally other Clas keyword arguments to instantiate the survey point.
Returns:
Tienstra7Tuple(pointP, A, B, C, a, b, c) with survey pointP, an instance of Clas or pointA's (sub-)class, with triangle angles A at pointA, B at pointB and C at pointC in degrees and with triangle sides a, b and c in meter, conventionally.
Raises:
  • ResectionError - Near-coincident, -colinear or -concyclic points or sum of alpha, beta and gamma not 360 or negative alpha, beta or gamma.
  • TypeError - Invalid pointA, pointB or pointC.

toCss (latlon, cs0=None, height=None, Css=<class 'pygeodesy.css.Css'>, **name)

 

Convert an (ellipsoidal) geodetic point to a Cassini-Soldner location.

Arguments:
  • latlon - Ellipsoidal point (LatLon or LatLon4Tuple).
  • cs0 - Optional, the Cassini-Soldner projection to use (CassiniSoldner).
  • height - Optional height for the point, overriding the default height (meter).
  • Css - Optional class to return the location (Css) or None.
  • name - Optional Css name=NN (str).
Returns:
The Cassini-Soldner location (Css) or if Css is None, an EasNor3Tuple(easting, northing, height).
Raises:
  • CSSError - Ellipsoidal mismatch of latlon and cs0.
  • ImportError - Package geographiclib not installed or not found.
  • TypeError - If latlon is not ellipsoidal.

toDMS (deg, form='dms', prec=2, sep='', ddd=2, neg='-', pos='+', **s_D_M_S)

 

Convert signed degrees to string, without suffix.

Arguments:
Returns:
Degrees in the specified form (str).
Notes:
  • The degrees, minutes and seconds (DMS) symbol can be overridden in this and other *DMS functions by using optional keyword argments s_D="d", s_M="'" respectively s_S='"'. Using s_DMS=None cancels all DMS symbols to "" aka pygeodesy.NN.
  • Sexagecimal format F_D60 supports overridable pseudo-DMS symbols positioned at "[D]DD<s_D>MM<s_M>SS<s_S>" with defaults s_D=".", s_M=sep and s_S=pygeodesy.NN.
  • Formats F__E, F__F and F__G is extended with a D-only symbol suffix if defined with keyword argument s_D=pygeodesy.NN. Likewise for F_RAD forms with keyword argument s_R=S_RAD.

See Also: Function pygeodesy.degDMS

toEtm8 (latlon, lon=None, datum=None, Etm=<class 'pygeodesy.etm.Etm'>, falsed=True, strict=True, zone=None, **name_cmoff)

 

Convert a geodetic lat-/longitude to an ETM coordinate.

Arguments:
  • latlon - Latitude (degrees) or an (ellipsoidal) geodetic LatLon instance.
  • lon - Optional longitude (degrees), required if latlon is degrees, ignored otherwise.
  • datum - Optional datum for the ETM coordinate, overriding latlon's datum (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple).
  • Etm - Optional class to return the ETM coordinate (Etm) or None.
  • falsed - False both easting and northing (bool).
  • strict - Restrict lat to UTM ranges (bool).
  • zone - Optional UTM zone to enforce (int or str).
  • name_cmoff - Optional Etm name=NN (str) and DEPRECATED keyword argument cmoff=True to offset the longitude from the zone's central meridian (bool), use falsed instead.
Returns:
The ETM coordinate as Etm or if Etm is None or not falsed, a UtmUps8Tuple(zone, hemipole, easting, northing, band, datum, gamma, scale). The hemipole is the 'N'|'S' hemisphere.
Raises:
  • ETMError - No convergence transforming to ETM easting and northing.
  • ETMError - Invalid zone or near-spherical or incompatible datum or ellipsoid.
  • RangeError - If lat outside the valid UTM bands or if lat or lon outside the valid range and rangerrors is True.
  • TypeError - Invalid or near-spherical datum or latlon not ellipsoidal.
  • ValueError - The lon value is missing or 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_Lcc_kwds)

 

Convert an (ellipsoidal) geodetic point to a Lambert location.

Arguments:
  • latlon - Ellipsoidal point (LatLon).
  • conic - Optional Lambert projection to use (Conic).
  • height - Optional height for the point, overriding the default height (meter).
  • Lcc - Class to return the Lambert location (Lcc).
  • name_Lcc_kwds - Optional name=NN (str) and optionally, additional Lcc keyword arguments, ignored if Lcc is None.
Returns:
The Lambert location (Lcc) or if Lcc is None, an EasNor3Tuple(easting, northing, height).
Raises:
  • TypeError - If latlon is not ellipsoidal.

toMgrs (utmups, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>, **name_Mgrs_kwds)

 

Convert a UTM or UPS coordinate to an MGRS grid reference.

Arguments:
  • utmups - A UTM or UPS coordinate (Utm, Etm or Ups).
  • Mgrs - Optional class to return the MGRS grid reference (Mgrs) or None.
  • name_Mgrs_kwds - Optional name=NN (str) and optionally, additional Mgrs keyword arguments, ignored if Mgrs is None.
Returns:
The MGRS grid reference as Mgrs or if Mgrs is None as an Mgrs6Tuple(zone, EN, easting, northing, band, datum).
Raises:

toOsgr (latlon, lon=None, kTM=False, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., Osgr=<class 'pygeodesy.osgr.Osgr'>, **prec_name_Osgr_kwds)

 

Convert a lat-/longitude point to an OSGR coordinate.

Arguments:
  • latlon - Latitude (degrees) or an (ellipsoidal) geodetic LatLon point.
  • lon - Optional longitude in degrees (scalar or None).
  • kTM - If True, use Karney's Krüger method from module ktm, otherwise use the Ordnance Survey formulation (bool).
  • datum - Optional datum to convert lat, lon from (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple).
  • Osgr - Optional class to return the OSGR coordinate (Osgr) or None.
  • prec_name_Osgr_kwds - Optional name=NN (str), optional truncate precision prec=ndigits and additional Osgr keyword arguments, ignored if Osgr is None.
Returns:
An (Osgr) instance or if Osgr is None an EasNor2Tuple(easting, northing).
Raises:
  • OSGRError - Invalid latlon or lon.
  • TypeError - Non-ellipsoidal latlon or invalid datum, Osgr, Osgr_kwds or conversion to Datums.OSGB36 failed.

Note: If isint(prec) both easting and northing are truncated to the given number of digits.

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.

Arguments:
  • 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, Ellipsoid, Ellipsoid2 or a_f2Tuple).
  • Ups - Optional class to return the UPS coordinate (Ups) or None.
  • pole - Optional top/center of (stereographic) projection (str, 'N[orth]' or 'S[outh]').
  • falsed - If True, false both easting and northing (bool).
  • strict - Restrict lat to UPS ranges (bool).
  • name - Optional Ups name=NN (str).
Returns:
The UPS coordinate (Ups) or if Ups is None, a UtmUps8Tuple(zone, hemipole, easting, northing, band, datum, gamma, scale) where 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 is True.
  • TypeError - If latlon is not ellipsoidal or if datum is invalid.
  • 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=_UTM, cmoff=True, name='')

 

DEPRECATED, use function pygeodesy.toUtm8.

Returns:
The UTM coordinate (Utm) or a 6-tuple (zone, easting, northing, band, convergence, scale) if Utm is None or cmoff is False.
Decorators:
  • @deprecated_function

toUtm8 (latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>, falsed=True, strict=True, zone=None, **name_cmoff)

 

Convert a lat-/longitude point to a UTM coordinate.

Arguments:
  • latlon - Latitude (degrees) or an (ellipsoidal) geodetic LatLon point.
  • lon - Longitude (degrees), required if latlon is degrees, ignored otherwise.
  • datum - Optional datum for this UTM coordinate, overriding latlon's datum (Datum, Ellipsoid, Ellipsoid2 or a_f2Tuple).
  • Utm - Optional class to return the UTM coordinate (Utm) or None.
  • falsed - If True, false both easting and northing (bool).
  • strict - If True, restrict lat to UTM ranges (bool).
  • zone - Optional UTM zone to enforce (int or str).
  • name_cmoff - Optional name=NN (str) and DEPRECATED keyword argument cmoff=True to offset the longitude from the zone's central meridian (bool), use falsed instead.
Returns:
The UTM coordinate (Utm) or if Utm is None or falsed is False, a UtmUps8Tuple(zone, hemipole, easting, northing, band, datum, gamma, scale) where hemipole is the 'N'|'S' hemisphere.
Raises:
  • RangeError - If lat outside the valid UTM bands or if lat or lon outside the valid range and rangerrors is True.
  • TypeError - Invalid datum or latlon not ellipsoidal.
  • UTMError - Invalid zone.
  • ValueError - If lon is missing or 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 3,900 Km from the central meridian.

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.

Arguments:
  • latlon - Latitude (degrees) or an (ellipsoidal) geodetic LatLon point.
  • lon - Longitude (degrees), required if latlon is degrees, ignored otherwise.
  • datum - Optional datum to use this UTM coordinate, overriding the latlon's datum (Datum).
  • falsed - If True, false both easting and northing (bool).
  • Utm - Optional class to return the UTM coordinate (Utm) or None.
  • Ups - Optional class to return the UPS coordinate (Ups) or None.
  • pole - Optional top/center of UPS (stereographic) projection (str, 'N[orth]' or 'S[outh]').
  • name_cmoff - Optional name=NN (str) and DEPRECATED keyword argument cmoff=True to offset the longitude from the zone's central meridian (bool), use falsed instead and for UTM only.
Returns:
The UTM or UPS coordinate (Utm respectively Ups) or a UtmUps8Tuple(zone, hemipole, easting, northing, band, datum, gamma, scale) if Utm respectively Ups is None or if falsed is False.
Raises:
  • RangeError - If lat outside the valid UTM or UPS bands or if lat or lon outside the valid range and rangerrors is True.
  • TypeError - If latlon is not ellipsoidal or lon is missing or datum is invalid.
  • UTMUPSError - UTM or UPS validation failed.
  • ValueError - Invalid lat or lon.

See Also: Functions pygeodesy.toUtm8 and pygeodesy.toUps8.

toWm (latlon, lon=None, earth=6378137.0, Wm=<class 'pygeodesy.webmercator.Wm'>, **name_Wm_kwds_radius)

 

Convert a lat-/longitude point to a WM coordinate.

Arguments:
  • latlon - Latitude (degrees) or an (ellipsoidal or spherical) geodetic LatLon point.
  • lon - Optional longitude (degrees or None).
  • earth - Earth radius (meter), datum or ellipsoid (Datum, a_f2Tuple, Ellipsoid or Ellipsoid2), overridden by latlon's datum if present.
  • Wm - Optional class to return the WM coordinate (Wm) or None.
  • name_Wm_kwds_radius - Optional name=NN (str), optionally, additional Wm keyword arguments, ignored if Wm is None and DEPRECATED keyword argument radius=earth, use earth.
Returns:
The WM coordinate (Wm) or if Wm is None, an EasNorRadius3Tuple(easting, northing, radius).
Raises:
  • ValueError - If earth is invalid, if lon value is missing, if latlon is not scalar, or if latlon is beyond the valid WM range and rangerrrors is True.

toise2m (toises)

 

Convert French toises to meter.

Arguments:
  • toises - Value in toises (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid toises.

See Also: Function fathom2m.

trfTransform0 (reframe, reframe2, epoch=None, epoch2=None, indirect=True, inverse=True, exhaust=False)

 

Get a Helmert transform to convert one reframe observed at epoch to an other reframe2 at observed at epoch2 or epoch.

Returns:
A TransformXform instance, a 0-tuple for unity, identity or None if no conversion exists.

See Also: Function trfTransforms for futher details.

trfTransforms (reframe, reframe2, epoch=None, epoch2=None, indirect=True, inverse=True, exhaust=False)

 

Yield all Helmert transform to convert one reframe observed at epoch to an other reframe2 at observed at epoch2 or epoch.

Arguments:
  • reframe - The frame to convert from (RefFrame or str).
  • reframe2 - The frame to convert to (RefFrame or str).
  • epoch - Epoch to observe from (Epoch, scalar or str), otherwise reframe's epoch.
  • epoch2 - Optional epoch to observe to (Epoch, scalar or str), otherwise epoch.
  • indirect - If True, include transforms via one intermediate reframe, otherwise only direct reframe to reframe2 transforms (bool).
  • inverse - If True, include inverse, otherwise only forward transforms (bool).
  • exhaust - If True, exhaustively generate all transforms, forward and inverse and via any number of intermediate reframes (bool).
Returns:
A TransformXform instance for each available conversion, without duplicates.
Raises:
  • TRFError - Invalid reframe, reframe2, epoch or epoch2.
  • TypeError - Invalid reframe or reframe2.

trfXform (reframe1, reframe2, epoch=None, xform=None, rates=None, raiser=True)

 

Define a new Terrestrial Reference Frame (TRF) converter or get an existing one.

Arguments:
  • reframe1 - Source frame (RefFrame or str), converting from.
  • reframe2 - Destination frame (RefFrame or str), converting to.
  • epoch - Epoch, a fractional year (Epoch, scalar or str) or None for reframe2's epoch.
  • xform - Transform parameters (TRFXform7Tuple).
  • rates - Rate parameters (TRFXform7Tuple), as xform, but in units-per-year.
  • raiser - If False, do not raise an error if the converter exists, replace it (bool).
Returns:
The new TRF converter (TRFXform) or if no epoch, xform and rates are given, return the existing one (TRFXform) or None if not available.
Raises:
  • TRFError - Invalid reframe1, reframe2, epoch, xform or rates or the TRF converter already exists.

triAngle (a, b, c)

 

Compute one angle of a triangle.

Arguments:
  • a - Adjacent triangle side length (scalar, non-negative meter, conventionally).
  • b - Adjacent triangle side length (scalar, non-negative meter, conventionally).
  • c - Opposite triangle side length (scalar, non-negative meter, conventionally).
Returns:
Angle in radians at triangle corner C, opposite triangle side c.
Raises:

See Also: Functions triAngle5 and triSide.

triAngle4 (a, b, c)

 

DEPRECATED on 2023.09.14, use function pygeodesy.triAngle5.

Returns:
A DEPRECATED TriAngle4Tuple(radA, radB, radC, rIn).
Decorators:
  • @deprecated_function

triAngle5 (a, b, c)

 

Compute the angles of a triangle.

Arguments:
  • a - Length of the triangle side opposite of triangle corner A (scalar, non-negative meter, conventionally).
  • b - Length of the triangle side opposite of triangle corner B (scalar, non-negative meter, conventionally).
  • c - Length of the triangle side opposite of triangle corner C (scalar, non-negative meter, conventionally).
Returns:
TriAngle5Tuple(radA, radB, radC, rIn, area) with angles radA, radB and radC at triangle corners A, B and C, all in radians, the InCircle radius rIn aka inradius, same units as triangle sides a, b and c and the triangle area in those same units squared.
Raises:

See Also: Functions triAngle and triArea.

triArea (a, b, c)

 

Compute the area of a triangle using Heron's stable formula.

Arguments:
  • a - Length of the triangle side opposite of triangle corner A (scalar, non-negative meter, conventionally).
  • b - Length of the triangle side opposite of triangle corner B (scalar, non-negative meter, conventionally).
  • c - Length of the triangle side opposite of triangle corner C (scalar, non-negative meter, conventionally).
Returns:
The triangle area (float, conventionally meter or same units as a, b and c squared).
Raises:

triSide (a, b, radC)

 

Compute one side of a triangle.

Arguments:
  • a - Adjacent triangle side length (scalar, non-negative meter, conventionally).
  • b - Adjacent triangle side length (scalar, non-negative meter, conventionally).
  • radC - Angle included by sides a and b, opposite triangle side c (radians).
Returns:
Length of triangle side c, opposite triangle corner C and angle radC, same units as a and b.
Raises:

See Also: Functions sqrt_a, triAngle, triSide2 and triSide4.

triSide2 (b, c, radB)

 

Compute a side and its opposite angle of a triangle.

Arguments:
  • b - Adjacent triangle side length (scalar, non-negative meter, conventionally).
  • c - Adjacent triangle side length (scalar, non-negative meter, conventionally).
  • radB - Angle included by sides a and c, opposite triangle side b (radians).
Returns:
TriSide2Tuple(a, radA) with triangle angle radA in radians and length of the opposite triangle side a, same units as b and c.
Raises:

See Also: Functions sqrt_a, triSide and triSide4.

triSide4 (radA, radB, c)

 

Compute two sides and the height of a triangle.

Arguments:
  • radA - Angle at triangle corner A, opposite triangle side a (non-negative radians).
  • radB - Angle at triangle corner B, opposite triangle side b (non-negative radians).
  • c - Length of triangle side between triangle corners A and B, (scalar, non-negative meter, conventionally).
Returns:
TriSide4Tuple(a, b, radC, d) with triangle sides a and b and triangle height d perpendicular to triangle side c, all in the same units as c and interior angle radC in radians at triangle corner C, opposite triangle side c.
Raises:

See Also: Triangulation, Surveying and functions sqrt_a, triSide and triSide2.

triaxum5 (points, useZ=True)

 

Best-fit a triaxial ellipsoid through three or more (3-D) points.

Arguments:
  • points - Iterable of points (each a Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • useZ - If True, use the points' Z component, otherwise force z=INT0 (bool).
Returns:
Triaxum5Tuple(a, b, c, rank, residuals) with the unordered triaxial radii a, b and c in meter, same units as the points' coordinates.
Raises:
  • ImportError - Package numpy not found, not installed or older than version 1.10.
  • NumPyError - Some numpy issue.
  • PointsError - Too few points.
  • TypeError - One of the points is invalid.

See Also: Charles Jekel's "Least Squares Ellipsoid Fit" and numpy.linalg.lstsq.

trilaterate2d2 (x1, y1, radius1, x2, y2, radius2, x3, y3, radius3, eps=None, **Vector_and_kwds)

 

Trilaterate three circles, each given as a (2-D) center and a radius.

Arguments:
  • x1 - Center x coordinate of the 1st circle (scalar).
  • y1 - Center y coordinate of the 1st circle (scalar).
  • radius1 - Radius of the 1st circle (scalar).
  • x2 - Center x coordinate of the 2nd circle (scalar).
  • y2 - Center y coordinate of the 2nd circle (scalar).
  • radius2 - Radius of the 2nd circle (scalar).
  • x3 - Center x coordinate of the 3rd circle (scalar).
  • y3 - Center y coordinate of the 3rd circle (scalar).
  • radius3 - Radius of the 3rd circle (scalar).
  • eps - Tolerance to check the trilaterated point delta on all 3 circles (scalar) or None for no checking.
  • Vector_and_kwds - Optional class Vector=None to return the trilateration and optionally, additional Vector keyword arguments).
Returns:
Trilaterated point as Vector(x, y, **Vector_kwds) or Vector2Tuple(x, y) if Vector is None.
Raises:
  • IntersectionError - No intersection, near-concentric or -colinear centers, trilateration failed some other way or the trilaterated point is off one circle by more than eps.
  • UnitError - Invalid radius1, radius2 or radius3.

trilaterate3d2 (center1, radius1, center2, radius2, center3, radius3, eps=2.220446049250313e-16, **Vector_and_kwds)

 

Trilaterate three spheres, each given as a (3-D) center and a radius.

Arguments:
  • center1 - Center of the 1st sphere (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • radius1 - Radius of the 1st sphere (same units as x, y and z).
  • center2 - Center of the 2nd sphere (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • radius2 - Radius of this sphere (same units as x, y and z).
  • center3 - Center of the 3rd sphere (Cartesian, Vector3d, Vector3Tuple or Vector4Tuple).
  • radius3 - Radius of the 3rd sphere (same units as x, y and z).
  • eps - Pertubation tolerance (scalar), same units as x, y and z or None for no pertubations.
  • Vector_and_kwds - Optional class Vector=None to return the trilateration and optionally, additional Vector keyword arguments, otherwise center1's (sub-)class.
Returns:
2-Tuple with two trilaterated points, each a Vector instance. Both points are the same instance if all three spheres abut/intersect in a single point.
Raises:
  • ImportError - Package numpy not found, not installed or older than version 1.10.
  • IntersectionError - Near-concentric, -colinear, too distant or non-intersecting spheres.
  • NumPyError - Some numpy issue.
  • TypeError - Invalid center1, center2 or center3.
  • UnitError - Invalid radius1, radius2 or radius3.

truncate (x, ndigits=None)

 

Truncate to the given number of digits.

Arguments:
  • x - Value to truncate (scalar).
  • ndigits - Number of digits (int), aka precision.
Returns:
Truncated x (float).

See Also: Python function round.

tyr3d (tilt=0, yaw=0, roll=0, Vector=<class 'pygeodesy.vector3d.Vector3d'>, **name_Vector_kwds)

 

Convert an attitude pose into a (3-D) direction vector.

Arguments:
  • tilt - Pitch, elevation from horizontal (degrees), negative down (clockwise rotation along and around the x-axis).
  • yaw - Bearing, heading (compass degrees360), clockwise from North (counter-clockwise rotation along and around the z-axis).
  • roll - Roll, bank (degrees), positive to the right and down (clockwise rotation along and around the y-axis).
  • Vector - Class to return the direction vector (Cartesian, Vector3d or Vector3Tuple) or None.
  • name_Vector_kwds - Optional name=NN (str) and optionally, additional Vector keyword arguments, ignored if Vector is None.
Returns:
A named Vector instance or if Vector is None, a named Vector3Tuple(x, y, z).
Raises:
  • AttitudeError - Invalid tilt, yaw or roll.
  • TypeError - Invalid Vector or name_Vector_kwds.

See Also: Yaw, pitch, and roll rotations and function pygeodesy.hartzell argument los, Line-Of-Sight.

unStr (name, *args, **kwds)

 

DEPRECATED, use function pygeodesy.unstr.

Decorators:
  • @deprecated_function

unroll180 (lon1, lon2, wrap=True)

 

Unroll longitudinal delta and wrap longitude in degrees.

Arguments:
  • lon1 - Start longitude (degrees).
  • lon2 - End longitude (degrees).
  • wrap - If True, wrap and unroll to the (-180..+180] range (bool).
Returns:
2-Tuple (lon2-lon1, lon2) unrolled (degrees, degrees).

See Also: Capability LONG_UNROLL in GeographicLib.

unrollPI (rad1, rad2, wrap=True)

 

Unroll longitudinal delta and wrap longitude in radians.

Arguments:
  • rad1 - Start longitude (radians).
  • rad2 - End longitude (radians).
  • wrap - If True, wrap and unroll to the (-PI..+PI] range (bool).
Returns:
2-Tuple (rad2-rad1, rad2) unrolled (radians, radians).

See Also: Capability LONG_UNROLL in GeographicLib.

unsign0 (x)

 

DEPRECATED, use function pygeodesy.unsigned0.

Decorators:
  • @deprecated_function

unsigned0 (x)

 

Unsign if 0.0.

Returns:
x if x else 0.0.

unstr (where, *args, **kwds_)

 

Return the string representation of an invokation.

Arguments:
  • where - Class, function, method (type) or name (str).
  • args - Optional positional arguments.
  • kwds_ - Optional keyword arguments, except _Cdot=None, _ELLIPSIS=False and _fmt=Fmt.g.
Returns:
Representation (str).

upsZoneBand5 (lat, lon, strict=True, **name)

 

Return the UTM/UPS zone number, polar Band letter, pole and clipped lat- and longitude for a given location.

Arguments:
  • lat - Latitude in degrees (scalar or str).
  • lon - Longitude in degrees (scalar or str).
  • strict - Restrict lat to UPS ranges (bool).
  • name - Optional Ups name=NN (str).
Returns:
A UtmUpsLatLon5Tuple(zone, band, hemipole, lat, lon) where hemipole is the 'N'|'S' pole, the UPS projection top/center and lon [-180..180).
Raises:
  • RangeError - If strict is True and lat within the UTM but not the UPS range or if lat or lon outside the valid range and rangerrors is True.
  • ValueError - Invalid lat or lon.

Note: The lon is set to 0 if lat is -90 or 90, see env variable PYGEODESY_UPS_POLES in module ups.

utmZoneBand2 (lat, lon)

 

DEPRECATED, use function pygeodesy.utmZoneBand5.

Returns:
2-Tuple (zone, band).
Decorators:
  • @deprecated_function

utmZoneBand5 (lat, lon, cmoff=False, **name)

 

Return the UTM zone number, Band letter, hemisphere and (clipped) lat- and longitude for a given location.

Arguments:
  • lat - Latitude in degrees (scalar or str).
  • lon - Longitude in degrees (scalar or str).
  • cmoff - If True, offset longitude from the zone's central meridian (bool).
  • name - Optional name=NN (str).
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 is True.
  • ValueError - Invalid lat or lon.

utmupsValidate (coord, falsed=False, MGRS=False, Error=<class 'pygeodesy.utmups.UTMUPSError'>)

 

Check a UTM or UPS coordinate.

Arguments:
  • coord - The UTM or UPS coordinate (Utm, Etm, Ups or 5+Tuple).
  • falsed - If True, easting and northing are falsed in the coord 5+Tuple (bool), ignored otherwise.
  • MGRS - Increase easting and northing ranges (bool).
  • Error - Optional error to raise, overriding the default (UTMUPSError).
Returns:
None if validation passed.
Raises:
  • Error - Validation failed.

See Also: Function utmupsValidateOK.

utmupsValidateOK (coord, falsed=False, ok=True)

 

Check a UTM or UPS coordinate.

Arguments:
  • coord - The UTM or UPS coordinate (Utm, Ups or 5+Tuple).
  • falsed - If True, easting and northing are falsed in the coord 5+Tuple (bool), ignored otherwise.
  • ok - Result to return if validation passed (ok).
Returns:
ok if validation passed, otherwise the UTMUPSError.

See Also: Function utmupsValidate.

utmupsZoneBand5 (lat, lon, cmoff=False, **name)

 

Return the UTM/UPS zone number, Band letter, hemisphere/pole and clipped lat- and longitude for a given location.

Arguments:
  • lat - Latitude in degrees (scalar or str).
  • lon - Longitude in degrees (scalar or str).
  • cmoff - If True, offset longitude from the zone's central meridian, for UTM only (bool).
  • name - Optional name=NN (str).
Returns:
A UtmUpsLatLon5Tuple(zone, band, hemipole, lat, lon) where hemipole is 'N'|'S', the UTM hemisphere or UPS pole, 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 is True.
  • ValueError - Invalid lat or lon.

vincentys (lat1, lon1, lat2, lon2, radius=6371008.771415, wrap=False)

 

Compute the distance between two (spherical) points using Vincenty's spherical formula.

Arguments:
  • lat1 - Start latitude (degrees).
  • lon1 - Start longitude (degrees).
  • lat2 - End latitude (degrees).
  • lon2 - End longitude (degrees).
  • radius - Mean earth radius (meter), datum (Datum) or ellipsoid (Ellipsoid, Ellipsoid2 or a_f2Tuple) to use.
  • wrap - If True, wrap or normalize and unroll lat2 and lon2 (bool).
Returns:
Distance (meter, same units as radius).
Raises:

See Also: Functions vincentys_, cosineLaw, equirectangular, euclidean, flatLocal/hubeny, flatPolar, haversine and thomas and methods Ellipsoid.distance2, LatLon.distanceTo* and LatLon.equirectangularTo.

Note: See note at function vincentys_.

vincentys_ (geohash1, geohash2, **radius_wrap)

 

Compute the distance between two geohashes using the pygeodesy.vincentys formula.

Arguments:
  • geohash1 - First geohash (Geohash, LatLon or str).
  • geohash2 - Second geohash (Geohash, LatLon or str).
  • radius_wrap - Optional keyword arguments for function pygeodesy.vincentys.
Returns:
Distance (meter, same units as radius).
Raises:
  • TypeError - If geohash1 or geohash2 is not a Geohash, LatLon or str.

wildberger3 (a, b, c, alpha, beta, R3=<built-in function min>)

 

Snellius' surveying using Rational Trigonometry.

Arguments:
  • a - Length of the triangle side between corners B and C and opposite of triangle corner A (scalar, non-negative meter, conventionally).
  • b - Length of the triangle side between corners C and A and opposite of triangle corner B (scalar, non-negative meter, conventionally).
  • c - Length of the triangle side between corners A and B and opposite of triangle corner C (scalar, non-negative meter, conventionally).
  • alpha - Angle subtended by triangle side b (degrees, non-negative).
  • beta - Angle subtended by triangle side a (degrees, non-negative).
  • R3 - Callable to determine R3 from (R3 - C)**2 = D, typically standard Python function min or max, invoked with 2 arguments.
Returns:
Survey3Tuple(PA, PB, PC) with distance from survey point P to each of the triangle corners A, B and C, same units as a, b and c.
Raises:
  • TriangleError - Invalid a, b or c or negative alpha or beta or R3 not callable.

wrap180 (deg)

 

Wrap degrees to [-180..+180].

Arguments:
  • deg - Angle (degrees).
Returns:
Degrees, wrapped (degrees180).

wrap360 (deg)

 

Wrap degrees to [0..+360).

Arguments:
  • deg - Angle (degrees).
Returns:
Degrees, wrapped (degrees360).

wrap90 (deg)

 

Wrap degrees to [-90..+90].

Arguments:
  • deg - Angle (degrees).
Returns:
Degrees, wrapped (degrees90).

wrapPI (rad)

 

Wrap radians to [-PI..+PI].

Arguments:
  • rad - Angle (radians).
Returns:
Radians, wrapped (radiansPI).

wrapPI2 (rad)

 

Wrap radians to [0..+2PI).

Arguments:
  • rad - Angle (radians).
Returns:
Radians, wrapped (radiansPI2).

wrapPI_2 (rad)

 

Wrap radians to [-PI/2..+PI/2].

Arguments:
  • rad - Angle (radians).
Returns:
Radians, wrapped (radiansPI_2).

wrap_normal (*normal)

 

Define the operation for the keyword argument wrap=True, across pygeodesy: wrap, normalize or no-op. For backward compatibility, the default is wrap.

Arguments:
  • normal - If True, normalize lat- and longitude using normal or normal_, if False, wrap the lat- and longitude individually by wrap90 or wrapPI_2 respectively wrap180, wrapPI or if None, leave lat- and longitude unchanged. To get the current setting, do not specify.
Returns:
The previous wrap_normal setting (bool or None).

xyz2rtp (x_xyz, y=0, z=0, **name)

 

Convert cartesian (x, y, z) to spherical, polar (r, theta, phi) coordinates.

Returns:
RadiusThetaPhi3Tuple(r, theta, phi) with theta and phi, both in Degrees.

See Also: Function xyz2rtp_ for further details.

xyz2rtp_ (x_xyz, y=0, z=0, **name)

 

Convert cartesian (x, y, z) to spherical, polar (r, theta, phi) coordinates.

Arguments:
  • x_xyz - X component (scalar) or a cartesian (Cartesian, Ecef9Tuple, Nvector, Vector3d, Vector3Tuple, Vector4Tuple or a tuple or list of 3+ scalar items) if no y_z specified.
  • y - Y component (scalar), required if x_xyz is scalar, ignored otherwise.
  • z - Z component (scalar), like y.
  • name - Optional name=NN (str).
Returns:
RadiusThetaPhi3Tuple(r, theta, phi) with radial distance r (meter, same units as x, y and z), inclination theta (with respect to the positive z-axis) and azimuthal angle phi, both in Radians.

See Also: Physics convention (ISO 80000-2:2019), class RadiusThetaPhi3Tuple and function xyz2rtp.

yard2m (yards)

 

Convert UK yards to meter.

Arguments:
  • yards - Value in yards (scalar).
Returns:
Value in meter (float).
Raises:
  • ValueError - Invalid yards.

zcrt (x)

 

Return the 6-th, zenzi-cubic root, x**(1 / 6), preserving type(x).

Arguments:
Returns:
Zenzi-cubic root (float or Fsum).
Raises:
  • TypeeError - Invalid x.
  • ValueError - Negative x.

See Also: Functions bqrt and zqrt.

zqrt (x)

 

Return the 8-th, zenzi-quartic or squared-quartic root, x**(1 / 8), preserving type(x).

Arguments:
Returns:
Zenzi-quartic root (float or Fsum).
Raises:
  • TypeeError - Invalid x.
  • ValueError - Negative x.

See Also: Functions bqrt and zcrt.


Variables Details

pygeodesy_abspath

Fully qualified pygeodesy directory name (str).
Value:
'..../PyGeodesy/p\
ygeodesy'

Conics

Registered, predefined conics (enum-like).
Value:
Conics.WRF_Lb: Conic(name='WRF_Lb', lat0=40, lon0=-97, par1=33, par2=4\
5, E0=0, N0=0, k0=1, SP=2, datum=Datum(name='WGS84', ellipsoid=Ellipso\
ids.WGS84, transform=Transforms.WGS84))

Datums

Registered, predefined datums (enum-like).
Value:
Datums.Sphere: Datum(name='Sphere', ellipsoid=Ellipsoids.Sphere, trans\
form=Transforms.WGS84),
Datums.NAD83: Datum(name='NAD83', ellipsoid=Ellipsoids.GRS80, transfor\
m=Transforms.NAD83),
Datums.OSGB36: Datum(name='OSGB36', ellipsoid=Ellipsoids.Airy1830, tra\
nsform=Transforms.OSGB36),
Datums.WGS84: Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transfor\
m=Transforms.WGS84),
...

Ellipsoids

Registered, predefined ellipsoids (enum-like).
Value:
Ellipsoids.Sphere: Ellipsoid(name='Sphere', a=6371008.771415, f=0, f_=\
0, b=6371008.771415),
Ellipsoids.GRS80: Ellipsoid(name='GRS80', a=6378137, f=0.00335281, f_=\
298.2572221, b=6356752.31414035),
Ellipsoids.WGS84: Ellipsoid(name='WGS84', a=6378137, f=0.00335281, f_=\
298.25722356, b=6356752.31424518),
Ellipsoids.Airy1830: Ellipsoid(name='Airy1830', a=6377563.396, f=0.003\
34085, f_=299.3249646, b=6356256.90923729)

RefFrames

Registered, predefined reference frames (enum-like).
Value:
RefFrames.ETRF89: RefFrame(name='ETRF89', epoch=1989, datum=Datums.GRS\
80),
RefFrames.NAD83cors96: RefFrame(name='NAD83cors96', epoch=1997, datum=\
Datums.GRS80),
RefFrames.GDA2020: RefFrame(name='GDA2020', epoch=2020, datum=Datums.G\
RS80),
RefFrames.ETRF92: RefFrame(name='ETRF92', epoch=1992, datum=Datums.GRS\
80),
...

Transforms

Registered, predefined transforms (enum-like).
Value:
Transforms.OSGB36: Transform(name='OSGB36', tx=-446.45, ty=125.16, tz=\
-542.06, s1=1.0, rx=-7.2819e-07, ry=-1.1975e-06, rz=-4.0826e-06, s=20.\
489, sx=-0.1502, sy=-0.247, sz=-0.8421),
Transforms.NAD83: Transform(name='NAD83', tx=1.004, ty=-1.91, tz=-0.51\
5, s1=1.0, rx=1.2945e-07, ry=1.6484e-09, rz=5.333e-08, s=-0.0015, sx=0\
.0267, sy=0.00034, sz=0.011),
Transforms.WGS84: Transform(name='WGS84', tx=0.0, ty=0.0, tz=0.0, s1=1\
.0, rx=0.0, ry=0.0, rz=0.0, s=0.0, sx=0.0, sy=0.0, sz=0.0),
...