Python 3D coordinate conversions
Pure Python (no prerequistes beyond Python itself) 3D geographic coordinate conversions and geodesy. API similar to popular $1000 Matlab Mapping Toolbox routines for Python PyMap3D is intended for noninteractive use on massively parallel (HPC) and embedded systems.
Thanks to our contributors.
Similar toolboxes in other code languages
Prerequisites
Pymap3d is compatible with Python ≥ 3.7 including PyPy. Numpy and AstroPy are optional; algorithms from Vallado and Meeus are used if AstroPy is not present.
Install
python3 m pip install pymap3d
or for the latest development code:
git clone https://github.com/geospacecode/pymap3d
pip install e pymap3d
One can verify Python functionality after installation by:
pytest pymap3d
Usage
Where consistent with the definition of the functions, all arguments may be arbitrarily shaped (scalar, ND array).
import pymap3d as pm
x,y,z = pm.geodetic2ecef(lat,lon,alt)
az,el,range = pm.geodetic2aer(lat, lon, alt, observer_lat, observer_lon, 0)
Python argument unpacking can be used for compact function arguments with scalars or arbitrarily shaped ND arrays:
aer = (az,el,slantrange)
obslla = (obs_lat,obs_lon,obs_alt)
lla = pm.aer2geodetic(*aer,*obslla)
where tuple lla
is comprised of scalar or ND arrays (lat,lon,alt)
.
Example scripts are in the examples directory.
Native Python float is typically 64 bit. Numpy can select real precision bits: 32, 64, 128, etc.
Functions
Popular mapping toolbox functions ported to Python include the following, where the source coordinate system (before the "2") is converted to the desired coordinate system:
aer2ecef aer2enu aer2geodetic aer2ned
ecef2aer ecef2enu ecef2enuv ecef2geodetic ecef2ned ecef2nedv
ecef2eci eci2ecef eci2aer aer2eci geodetic2eci eci2geodetic
enu2aer enu2ecef enu2geodetic
geodetic2aer geodetic2ecef geodetic2enu geodetic2ned
ned2aer ned2ecef ned2geodetic
azel2radec radec2azel
lookAtSpheroid
track2 departure meanm
rcurve rsphere
geod2geoc geoc2geod
Vincenty functions "vincenty.vreckon" and "vincenty.vdist" are accessed like:
import pymap3d.vincenty as pmv
lat2, lon2 = pmv.vreckon(lat1, lon1, ground_range_m, azimuth_deg)
dist_m, azimuth_deg = pmv.vdist(lat1, lon1, lat2, lon2)
Additional functions:
 loxodrome_inverse: rhumb line distance and azimuth between ellipsoid points (lat,lon) akin to Matlab
distance('rh', ...)
andazimuth('rh', ...)
 loxodrome_direct
 geodetic latitude transforms to/from: parametric, authalic, isometric, and more in pymap3d.latitude
Abbreviations:
 AER: Azimuth, Elevation, Range
 ECEF: Earthcentered, Earthfixed

ECI: Earthcentered Inertial using IERS via
astropy
 ENU: East North Up
 NED: North East Down
 radec: right ascension, declination
command line
Command line convenience functions provided include:
python m pymap3d.vdist
python m pymap3d.vreckon
array vs scalar
Use of pymap3d on embedded systems or other streaming data applications often deal with scalar position data. These data are handled efficiently with the Python math stdlib module. Vector data can be handled via list comprehension.
Those needing multidimensional data with SIMD and other Numpy and/or PyPy accelerated performance can do so automatically by installing Numpy. pymap3d seamlessly falls back to Python's math module if Numpy isn't present. To keep the code clean, only scalar data can be used without Numpy. As noted above, use list comprehension if you need vector data without Numpy.
Caveats
 Atmospheric effects neglected in all functions not invoking AstroPy. Would need to update code to add these input parameters (just start a GitHub Issue to request).
 Planetary perturbations and nutation etc. not fully considered.
Notes
As compared to PyProj:
 PyMap3D does not require anything beyond pure Python for most transforms
 Astronomical conversions are done using (optional) AstroPy for established accuracy
 PyMap3D API is similar to Matlab Mapping Toolbox, while PyProj's interface is quite distinct
 PyMap3D intrinsically handles local coordinate systems such as ENU, while PyProj ENU requires some additional effort.
 PyProj is oriented towards points on the planet surface, while PyMap3D handles points on or above the planet surface equally well, particularly important for airborne vehicles and remote sensing.
AstroPy.Units.Quantity
At this time,
AstroPy.Units.Quantity
is not supported.
Let us know if this is of interest.
Impacts on performance would have to be considered before making Quantity a firstclass citizen.
For now, you can workaround by passing in the .value
of the variable.