Skip to main content

pure Python (no prereqs) coordinate conversions, following convention of several popular Matlab routines.

Project description

Python 3-D coordinate conversions

image image codecov Actions Status Actions Status image PyPi Download stats

Pure Python (no prerequistes beyond Python itself) 3-D geographic coordinate conversions and geodesy. Function syntax is roughly similar to Matlab Mapping Toolbox. PyMap3D is intended for non-interactive use on massively parallel (HPC) and embedded systems.

API docs

Thanks to our contributors.

Similar toolboxes in other code languages

Prerequisites

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/geospace-code/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, N-D 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 N-D 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 N-D 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
geodetic2spherical spherical2geodetic

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', ...) and azimuth('rh', ...)
  • loxodrome_direct
  • geodetic latitude transforms to/from: parametric, authalic, isometric, and more in pymap3d.latitude

Abbreviations:

Ellipsoid

Numerous functions in pymap3d use an ellipsoid model. The default is WGS84 Ellipsoid. Numerous other ellipsoids are available in pymap3d.Ellipsoid.

Print available ellipsoid models:

import pymap3d as pm

print(pm.Ellipsoid.models)

Specify GRS80 ellipsoid:

import pymap3d as pm

ell = pm.Ellipsoid.from_name('grs80')

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.

Compare to Matlab Mapping and Aerospace Toolbox

The tests in files tests/test_matlab*.py selected by

pytest -k matlab
# run from pymap3d/ top-level directory

use Matlab Engine for Python to compare Python PyMap3D output with Matlab output using Matlab functions.

python -m pip install matlabengine

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 first-class citizen. For now, you can workaround by passing in the .value of the variable.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pymap3d-3.2.0.tar.gz (50.8 kB view details)

Uploaded Source

Built Distribution

pymap3d-3.2.0-py3-none-any.whl (64.8 kB view details)

Uploaded Python 3

File details

Details for the file pymap3d-3.2.0.tar.gz.

File metadata

  • Download URL: pymap3d-3.2.0.tar.gz
  • Upload date:
  • Size: 50.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pymap3d-3.2.0.tar.gz
Algorithm Hash digest
SHA256 355e87c559ac681cba34a7fef5bcec3ad791f95336a0fdaf15e0335f48a309a2
MD5 f35a83d39f144f2ad7cfc811919cb89c
BLAKE2b-256 a55c6de7682c8d0d618acfd939425803ce74f02487eea7124f807c79997facc4

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymap3d-3.2.0.tar.gz:

Publisher: publish-python-package.yml on geospace-code/pymap3d

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file pymap3d-3.2.0-py3-none-any.whl.

File metadata

  • Download URL: pymap3d-3.2.0-py3-none-any.whl
  • Upload date:
  • Size: 64.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for pymap3d-3.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 fccd44f2f6021a95adec19771c603b8dac104eab120d863c463d76b9bc298669
MD5 1c06e7d83d84c8907ebf6c6cfc0c88c2
BLAKE2b-256 4ece3714d0d67a83577017b1e7c40193bc1cf768a1de39c4adff750b7d3c1539

See more details on using hashes here.

Provenance

The following attestation bundles were made for pymap3d-3.2.0-py3-none-any.whl:

Publisher: publish-python-package.yml on geospace-code/pymap3d

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page