Package pygeodesy
[frames] | no frames]

Package pygeodesy

A pure Python implementation of geodesy tools for various ellipsoidal and spherical earth models using precision trigonometric and vector-based 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 two modules for ellipsoidal earth models, ellipsoidalVincenty and -Nvector and two for spherical ones, sphericalTrigonometry and -Nvector. Each module provides a LatLon class with methods to compute distance, initial and final bearing, intermediate points and conversions, among other things. For more information and further details see the documentation, descriptions of Latitude/Longitude, Vincenty and Vector-based geodesy and the original JavaScript source or docs.

Also included are modules for conversions to and from UTM (Universal Transverse 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, including implementations of the Ramer-Douglas-Peucker and Visvalingam-Whyatt algorithms and modified versions of both.

All Python source code has been statically checked with PyChecker, PyFlakes, PyCodeStyle (formerly Pep8) and McCabe using Python 2.7.10 or 2.7.13 and with Flake8 on Python 3.6.0 or 3.6.1.

The tests have been run with 64-bit Python 2.6.9, 2.7.13, 3.5.3 and 3.6.1, but only on MacOSX 10.10 Yosemite, MacOSX 10.11 El Capitan or macOS 10.12.2, 10.12.3, 10.12.4 or 10.12.5 Sierra and with Pythonista 3.1 using Python 2.7.12 and 3.5.1 on iOS 10.3.2.

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). The zip and tar distribution files were created with command line python setup.py sdist --formats=zip,gztar,bztar.

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-2017 -- 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: 17.06.19

Submodules

Classes
  Geohash
Geohash class, sub-class of str.
  VincentyError
Error thrown 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.
  Lcc
Lambert conformal conic East-/Northing location.
  Mgrs
Military Grid Reference System (MGRS/NATO) references, with method to convert to UTM coordinates.
  Osgr
OSGR coordinate.
  Transform
Helmert transformation.
  Utm
Universal Transverse Mercator (UTM) coordinate.
Functions
 
isclockwise(points, radius=None)
Determine the direction of a polygon defined by a list, sequence, set or tuple of LatLon points.
 
isconvex(points, radius=None)
Determine whether a polygon defined by a list, sequence, set or tuple of LatLon points is convex.
 
bearingDMS(bearing, form='d', prec=None, sep='')
Convert bearing to a string.
 
cbrt(x)
Compute the cubic root x**(1/3).
 
cbrt2(x)
Compute the cubic root squared x**(2/3).
 
compassDMS(bearing, form='d', prec=None, sep='')
Convert bearing to a string suffixed with compass point.
 
compassPoint(bearing, prec=3)
Convert bearing to a compass point.
 
degrees(x)
Convert angle x from radians to degrees.
 
degrees180(rad)
Convert and wrap radians to degrees -180..+180.
 
degrees360(rad)
Convert and wrap radians to degrees 0..+360.
 
degrees90(rad)
Convert and wrap radians to degrees -270..+90.
 
fStr(floats, prec=6, sep=', ', fmt='%.*f', ints=False)
Convert floats to string, optionally with trailing zero decimals stripped.
 
fStrzs(fstr)
Strip trailing zero decimals from a float string.
 
false2f(value, name='value', false=True)
Convert a false east-/northing to non-negative float.
 
favg(v1, v2, f=0.5)
Return the weighted average of two values.
 
fdot(a, *b)
Return the precision dot product sum(a[i] * b[i] for i in range(len(a))).
 
fdot3(a, b, c, start=0)
Return the precision dot product sum(a[i] * b[i] * c[i] for i in range(len(a))) + start.
 
fsum(iterable)
Return an accurate floating point sum of values in the iterable.
 
ft2m(feet)
Convert feet to meter (m).
 
halfs(str2)
Split a string in 2 halfs.
 
hsin(rad)
Compute the Haversine value of an angle.
 
hsin3(a2, a1, b21)
Compute the angular distance using the Haversine formula.
 
hypot(x, y)
Return the Euclidean distance, sqrt(x*x + y*y).
 
hypot1(x)
Compute the norm sqrt(1 + x**2).
 
hypot3(x, y, z)
Compute the norm sqrt(x**2 + y**2 + z**2).
 
isint(obj, both=False)
Check for integer types and value.
 
isscalar(obj)
Check for scalar types.
 
latDMS(deg, form='dms', prec=2, sep='')
Convert latitude to a string suffixed with N or S.
 
len2(xtor)
Make built-in len() function work for generators, iterators, etc.
 
lonDMS(deg, form='dms', prec=2, sep='')
Convert longitude to a string suffixed with E or W.
 
m2NM(meter)
Convert meter to nautical miles (NM).
 
m2SM(meter)
Convert meter to statute miles (SM).
 
m2ft(meter)
Convert meter to feet (ft).
 
m2km(meter)
Convert meter to kilo meter (km).
 
map1(func, *args)
Apply each argument to a single-argument function and returns a tuple of results.
 
map2(func, *args)
Apply arguments to a function and returns a tuple of results.
 
normDMS(strDMS, norm='')
Normalize all degree ˚, minute ' and second " symbols in a string to the default symbols °, ′ and ″.
 
parse3llh(strll, height=0, sep=',')
Parse a string representing lat-, longitude and height point.
 
parseDMS(strDMS, suffix='NSEW', sep='')
Parse a string representing deg°min′sec″ to degrees.
 
parseMGRS(strMGRS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)
Parse a string representing a MGRS grid reference, consisting of zoneBand, grid, easting and northing.
 
parseOSGR(strOSGR)
Parse an OSGR coordinate string to an Osgr instance.
 
parseUTM(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)
Parse a string representing a UTM coordinate, consisting of zone, hemisphere, easting and northing.
 
precision(form, prec=None)
Set the default precison for a given F_ form.
 
radians(x)
Convert angle x from degrees to radians.
 
radiansPI(deg)
Convert and wrap degrees to radians -PI..+PI.
 
radiansPI2(deg)
Convert and wrap degrees to radians 0..+2PI.
 
radiansPI_2(deg)
Convert and wrap degrees to radians -3PI/2..+PI/2.
 
simplify1(points, distance, radius=6371008.77141, adjust=True)
Basic simplification of a path of LatLon points.
 
simplify2(points, pipe, radius=6371008.77141, adjust=True, shortest=False)
Pipe simplification of a path of LatLon points.
 
simplifyRDP(points, distance, radius=6371008.77141, adjust=True, shortest=False)
Ramer-Douglas-Peucker (RDP) simplification of a path of LatLon points.
 
simplifyRDPm(points, distance, radius=6371008.77141, adjust=True, shortest=False)
Modified Ramer-Douglas-Peucker (RDP) simplification of a path of LatLon points.
 
simplifyVW(points, area, radius=6371008.77141, adjust=True, attr=None)
Visvalingam-Whyatt (VW) simplification of a path of LatLon points.
 
simplifyVWm(points, area, radius=6371008.77141, adjust=True, attr=None)
Modified Visvalingam-Whyatt (VW) simplification of a path of LatLon points.
 
tanPI_2_2(rad)
Compute tan of half angle, rotated.
 
toDMS(deg, form='dms', prec=2, sep='', ddd=2, neg='-', pos='')
Convert signed degrees to string, without suffix.
 
toLcc(latlon, conic=Conic(name='WRF_Lb', lat0=40.0, lon0=-97.0, par1=33.0, par2=45..., height=None, Lcc=<class 'pygeodesy.lcc.Lcc'>)
Convert an (ellipsoidal) geodetic point to a Lambert location.
 
toMgrs(utm, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>)
Convert a UTM coordinate to an MGRS grid reference.
 
toOsgr(latlon, lon=None, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., Osgr=<class 'pygeodesy.osgr.Osgr'>)
Convert a lat-/longitude point to an OSGR coordinate.
 
toUtm(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>)
Convert a lat-/longitude point to a UTM coordinate.
 
wrap180(deg)
Wrap degrees to -180..+180.
 
wrap360(deg)
Wrap degrees to 0..+360.
 
wrap90(deg)
Wrap degrees to -270..+90.
 
wrapPI(rad)
Wrap radians to -PI..+PI.
 
wrapPI2(rad)
Wrap radians to 0..+2PI.
 
wrapPI_2(rad)
Wrap radians to -3PI/2..+PI/2.
Variables
  version = '17.6.19'
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 = 'd'
Format degrees as deg° (string).
  F_DEG = 'deg'
Format degrees as [D]DD without symbol (string).
  F_DM = 'dm'
Format degrees as deg°min′ (string).
  F_DMS = 'dms'
Format degrees as deg°min′sec″ (string).
  F_MIN = 'min'
Format degrees as [D]DDMM without symbols (string).
  F_RAD = 'rad'
Convert degrees to radians and format as RR (string).
  F_SEC = '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_KM = 6371.00877142
Mean, spherical earth radius (kilo meter).
  R_M = 6371008.77141
Mean, spherical earth radius (meter).
  R_NM = 3440.06953447
Mean, spherical earth radius (nautical miles).
  R_SM = 3958.75339537
Mean, spherical earth radius (statute miles).
  S_DEG = '\xc2\xb0'
Degrees symbol ° (string).
  S_MIN = '\xe2\x80\xb2'
Minutes symbol ′ (string).
  S_RAD = ''
Radians symbol (string).
  S_SEC = '\xe2\x80\xb3'
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

isclockwise(points, radius=None)

 

Determine the direction of a polygon defined by a list, sequence, set or tuple of LatLon points.

Parameters:
  • points - The points defining the polygon (LatLon[]).
  • radius - Optional, mean earth radius (meter).
Returns:
True if clockwise, False otherwise.
Raises:
  • TypeError - Some points are not LatLon.
  • ValueError - Too few points or zero area polygon.

Example:

>>> f = LatLon(45,1), LatLon(45,2), LatLon(46,2), LatLon(46,1)
>>> pygeodesy.isclockwise(f)  # False
>>> t = LatLon(45,1), LatLon(46,1), LatLon(46,2)
>>> pygeodesy.isclockwise(t)  # True

isconvex(points, radius=None)

 

Determine whether a polygon defined by a list, sequence, set or tuple of LatLon points is convex.

Parameters:
  • points - The points defining the polygon (LatLon[]).
  • radius - Optional, mean earth radius (meter).
Returns:
True if convex, False otherwise.
Raises:
  • TypeError - Some points are not LatLon.
  • ValueError - Too few points or colinear point.

Example:

>>> t = LatLon(45,1), LatLon(46,1), LatLon(46,2)
>>> pygeodesy.isconvex(t)  # True
>>> f = LatLon(45,1), LatLon(46,2), LatLon(45,2), LatLon(46,1)
>>> pygeodesy.isconvex(f)  # False

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

 

Convert bearing to a string.

Parameters:
  • bearing - Bearing from North (compass degrees).
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, [D]DD, [D]DDMM, [D]DDMMSS or radians (string).
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
  • sep - Optional, separator (string).
Returns:
Compass degrees per the specified form (string).

JS name: toBrng.

cbrt(x)

 

Compute the cubic root x**(1/3).

Parameters:
  • x - Argument (scalar).
Returns:
Cubic root (float).

cbrt2(x)

 

Compute the cubic root squared x**(2/3).

Parameters:
  • x - Argument (scalar).
Returns:
Cubic root squared (float).

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

 

Convert bearing to a string suffixed with compass point.

Parameters:
  • bearing - Bearing from North (compass degrees).
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, [D]DD, [D]DDMM, [D]DDMMSS or radians (string).
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
  • sep - Optional, separator (string).
Returns:
Compass degrees and point per the specified form (string).

compassPoint(bearing, prec=3)

 

Convert bearing to a compass point.

Parameters:
  • bearing - Bearing from North (compass degrees).
  • prec - Optional precision (1 for cardinal or basic winds, 2 for intercardinal or ordinal or principal winds, 3 for secondary-intercardinal or half-winds or 4 for quarter-winds).
Returns:
Compass point (1-, 2-, 3- or 4-letter string).
Raises:
  • ValueError - Invalid prec.

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'

degrees180(rad)

 

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

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

degrees360(rad)

 

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

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

degrees90(rad)

 

Convert and wrap radians to degrees -270..+90.

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

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

 

Convert floats to string, optionally with trailing zero decimals stripped.

Parameters:
  • floats - List, sequence, tuple, etc. (scalars).
  • prec - Optional precision, number of decimal digits (0..9). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
  • sep - Optional, separator to join (string).
  • fmt - Optional, float format (string).
  • ints - Optionally, remove decimal dot (bool).
Returns:
The floats as 'f, f, ... f' (string).

fStrzs(fstr)

 

Strip trailing zero decimals from a float string.

Parameters:
  • fstr - Float (string)
Returns:
Float (string).

false2f(value, name='value', false=True)

 

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

Parameters:
  • value - Value to convert (scalar).
  • name - Name of the value (string).
  • false - Value must include false origin (bool).
Returns:
The value (float).
Raises:
  • ValueError - Invalid or negative value.

favg(v1, v2, f=0.5)

 

Return the weighted average of two values.

Parameters:
  • v1 - One value (scalar).
  • v2 - Other value (scalar).
  • f - Fraction (scalar).
Returns:
v1 + f * (v2 - v1) (float).

fdot(a, *b)

 

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

Parameters:
  • a - List, sequence, tuple, etc. (scalars).
  • b - List, sequence, tuple, etc. (scalars).
Returns:
Dot product (float).
Raises:
  • ValueError - Unequal len(a) and len(b).

fdot3(a, b, c, start=0)

 

Return the precision dot product sum(a[i] * b[i] * c[i] for i in range(len(a))) + start.

Parameters:
  • a - List, sequence, tuple, etc. (scalars).
  • b - List, sequence, tuple, etc. (scalars).
  • c - List, sequence, tuple, etc. (scalars).
  • start - Optional bias (scalar).
Returns:
Dot product (float).
Raises:
  • ValueError - Unequal len(a), len(b) and/or len(c).

fsum(iterable)

 

Return an accurate floating point sum of values in the iterable. Assumes IEEE-754 floating point arithmetic.

ft2m(feet)

 

Convert feet to meter (m).

Parameters:
  • feet - Value in feet (scalar).
Returns:
Value in m (float).

halfs(str2)

 

Split a string in 2 halfs.

Parameters:
  • str2 - String to split (string).
Returns:
2-Tuple (1st, 2nd) halfs (strings).
Raises:
  • ValueError - Zero or odd len(str2).

hsin(rad)

 

Compute the Haversine value of an angle.

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

hsin3(a2, a1, b21)

 

Compute the angular distance using the Haversine formula.

Parameters:
  • a2 - Latitude2 (radians).
  • a1 - Latitude1 (radians).
  • b21 - Longitude delta (radians).
Returns:
3-Tuple (angle, cos(a2), cos(a1))

hypot1(x)

 

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

Parameters:
  • x - Argument (scalar).
Returns:
Norm (float).

hypot3(x, y, z)

 

Compute the norm sqrt(x**2 + y**2 + z**2).

Parameters:
  • x - X argument (scalar).
  • y - Y argument (scalar).
  • z - Z argument (scalar).
Returns:
Norm (float).

isint(obj, both=False)

 

Check for integer types and value.

Parameters:
  • obj - The object (any type).
  • both - Check both type and value (bool).
Returns:
True if obj is integer (bool).

isscalar(obj)

 

Check for scalar types.

Parameters:
  • obj - The object (any type).
Returns:
True if obj is scalar (bool).

latDMS(deg, form='dms', prec=2, sep='')

 

Convert latitude to a string suffixed with N or S.

Parameters:
  • deg - Latitude to be formatted (degrees).
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, DD, DDMM, DDMMSS or radians (string).
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
  • sep - Optional, separator (string).
Returns:
Degrees per the specified form (string).

JS name: toLat.

len2(xtor)

 

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

Parameters:
  • xtor - Generator, iterator, list, sequence, tuple, etc.
Returns:
2-Tuple (number, list) of items (int, list).

lonDMS(deg, form='dms', prec=2, sep='')

 

Convert longitude to a string suffixed with E or W.

Parameters:
  • deg - Longitude to be formatted (degrees).
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, DDD, DDDMM, DDDMMSS or radians (string).
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
  • sep - Optional, separator (string).
Returns:
Degrees per the specified form (string).

JS name: toLon.

m2NM(meter)

 

Convert meter to nautical miles (NM).

Parameters:
  • meter - Value in meter (scalar).
Returns:
Value in NM (float).

m2SM(meter)

 

Convert meter to statute miles (SM).

Parameters:
  • meter - Value in meter (scalar).
Returns:
Value in SM (float).

m2ft(meter)

 

Convert meter to feet (ft).

Parameters:
  • meter - Value in meter (scalar).
Returns:
Value in ft (float).

m2km(meter)

 

Convert meter to kilo meter (km).

Parameters:
  • meter - Value in meter (scalar).
Returns:
Value in km (float).

map1(func, *args)

 

Apply each argument to a single-argument function and returns a tuple of results.

Parameters:
  • func - Function to apply (callable).
  • args - Arguments to apply (any).
Returns:
Function results (tuple).

map2(func, *args)

 

Apply arguments to a function and returns a tuple of results.

Unlike Python 2 built-in map, Python 3+ map returns a map object, an iterator-like object which generates the results only once. Converting the map object to a tuple maintains Python 2 behavior.

Parameters:
  • func - Function to apply (callable).
  • args - Arguments to apply (list, tuple, ...).
Returns:
Function results (tuple).

normDMS(strDMS, norm='')

 

Normalize all degree ˚, minute ' and second " symbols in a string to the default symbols °, ′ and ″.

Parameters:
  • strDMS - DMS (string).
  • norm - Replacement, default symbol otherwise (string).
Returns:
Normalized DMS (string).

parse3llh(strll, height=0, sep=',')

 

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

See function parseDMS for more details on the forms and symbols accepted.

Parameters:
  • strll - Lat, lon[, height] (string).
  • height - Default for missing height (meter).
  • sep - Optional, separator (string).
Returns:
3-Tuple (lat, lon, height) as (scalars).
Raises:
  • ValueError - Invalid strll.

Example:

>>> t = parse3llh('000°00′05.31″W, 51° 28′ 40.12″ N')  # (51.4778°N, 000.0015°W, 0)

parseDMS(strDMS, suffix='NSEW', sep='')

 

Parse a string representing deg°min′sec″ to degrees.

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

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

Parameters:
  • strDMS - Degrees in any of several forms (string).
  • suffix - Optional, valid compass directions (NSEW).
  • sep - Optional separator between deg°, min′ and sec″ ('').
Returns:
Degrees (float).
Raises:
  • ValueError - Invalid strDMS.

parseMGRS(strMGRS, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)

 

Parse a string representing a MGRS grid reference, consisting of zoneBand, grid, easting and northing.

Parameters:
  • strMGRS - MGRS grid reference (string).
  • datum - The datum to use (Datum).
Returns:
The MGRS grid reference (Mgrs).
Raises:
  • ValueError - Invalid strMGRS.

Example:

>>> m = parseMGRS('31U DQ 48251 11932')
>>> str(m)  # 31U DQ 48251 11932
>>> m = parseMGRS('31UDQ4825111932')
>>> repr(m)  # [Z:31U, G:DQ, E:48251, N:11932]

parseOSGR(strOSGR)

 

Parse an OSGR coordinate string to an Osgr instance.

Accepts standard OS Grid References like 'SU 387 148', with or without whitespace separators, from 2- up to 10-digit references (1 m × 1 m square), or fully numeric, comma-separated references in metres, for example '438700,114800'.

Parameters:
  • strOSGR - An OSGR coordinate (string).
Returns:
The OSGR coordinate (Osgr).
Raises:
  • ValueError - Invalid strOSGR.

Example:

>>> g = parseOSGR('TG 51409 13177')
>>> str(g)  # TG 51409 13177
>>> g = parseOSGR('TG5140913177')
>>> str(g)  # TG 51409 13177
>>> g = parseOSGR('TG51409 13177')
>>> str(g)  # TG 51409 13177
>>> g = parseOSGR('651409,313177')
>>> str(g)  # TG 51409 13177
>>> g.toStr(prec=0)  # 651409,313177

parseUTM(strUTM, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran...)

 

Parse a string representing a UTM coordinate, consisting of zone, hemisphere, easting and northing.

Parameters:
  • strUTM - A UTM coordinate (string).
  • datum - Datum to use (Datum).
Returns:
The UTM coordinate (Utm).
Raises:
  • ValueError - Invalid strUTM.

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

precision(form, prec=None)

 

Set the default precison for a given F_ form.

Parameters:
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD (string).
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
Returns:
Previous precision (int).
Raises:
  • ValueError - Invalid precision.

radiansPI(deg)

 

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

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

radiansPI2(deg)

 

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

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

radiansPI_2(deg)

 

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

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

simplify1(points, distance, radius=6371008.77141, adjust=True)

 

Basic simplification of a path of LatLon points.

Eliminates any points closer together than the given distance tolerance.

Parameters:
  • points - Path points (LatLons).
  • distance - Tolerance (meter, same units as radius).
  • radius - Earth radius (meter).
  • adjust - Adjust longitudes (bool).
Returns:
Simplified points (list of LatLons).
Raises:
  • ValueError - Radius or distance tolerance too small.

simplify2(points, pipe, radius=6371008.77141, adjust=True, shortest=False)

 

Pipe simplification of a path of LatLon points.

Eliminates any points too close together or within the given pipe tolerance along an edge.

Parameters:
  • points - Path points (LatLons).
  • pipe - Half pipe width (meter, same units as radius).
  • radius - Earth radius (meter).
  • adjust - Adjust longitudes (bool).
  • shortest - Shortest or perpendicular distance (bool).
Returns:
Simplified points (list of LatLons).
Raises:
  • ValueError - Radius or pipe tolerance too small.

simplifyRDP(points, distance, radius=6371008.77141, adjust=True, shortest=False)

 

Ramer-Douglas-Peucker (RDP) simplification of a path of LatLon points.

Eliminates any points too close together or closer to an edge than the given distance tolerance.

This RDP method exhaustively searches for the point with the largest distance, resulting in worst-case complexity O(n**2) where n is the number of points.

Parameters:
  • points - Path points (LatLons).
  • distance - Tolerance (meter, same units as radius).
  • radius - Earth radius (meter).
  • adjust - Adjust longitudes (bool).
  • shortest - Shortest or perpendicular distance (bool).
Returns:
Simplified points (list of LatLons).
Raises:
  • ValueError - Radius or distance tolerance too small.

simplifyRDPm(points, distance, radius=6371008.77141, adjust=True, shortest=False)

 

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

Parameters:
  • points - Path points (LatLons).
  • distance - Tolerance (meter, same units as radius).
  • radius - Earth radius (meter).
  • adjust - Adjust longitudes (bool).
  • shortest - Shortest or perpendicular distance (bool).
Returns:
Simplified points (list of LatLons).
Raises:
  • ValueError - Radius or distance tolerance too small.

simplifyVW(points, area, radius=6371008.77141, adjust=True, attr=None)

 

Visvalingam-Whyatt (VW) simplification of a path of LatLon points.

Eliminates any points too close together or with a triangular area not exceeding the given area tolerance (squared).

This VW method exhaustively searches for the single point with the smallest triangular area, resulting in worst-case complexity O(n**2) where n is the number of points.

Parameters:
  • points - Path points (LatLons).
  • area - Tolerance (meter, same units as radius).
  • radius - Earth radius (meter).
  • adjust - Adjust longitudes (bool).
  • attr - Points attribute save area value (string).
Returns:
Simplified points (list of LatLons).
Raises:
  • ValueError - Radius or area tolerance too small.

simplifyVWm(points, area, radius=6371008.77141, adjust=True, attr=None)

 

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

Parameters:
  • points - Path points (LatLons).
  • area - Tolerance (meter, same units as radius).
  • radius - Earth radius (meter).
  • adjust - Adjust longitudes (bool).
  • attr - Attribute to save the area value (string).
Returns:
Simplified points (list of LatLons).
Raises:
  • ValueError - Radius or area tolerance too small.

tanPI_2_2(rad)

 

Compute tan of half angle, rotated.

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

toDMS(deg, form='dms', prec=2, sep='', ddd=2, neg='-', pos='')

 

Convert signed degrees to string, without suffix.

Parameters:
  • deg - Degrees to be formatted (scalar).
  • form - F_D, F_DM, F_DMS, F_DEG, F_MIN, F_SEC or F_RAD for deg°, deg°min′, deg°min′sec″, [D]DD, [D]DDMM, [D]DDMMSS or radians (string).
  • prec - Optional, number of decimal digits (0..9 or None for default). Trailing zero decimals are stripped for prec values of 1 and above, but kept for negative prec values.
  • sep - Optional, separator (string).
  • ddd - Optional, number of digits for deg° (2 or 3).
  • neg - Optional, sign for negative degrees ('-').
  • pos - Optional, sign for positive degrees ('').
Returns:
Degrees per the specified form (string).

toLcc(latlon, conic=Conic(name='WRF_Lb', lat0=40.0, lon0=-97.0, par1=33.0, par2=45..., height=None, Lcc=<class 'pygeodesy.lcc.Lcc'>)

 

Convert an (ellipsoidal) geodetic point to a Lambert location.

Parameters:
  • latlon - Ellipsoidal point (LatLon).
  • conic - Lambert projection to use (Conic).
  • height - Optional height for the point, overriding the default height (meter).
  • Lcc - Lcc class for the Lambert location (Lcc).
Returns:
The Lambert location (Lcc).
Raises:
  • TypeError - If latlon is not ellipsoidal.

toMgrs(utm, Mgrs=<class 'pygeodesy.mgrs.Mgrs'>)

 

Convert a UTM coordinate to an MGRS grid reference.

Parameters:
  • utm - A UTM coordinate (Utm).
  • Mgrs - Mgrs class for the MGRS grid reference (Mgrs).
Returns:
The MGRS grid reference (Mgrs).
Raises:
  • TypeError - If utm is not Utm.
  • ValueError - Invalid utm.

Example:

>>> u = Utm(31, 'N', 448251, 5411932)
>>> m = u.toMgrs()  # 31U DQ 48251 11932

toOsgr(latlon, lon=None, datum=Datum(name='WGS84', ellipsoid=Ellipsoids.WGS84, transform=Tran..., Osgr=<class 'pygeodesy.osgr.Osgr'>)

 

Convert a lat-/longitude point to an OSGR coordinate.

Parameters:
  • latlon - Latitude (degrees) or an (ellipsoidal) geodetic LatLon point.
  • lon - Longitude in degrees (scalar or None).
  • datum - Datum to convert (Datum).
  • Osgr - Osgr class for the OSGR coordinate (Osgr).
Returns:
The OSGR coordinate (Osgr).
Raises:
  • TypeError - If latlon is not ellipsoidal.
  • ValueError - If latlon or lon is invalid.

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)

toUtm(latlon, lon=None, datum=None, Utm=<class 'pygeodesy.utm.Utm'>)

 

Convert a lat-/longitude point to a UTM coordinate.

Parameters:
  • latlon - Latitude (degrees) or an (ellipsoidal) geodetic LatLon point.
  • lon - Longitude (degrees or None).
  • datum - Datum for this UTM coordinate, overriding latlon's datum (Datum).
  • Utm - Utm class for the UTM coordinate (Utm).
Returns:
The UTM coordinate (Utm).
Raises:
  • TypeError - If latlon is not ellipsoidal.
  • ValueError - If lon value is missing, if latlon is not scalar or latlon is outside the valid UTM bands.

Note: Implements Karney’s method, using 6-th order Krüger series, giving results accurate to 5 nm 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

wrap180(deg)

 

Wrap degrees to -180..+180.

Parameters:
  • deg - Angle (degrees).
Returns:
Degrees, wrapped (degrees180).

wrap360(deg)

 

Wrap degrees to 0..+360.

Parameters:
  • deg - Angle (degrees).
Returns:
Degrees, wrapped (degrees360).

wrap90(deg)

 

Wrap degrees to -270..+90.

Parameters:
  • deg - Angle (degrees).
Returns:
Degrees, wrapped (degrees90).

wrapPI(rad)

 

Wrap radians to -PI..+PI.

Parameters:
  • rad - Angle (radians).
Returns:
Radians, wrapped (radiansPI).

wrapPI2(rad)

 

Wrap radians to 0..+2PI.

Parameters:
  • rad - Angle (radians).
Returns:
Radians, wrapped (radiansPI2).

wrapPI_2(rad)

 

Wrap radians to -3PI/2..+PI/2.

Parameters:
  • rad - Angle (radians).
Returns:
Radians, wrapped (radiansPI_2).

Variables Details

Conics

Registered conics (enum).
Value:
Conics.Be08Lb: Conic(name='Be08Lb', lat0=50.797815, lon0=4.35921583, p\
ar1=49.833333, par2=51.166667, E0=649328.0, N0=665262.0, k0=1, SP=2, d\
atum=(name='GRS80', ellipsoid=Ellipsoids.GRS80, transform=Transforms.W\
GS84)
Conics.Be72Lb: Conic(name='Be72Lb', lat0=90.0, lon0=4.3674867, par1=49\
.8333339, par2=51.1666672, E0=150000.013, N0=5400088.438, k0=1, SP=2, \
datum=(name='NAD83', ellipsoid=Ellipsoids.GRS80, transform=Transforms.\
NAD83)
...

Datums

Registered datums (enum).
Value:
Datums.BD72: Datum(name='BD72', ellipsoid=Ellipsoids.Intl1924, transfo\
rm=Transforms.BD72)
Datums.DHDN: Datum(name='DHDN', ellipsoid=Ellipsoids.Bessel1841, trans\
form=Transforms.DHDN)
Datums.ED50: Datum(name='ED50', ellipsoid=Ellipsoids.Intl1924, transfo\
rm=Transforms.ED50)
Datums.GRS80: Datum(name='GRS80', ellipsoid=Ellipsoids.GRS80, transfor\
m=Transforms.WGS84)
...

Ellipsoids

Registered ellipsoids (enum).
Value:
Ellipsoids.Airy1830: Ellipsoid(name='Airy1830', a=6377563.396, b=63562\
56.909, f_=299.3249646, f=0.00334085, e2=0.00667054, e22=0.00671533, R\
=6370461.23366667, Rm=6366901.23988196, R2=6370459.65458944, R3=637045\
3.30986645, Rr=6366914.60880589)
Ellipsoids.AiryModified: Ellipsoid(name='AiryModified', a=6377340.189,\
 b=6356034.448, f_=299.3249646, f=0.00334085, e2=0.00667054, e22=0.006\
71533, R=6370238.27533333, Rm=6366678.40619415, R2=6370236.69636116, R\
3=6370230.35181066, Rr=6366691.7746498)
...

Transforms

Registered transforms (enum).
Value:
Transforms.BD72: Transform(name='BD72', tx=106.8686, ty=-52.2978, tz=1\
03.7239, rx=-0.0, ry=-0.0, rz=-0.0, s=1.2727, s1=1.0, sx=-0.3366, sy=-\
0.457, sz=-1.8422)
Transforms.Bessel1841: Transform(name='Bessel1841', tx=-582.0, ty=-105\
.0, tz=-414.0, rx=-0.0, ry=-0.0, rz=0.0, s=-8.3, s1=1.0, sx=-1.04, sy=\
-0.35, sz=3.08)
Transforms.Clarke1866: Transform(name='Clarke1866', tx=8.0, ty=-160.0,\
 tz=-176.0, rx=0, ry=0, rz=0, s=0, s1=1, sx=0, sy=0, sz=0)
...