Home | Trees | Indices | Help |
|
---|
|
A pure Python implementation of geodesy tools for various ellipsoidal and spherical earth models using precision trigonometric, vector-based and approximate methods for geodetic (lat-/longitude) and geocentric cartesian (x/y/z) coordinates.
Transcribed from JavaScript originals by Chris Veness (C) 2005-2016 and published under the same MIT License**.
There are three modules for ellipsoidal earth models, ellipsoidalKarney, -Vincenty and -Nvector and two for spherical ones, sphericalTrigonometry and -Nvector. Each module provides a LatLon class with methods and functions to compute distance, initial and final bearing, intermediate and nearest points, area, perimeter, conversions and unrolling, among other things. For more information and further details see the documentation, the descriptions of Latitude/Longitude, Vincenty and Vector-based geodesy, the original JavaScript source or docs and GeographicLib Python.
Also included are modules for conversions to and from UTM (Universal Transverse Mercator) and Web Mercator (Pseudo-Mercator) coordinates, MGRS (NATO Military Grid Reference System) and OSGR (British Ordinance Survery Grid Reference) grid references and a module for encoding and decoding Geohashes.
Two other modules provide Lambert conformal conic projections and positions (from John P. Snyder, "Map Projections -- A Working Manual", 1987, pp 107-109) and several 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.
All Python source code has been statically checked with PyChecker, PyFlakes, PyCodeStyle (formerly Pep8) and McCabe using Python 2.7.15 and with Flake8 using Python 3.7.0, both in 64-bit on macOS 10.13.6 High Sierra.
The tests have been run in 64-bit with PyPy-Python 2.7.13, Python 2.7.15 (with geographiclib 1.49 and numpy 1.14.0), Intel-Python 3.5.3 (and numpy 1.11.3) and Python 3.7.0 (with geographiclib 1.49), all on macOS 10.13.6 High Sierra, with 64-bit Python 3.7.0 on Debian GNU/Linux 9 and with Pythonista 3.2 Python 2.7.12 and 3.6.1 (both with numpy 1.8.0) on iOS 11.4.1 (iPad and iPhone X).
Previously, the tests were run with 64-bit Python 2.6.9 (and numpy 1.6.2), 2.7.10 (and numpy 1.8.0rc1), 2.7.13, 2.7.14 (and numpy 1.13.1), 3.5.3, 3.6.2, 3.6.3, 3.6.4 and 3.6.5 on MacOS X 10.10 Yosemite, MacOS X 10.11 El Capitan, macOS 10.12 Sierra, macOS 10.13.4 and/or 10.13.5 High Sierra, with Pythonista 3.1 on iOS 10.3.3, 11.0.3, 11.1.2 and 11.3, with 32-bit Python 2.6.6 on Windows XP SP3, with 32-bit Python 2.7.14 on Windows 10 Pro.
In addition to the PyGeodesy package, the distribution files contain the
tests, the test results and the complete documentation (generated by Epydoc using
command line: epydoc --html --no-private --no-source
--name=PyGeodesy --url=... -v pygeodesy
).
To install PyGeodesy, type pip install PyGeodesy
or
easy_install PyGeodesy
in a terminal or command window.
Alternatively, download PyGeodesy-
from PyPI or
GitHub,
unzip
the downloaded file, cd
to directory
Pygeodesy-
and type python setup.py install
.
To run all PyGeodesy tests, type python setup.py test
before
installation.
Installation of NumPy and GeographicLib is optional. However, the latter is required for module ellipsoidalKarney classes LatLon and Cartesian and the functions areaOf and perimeterOf.
Some function and method names differ from the JavaScript version. In such cases documentation tag JS name: shows the original JavaScript name.
__
**) Copyright (C) 2016-2018 -- mrJean1 at Gmail dot com
Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction,
including without limitation the rights to use, copy, modify, merge,
publish, distribute, sublicense, and/or sell copies of the Software, and
to permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the
Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Version: 18.09.09
Submodules | |
|
Classes | |
CrossError Error raised for zero or near-zero vectorial cross products, occurring for coincident or colinear points, paths or bearings. |
|
Geohash Geohash class, sub-class of str. |
|
VincentyError Error raised from Vincenty's direct and inverse methods for coincident points and lack of convergence. |
|
Conic Lambert conformal conic projection (1- or 2-SP). |
|
Datum Ellipsoid and transform parameters for an earth model. |
|
Ellipsoid Ellipsoid with semi-major, semi-minor axis, inverse flattening and a number of other pre-computed, frequently used values. |
|
Fsum Precision floating point summation similar to standard Python function math.fsum. |
|
LatLon2psxy Wrapper for LatLon points as "on-the-fly" pseudo-xy coordinates. |
|
LatLon_ Low-overhead LatLon class for Numpy2LatLon or Tuple2LatLon' |
|
Lcc Lambert conformal conic East-/Northing location. |
|
LimitError Error raised for lat- and/or longitudinal deltas exceeding the limit in functions equirectangular and equirectangular_. |
|
Mgrs Military Grid Reference System (MGRS/NATO) references, with method to convert to UTM coordinates. |
|
Numpy2LatLon Wrapper for NumPy arrays as "on-the-fly" LatLon points. |
|
Osgr Ordinance Survey Grid References (OSGR) coordinate. |
|
RangeError Error raised for lat- or longitude values outside the clip, clipLat, clipLon or limit range in function clipDMS, parse3llh, parseDMS or parseDMS2. |
|
Transform Helmert transformation. |
|
Tuple2LatLon Wrapper for tuple sequences as "on-the-fly" LatLon points. |
|
UTMError UTM parse or other error. |
|
Utm Universal Transverse Mercator (UTM) coordinate. |
|
Wm Web Mercator (WM) coordinate. |
Functions | |||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
|||
|
Variables | |
version =
Normalized PyGeodesy version (string).
|
|
Conics = Conics.Be08Lb: Conic(name='Be08Lb', lat0=50.797815, l Registered conics (enum). |
|
Datums = Datums.BD72: Datum(name='BD72', ellipsoid=Ellipsoids. Registered datums (enum). |
|
EPS = 2.22044604925e-16 System's epsilon (float) |
|
EPS1 = 1.0 1 - EPS (float), about 0.9999999999999998 |
|
EPS2 = 1.49011611938e-08 sqrt(EPS) (float) |
|
Ellipsoids = Ellipsoids.Airy1830: Ellipsoid(name='Airy1830', a Registered ellipsoids (enum). |
|
F_D =
Format degrees as deg° (string). |
|
F_DEG =
Format degrees as [D]DD without symbol (string). |
|
F_DM =
Format degrees as deg°min′ (string). |
|
F_DMS =
Format degrees as deg°min′sec″ (string). |
|
F_MIN =
Format degrees as [D]DDMM without symbols (string). |
|
F_RAD =
Convert degrees to radians and format as RR (string). |
|
F_SEC =
Format degrees as [D]DDMMSS without symbols (string). |
|
PI = 3.14159265359 Constant math.pi (float) |
|
PI2 = 6.28318530718 Two PI, math.pi * 2 (float) |
|
PI_2 = 1.57079632679 Half PI, math.pi / 2 (float) |
|
R_FM = 6371000.0 Former FAI Sphere earth radius (meter). |
|
R_KM = 6371.00877142 Mean, spherical earth radius (kilo meter). |
|
R_M = 6371008.77141 Mean, spherical earth radius (meter). |
|
R_MA = 6378137.0 Equatorial earth radius (meter) WGS84, EPSG:3785. |
|
R_MB = 6356752.0 Polar earth radius (meter) WGS84, EPSG:3785. |
|
R_NM = 3440.06953447 Mean, spherical earth radius (nautical miles). |
|
R_SM = 3958.75339537 Mean, spherical earth radius (statute miles). |
|
R_VM = 6366707.01949 Aviation/Navigation earth radius (meter). |
|
S_DEG =
Degrees symbol ° (string). |
|
S_MIN =
Minutes symbol ′ (string). |
|
S_RAD =
Radians symbol (string). |
|
S_SEC =
Seconds symbol ″ (string). |
|
S_SEP =
Separator between deg°, min′ and sec″ (string). |
|
Transforms = Transforms.BD72: Transform(name='BD72', tx=106.86 Registered transforms (enum). |
Function Details |
Get/set raising of vectorial cross product errors.
|
Return the antipode, the point diametrically opposite to the given lat- and longitude.
See Also: Geosphere. |
Approximate the area of a polygon defined by an array, list, sequence, set or tuple of points.
Note: This is an area approximation with limited accuracy, ill-suited for regions exceeding several hundred Km or Miles or with near-polar latitudes. See Also: sphericalNvector.areaOf, sphericalTrigonometry.areaOf and ellipsoidalKarney.areaOf. |
Convert bearing to a string.
JS name: toBrng. |
Determine the lower-left and upper-right corners of a polygon/-line defined by a list, sequence, set or tuple of points.
Example: >>> b = LatLon(45,1), LatLon(45,2), LatLon(46,2), LatLon(46,1) >>> bounds(b) # False >>> 45.0, 1.0, 46.0, 2.0 |
Compute the cubic root x**(1/3).
|
Compute the cubic root squared x**(2/3).
See Also: Function sqrt3. |
Return an instance' module and class name.
|
Set the default class naming for
|
Clip a lat- or longitude to the given range.
|
Return the angle from North for the direction vector (lon1 - lon0, lat1 - lat0) between two points. Suitable only for short, non-near-polar vectors up to a few hundred Km or Miles. Use LatLon methods initialBearingTo or forward azimuth for larger distances.
Note: Courtesy Martin Schultz. See Also: Local, Flat Earth. |
Convert bearing to a string suffixed with compass point.
|
Convert bearing to a compass point.
See Also: Compass rose Example: >>> p = compassPoint(24) # 'NNE' >>> p = compassPoint(24, 1) # 'N' >>> p = compassPoint(24, 2) # 'NE' >>> p = compassPoint(18, 3) # 'NNE' >>> p = compassPoint(12, 4) # 'NbE' >>> p = compassPoint(30, 4) # 'NEbN' |
Convert and wrap radians to degrees (-180..+180].
|
Convert and wrap radians to degrees (0..+360].
|
Convert and wrap radians to degrees (-270..+90].
|
Get the geoid elevation at an
Note:
The returned elevation is None if lat or lon is
invalid or outside the See Also: USGS National Map, the FAQ and USGS10mElev.py. |
Return easting, northing string representations.
|
Compute the distance between two points using the Equirectangular Approximation / Projection. See function equirectangular_ for more details, the available options and errors raised.
See Also: Local, Flat Earth, method Ellipsoid.distance2 or function haversine for more accurate and/or larger distances. |
Compute the distance between two points using the Equirectangular Approximation / Projection. This approximation is valid for smaller distance of several hundred Km or Miles, see the limit keyword argument and the LimitError.
See Also: Local, Flat Earth, method Ellipsoid.distance2, function equirectangular for distance only and function haversine for accurate and/or larger distances. |
Convert floats to string, optionally with trailing zero decimals stripped.
|
Strip trailing zero decimals from a float string.
|
Convert a false east-/northing to non-negative float.
|
Return the weighted average of two values.
|
Return the precision dot product sum(a[i] * b[i] for i=0..len(a)).
|
Return the precision dot product start + sum(a[i] * b[i] * c[i] for i=0..len(a)).
|
Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)) using the Horner form.
|
Compute the accurate mean sum(xs[i] for i=0..len(xs)) / len(xs).
|
Evaluate the polynomial sum(cs[i] * x**i for i=0..len(cs)).
|
Return a series of powers [x**i for i=1..n].
|
Return an accurate floating point sum of values in the iterable. Assumes IEEE-754 floating point arithmetic. |
Precision floating point summation of the positional arguments.
|
Convert International feet to meter (m).
|
Get the
Note:
The returned height is CNone if lat or lon is invalid
or outside the See Also: NOAA National Geodetic Survery and Geoid |
Split a string in 2 halfs.
|
Compute the distance between two points using the Haversine formula.
See Also: Distance between two (spherical) points and function equirectangular or method Ellipsoid.distance2 for distance approximations. |
Compute the angular distance between two points using the Haversine formula.
See Also: Function haversine. |
Determine the height above the (spherical) earth after traveling along a straight line at a given tilt.
See Also: MultiDop GeogBeamHt (Shapiro et al. 2009, JTECH and Potvin et al. 2012, JTECH). |
Determine the distance to the horizon from a given altitude above the (spherical) earth.
See Also: Distance to horizon. |
Compute the norm sqrt(1 + x**2).
|
Compute the norm sqrt(x**2 + y**2 + z**2).
|
Return the string representation of an instance.
|
Check for an Numpy2LatLon points wrapper.
|
Check for an LatLon2psxy points wrapper.
|
Check for an Tuple2LatLon points wrapper.
|
Check whether two points are anitpodal, on diametrically opposite sides of the earth.
See Also: Geosphere. |
Determine the direction of a polygon defined by an array, list, sequence, set or tuple of points.
Example: >>> f = LatLon(45,1), LatLon(45,2), LatLon(46,2), LatLon(46,1) >>> isclockwise(f) # False >>> t = LatLon(45,1), LatLon(46,1), LatLon(46,2) >>> isclockwise(t) # True |
Determine whether a polygon defined by an array, list, sequence, set or tuple of points is convex.
Example: >>> t = LatLon(45,1), LatLon(46,1), LatLon(46,2) >>> isconvex(t) # True >>> f = LatLon(45,1), LatLon(46,2), LatLon(45,2), LatLon(46,1) >>> isconvex(f) # False |
Determine whether a point is enclosed by a polygon defined by an array, list, sequence, set or tuple of points.
|
Check for Inf and NaN values.
|
Check for integer type or integer value.
|
Check for scalar types.
|
Check for sequence types.
Note: Excluding tuple implies namedtuple. |
Iterate over Numpy2 wrappers or other sequences exceeding the threshold.
|
Get or set the iterNumpy2 threshold.
|
Convert latitude to a string suffixed with N or S.
JS name: toLat. |
Make built-in function
|
Get/set the raising of limit errors.
|
Convert longitude to a string suffixed with E or W.
JS name: toLon. |
Convert meter to nautical miles (NM).
|
Convert meter to statute miles (SM).
|
Convert distance to angle along equator.
|
Convert meter to International feet (ft).
|
Convert meter to kilo meter (km).
|
Apply each argument to a single-argument function and return a tuple of results.
|
Apply arguments to a function and return a tuple of results. Unlike Python 2's built-in
|
Normalize all degree ˚, minute ' and second " symbols in a string to the default symbols °, ′ and ″.
|
Parse a string representing lat-, longitude and height point. The lat- and longitude value must be separated by a separator character. If height is present it must follow, separated by another separator. The lat- and longitude values may be swapped, provided at least one ends with the proper compass point.
|
Parse a string representing deg°min′sec″ to degrees. This is very flexible on formats, allowing signed decimal degrees, degrees and minutes or degrees minutes and seconds optionally suffixed by compass direction NSEW. A variety of symbols, separators and suffixes are accepted, for example 3° 37′ 09″W. Minutes and seconds may be omitted.
See Also: Function parse3llh to parse a string with lat-, longitude and height values. |
Parse lat- and longitude representions.
|
Parse a string representing a MGRS grid reference, consisting of zoneBand, grid, easting and northing.
Example: >>> m = parseMGRS('31U DQ 48251 11932') >>> str(m) # 31U DQ 48251 11932 >>> m = parseMGRS('31UDQ4825111932') >>> repr(m) # [Z:31U, G:DQ, E:48251, N:11932] |
Parse an OSGR coordinate string to an Osgr instance. Accepts standard OS Grid References like 'SU 387 148', with or without whitespace separators, from 2- up to 10-digit references (1 m × 1 m square), or fully numeric, comma-separated references in metres, for example '438700,114800'.
Example: >>> g = parseOSGR('TG 51409 13177') >>> str(g) # TG 51409 13177 >>> g = parseOSGR('TG5140913177') >>> str(g) # TG 51409 13177 >>> g = parseOSGR('TG51409 13177') >>> str(g) # TG 51409 13177 >>> g = parseOSGR('651409,313177') >>> str(g) # TG 51409 13177 >>> g.toStr(prec=0) # 651409,313177 |
Parse a string representing a UTM coordinate, consisting of zone, hemisphere, easting and northing.
Example: >>> u = parseUTM('31 N 448251 5411932') >>> u.toStr2() # [Z:31, H:N, E:448251, N:5411932] >>> u = parseUTM('31 N 448251.8 5411932.7') >>> u.toStr() # 31 N 448252 5411933 |
Parse a string representing a WM coordinate, consisting of easting, northing and an optional radius.
Example: >>> u = parseWM('448251 5411932') >>> u.toStr2() # [E:448251, N:5411932] |
Approximate the perimeter of a polygon/-line defined by an array, list, sequence, set or tuple of points.
Note: This perimeter is based on the equirectangular_ distance approximation and is ill-suited for regions exceeding several hundred Km or Miles or with near-polar latitudes. See Also: sphericalTrigonometry.perimeterOf and ellipsoidalKarney.perimeterOf. |
Check a polygon given as an array, list, sequence, set or tuple of points.
|
Set the default precison for a given F_ form.
|
Decorator for
Note:
Like standard Python |
Convert and wrap degrees to radians (-PI..+PI].
|
Convert and wrap degrees to radians (0..+2PI].
|
Convert and wrap degrees to radians (-3PI/2..+PI/2].
|
Gert/set raising of range errors.
Note: Out-of-range lat- and longitude values are always clipped to the nearest range limit. |
Validate a scalar.
|
Basic simplification of a path of LatLon points. Eliminates any points closer together than the given distance tolerance.
|
Reumann-Witkam simplification of a path of LatLon points. Eliminates any points too close together or within the given pipe tolerance along an edge.
|
Ramer-Douglas-Peucker (RDP) simplification of a path of LatLon points. Eliminates any points too close together or closer to an edge than the given distance tolerance. This RDP method exhaustively searches for the point with the largest distance, resulting in worst-case complexity O(n**2) where n is the number of points.
|
Modified Ramer-Douglas-Peucker (RDP) simplification of a path of LatLon points. Eliminates any points too close together or closer to an edge than the given distance tolerance. This RDP method stops at the first point farther than the given distance tolerance, significantly reducing the run time (but producing results different from the original RDP method).
|
Reumann-Witkam simplification of a path of LatLon points. Eliminates any points too close together or within the given pipe tolerance along an edge.
|
Visvalingam-Whyatt (VW) simplification of a path of LatLon points. Eliminates any points too close together or with a triangular area not exceeding the given area tolerance (squared). This VW method exhaustively searches for the single point with the smallest triangular area, resulting in worst-case complexity O(n**2) where n is the number of points.
|
Modified Visvalingam-Whyatt (VW) simplification of a path of LatLon points. Eliminates any points too close together or with a triangular area not exceeding the given area tolerance (squared). This VW method removes all points with a triangular area below the tolerance per iteration, significantly reducing the run time (but producing results different from the original VW method).
|
Compute the square root cubed sqrt(x)**3 or sqrt(x**3).
See Also: Function cbrt2. |
Compute the tangent of half angle, 90 degrees rotated.
|
Compute the tangent of half angle.
|
Convert signed degrees to string, without suffix.
|
Convert an (ellipsoidal) geodetic point to a Lambert location.
|
Convert a UTM coordinate to an MGRS grid reference.
Example: >>> u = Utm(31, 'N', 448251, 5411932) >>> m = u.toMgrs() # 31U DQ 48251 11932 |
Convert a lat-/longitude point to an OSGR coordinate.
Example: >>> p = LatLon(52.65798, 1.71605) >>> r = toOsgr(p) # TG 51409 13177 >>> # for conversion of (historical) OSGB36 lat-/longitude: >>> r = toOsgr(52.65757, 1.71791, datum=Datums.OSGB36) |
Convert a lat-/longitude point to a UTM coordinate.
Note: Implements Karney’s method, using 8-th order Krüger series, giving results accurate to 5 nm (or better) for distances up to 3900 km from the central meridian. Example: >>> p = LatLon(48.8582, 2.2945) # 31 N 448251.8 5411932.7 >>> u = toUtm(p) # 31 N 448252 5411933 >>> p = LatLon(13.4125, 103.8667) # 48 N 377302.4 1483034.8 >>> u = toUtm(p) # 48 N 377302 1483035 |
Convert a lat-/longitude point to a WM coordinate.
Example: >>> p = LatLon(48.8582, 2.2945) # 448251.8 5411932.7 >>> w = toWm(p) # 448252 5411933 >>> p = LatLon(13.4125, 103.8667) # 377302.4 1483034.8 >>> w = toWm(p) # 377302 1483035 |
Return the string representation of an invokation.
|
Unroll longitudinal delta and wrap longitude in degrees.
See Also: Capability LONG_UNROLL in GeographicLib. |
Unroll longitudinal delta and wrap longitude in radians.
See Also: Capability LONG_UNROLL in GeographicLib. |
Return the UTM zone number and UTM Band letter for a location.
|
Wrap degrees to (-180..+180].
|
Wrap degrees to (0..+360].
|
Wrap degrees to (-270..+90].
|
Wrap radians to (-PI..+PI].
|
Wrap radians to (0..+2PI].
|
Wrap radians to (-3PI/2..+PI/2].
|
Variables Details |
ConicsRegistered conics (enum).
|
DatumsRegistered datums (enum).
|
EllipsoidsRegistered ellipsoids (enum).
|
TransformsRegistered transforms (enum).
|
Home | Trees | Indices | Help |
|
---|
Generated by Epydoc 3.0.1 on Thu Sep 13 11:53:05 2018 | http://epydoc.sourceforge.net |