pymap3d 1.6.3

pure Python coordinate conversions, following convention of several popular Matlab routines.

Python / Matlab / Fortran 3-D coordinate conversions

3-D geographic coordinate conversions, with API similar to popular $1000 Matlab Mapping Toolbox routines for:

• Python

• Matlab, GNU Octave

• modern Fortran (“elemental” functions and subroutines for massively parallel computation)

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

API docs:

https://www.scivision.co/pymap3d

For those not having:

• AstroPy: lower accuracy fallback functions are automatically used.

• Numpy: without Numpy, scalar inputs are handled with pure Python builtins.

Why not PyProj?

• PyMap3D does not require anything beyond pure Python.

• PyMap3D API is virtually identical 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 import for airborne vehicles and remote sensing.

Contents

• Python / Matlab / Fortran 3-D coordinate conversions

  • Prerequisites

  • Install

  • Usage

    • Python

    • Matlab / GNU Octave

    • Fortran

    • Functions

    • Caveats

  • Matlab / Octave

Prerequisites

• Python PyMap3D: any of Python 2.6, 2.7, 3.4, 3.5, 3.6, but only Python >= 3.5 is tested regularly. * Numpy (optional): if not present, function from math are automatically used, and if Numpy is present, it is automatically used. * AstroPy (optional): If not present, ECI coordinate conversions are not available.

• Matlab / GNU Octave: under matlab/

• Fortran MapTran: under fortran/: any Fortran compiler (tested with gfortran)

Install

The three separate packages are independent, they don’t rely on each other.

• Python PyMap3D:

  pip install pymap3d

  or for the latest development code:

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

  One can verify Python functionality after installation by:

  pip install -e .[tests]
  pytest -v

• Fortran MapTran:

  cd bin
  cmake ..
  make

  verify Fortran (as well as Python and Matlab/Octave) functionality after compiling by:

  make test

• Matlab/Octave: from within Matlab/Octave:

  addpath(pymap3d/matlab)

  One can verify Matlab code functionality by running:

  tests/Test.m

Usage

Where consistent with the definition of the functions, all arguments may be arbitrarily shaped (scalar, N-D array).

Python

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

Matlab / GNU Octave

The syntax is reasonably compatible with the $1000 Matlab Mapping Toolbox. Under the matlab/ directory:

x,y,z = geodetic2ecef([],lat,lon,alt)

az,el,range = geodetic2aer(lat, lon, alt, observer_lat, observer_lon, observer_alt)

Fortran

The Fortran API under fortran/ directory is simple like PyMap3D. Modern Fortran “elemental” procedures throughout enable seamless support of scalar or array coordinate inputs. Default precision is real64, set at the top of fortran/maptran.f90.

use maptran

call geodetic2ecef(lat,lon,alt, x,y,z)
call geodetic2aer(lat,lon,alt, observer_lat, observer_lon, observer_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
enu2aer  enu2ecef   enu2geodetic
geodetic2aer  geodetic2ecef  geodetic2enu  geodetic2ned
ned2aer  ned2ecef   ned2geodetic
azel2radec radec2azel
vreckon vdist

Abbreviations:

• AER: Azimuth, Elevation, Range

• ECEF: Earth-centered, Earth-fixed

• ECI: Earth-centered Inertial

• ENU: East North Up

• NED: North East Down

• radec: right ascension, declination

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.

Matlab / Octave

The matlab/ directory contains a subset of the Python conversion functions, usable from Matlab or GNU Octave. Mathworks currently charges $1000 for the Matlab Mapping Toolbox that provides these functions.

• The full set of Python conversions can be accessed from Matlab >= R2014b by commands like:

  lla = py.pymap3d.geodetic2ecef(x,y,z)

• Matlab documentation generated by m2html.