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

# Python 3-D coordinate conversions

Pure Python (no prerequistes beyond Python itself) 3-D geographic coordinate conversions. API similar to popular \$1000 Matlab Mapping Toolbox routines for:

PyMap3D is intended for non-interactive use on massively parallel (HPC) and embedded systems. Includes some relevant Vallado algorithms.

API docs

## Prerequisites

Python ≥ 2.6 (full features require Python ≥ 3.5)

or

PyPy3

References to Numpy and AstroPy are optional, algorithms from Vallado and Meeus are used if AstroPy is not present. PyMap3D is regularly tested with Python ≥ 3.5. Limited Python 2.6, 2.7 and 3.4 support is available for systems using MicroPython or other cases where a current Python version isn't available.

## Install

```pip install pymap3d
```

or for the latest development code:

```git clone https://github.com/scivision/pymap3d
cd pymap3d
pip install -e .
```

One can verify Python functionality after installation by:

```pip install -e .[tests]
pytest -rsv
```

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

### 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
enu2aer  enu2ecef   enu2geodetic
geodetic2aer  geodetic2ecef  geodetic2enu  geodetic2ned
ned2aer  ned2ecef   ned2geodetic
vreckon vdist
lookAtSpheroid
track2
``````

`loxodrome_inverse`: rhumb line distance and azimuth between ellipsoid points (lat,lon) akin to Matlab `distance('rh', ...)` and `azimuth('rh', ...)`

Abbreviations:

### 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 + Numpy.
• 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 for 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.