.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.213676.svg
   :target: https://doi.org/10.5281/zenodo.213676

.. image:: http://img.shields.io/badge/powered%20by-AstroPy-orange.svg?style=flat
    :target: http://www.astropy.org/

.. image:: https://travis-ci.org/scivision/pymap3d.svg?branch=master
    :target: https://travis-ci.org/scivision/pymap3d

.. image:: https://coveralls.io/repos/github/scivision/pymap3d/badge.svg?branch=master
    :target: https://coveralls.io/github/scivision/pymap3d?branch=master

.. image:: https://api.codeclimate.com/v1/badges/b6e4b90175e6dbf1b375/maintainability
   :target: https://codeclimate.com/github/scivision/pymap3d/maintainability
   :alt: Maintainability

==================================
Python 3-D coordinate conversions
==================================

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

:API docs: https://www.scivision.co/pymap3d

For those not having:

* AstroPy: lower accuracy fallback functions are included for some functions.
* Numpy: without numpy, scalar inputs are handled with pure Python builtins.

Why not `PyProj <https://github.com/jswhit/pyproj>`_? 
PyMap3D does not require anything beyond pure Python.
PyProj is very powerful and comprehensive, but requires a learning curve to use, 
particularly for Python users accustomed to Matlab.

.. contents::


:prereqs: any of Python 2.6, 2.7, 3.3, 3.4, 3.5, 3.6, 3.7, ...
:OPTIONAL prereqs: Numpy, AstroPy  (for full functionality)

Install
=======
::
    
    python -m pip install -e .


Usage
=====
a few quick examples

.. code:: python

   import pymap3d as pm

   lat,lon,alt = pm.eci2geodetic(eci, t)
   
   az,el,range = pm.geodetic2aer(lat, lon, alt, 42, -82, 0)
   

Functions
---------
Popular mapping toolbox functions ported to Python include::

  aer2ecef  aer2enu  aer2geodetic  aer2ned
  ecef2aer  ecef2enu  ecef2enuv  ecef2geodetic  ecef2ned  ecef2nedv  ecef2eci
  eci2ecef
  enu2aer  enu2ecef  enu2ecefv  enu2geodetic
  geodetic2aer  geodetic2ecef  geodetic2enu  geodetic2ned
  ned2aer  ned2ecef  ned2ecefv  ned2geodetic
  vreckon vdist
  azel2radec radec2azel


Caveats
-------

* Atmospheric effects neglected in all functions not invoking AstroPy. 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 <https://www.mathworks.com/products/mapping.html>`_ 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 <https://www.scivision.co/pymap3d>`_ generated by `m2html <https://www.artefact.tk/software/matlab/m2html/>`_.

