Welcome to PyMap3D’s documentation!

Matlab docs

Input/output: default units are METERS and DEGREES. boolean deg=True means degrees

For most functions you can input Numpy arrays of any shape, except as noted in the functions

see tests/Test.py for example uses.

pymap3d.aer2ecef(az, el, srange, lat0, lon0, alt0, ell=None, deg=True)[source]

convert target azimuth, elevation, range (meters) from observer at lat0,lon0,alt0 to ECEF coordinates.

Input: az,el; lat0,lon0 [degrees] srange, alt0 [meters]

output: ECEF x,y,z [meters]

if you specify NaN for srange, return value z will be NaN

pymap3d.aer2eci(az, el, srange, lat0, lon0, h0, t, ell=None, deg=True)[source]

convert target azimuth, elevation, range to ECI

pymap3d.aer2enu(az, el, srange, deg=True)[source]

input: azimuth, elevation [deg] slant range [m] output: East, North, Up [m]

pymap3d.aer2geodetic(az, el, srange, lat0, lon0, alt0, deg=True)[source]

Input: az,el; lat0,lon0 [degrees] srange, alt0 [meters]

output: WGS84 lat,lon [degrees] altitude above spheroid [meters]

pymap3d.aer2ned(az, elev, slantRange, deg=True)[source]

convert target azimuth, elevation, range to NED coordinates (meters)

pymap3d.azel2radec(az_deg, el_deg, lat_deg, lon_deg, t)[source]

convert astronomical target horizontal azimuth, elevation to ecliptic right ascension, declination (degrees)

pymap3d.ecef2aer(x, y, z, lat0, lon0, h0, ell=None, deg=True)[source]

Convert ECEF of target to azimuth, elevation, range (meters) from observer at lat0,lon0,h0 (meters) output: azimuth (deg), elevation (deg), slant range (m) for Obs->Point

pymap3d.ecef2eci(ecef, t)[source]

input t is either a datetime or float in radians

pymap3d.ecef2enu(x, y, z, lat0, lon0, h0, ell=None, deg=True)[source]

convert target ECEF (meters) to ENU (meters) from observer at lat0,lon0,h0 (degrees,degrees,meters)

pymap3d.ecef2enuv(u, v, w, lat0, lon0, deg=True)[source]

for VECTOR i.e. between two points

pymap3d.ecef2geodetic(x, y, z, ell=None, deg=True)[source]

convert ECEF (meters) to geodetic coordintes

Algorithm is based on http://www.astro.uni.torun.pl/~kb/Papers/geod/Geod-BG.htm This algorithm provides a converging solution to the latitude equation in terms of the parametric or reduced latitude form (v) This algorithm provides a uniform solution over all latitudes as it does not involve division by cos(phi) or sin(phi)

pymap3d.ecef2ned(x, y, z, lat0, lon0, h0, ell=None, deg=True)[source]

convert target ECEF (meters) to NED (meters) from observer at lat0,lon0,h0

pymap3d.ecef2nedv(u, v, w, lat0, lon0, deg=True)[source]

for VECTOR between two points

pymap3d.eci2aer(eci, lat0, lon0, h0, t)[source]

Convert ECI of target to azimuth, elevation, range (meters) from observer at lat0,lon0,h0 (meters) output: azimuth (deg), elevation (deg), slant range (m) for Obs->Point

pymap3d.eci2ecef(eci, t)[source]

Convert ECI to ECEF coordinates

inputs: t is either a datetime or float in radians

output: ECEF x,y,z (meters)

pymap3d.eci2geodetic(eci, t)[source]

convert ECI to geodetic coordinates

inputs:

eci/ecef: a Nx3 vector of x,y,z triplets in the eci or ecef system [meters] t : length N vector of datetime OR greenwich sidereal time angle [radians].

Note: Conversion is idealized: doesn’t consider nutations, perterbations, etc. like the IAU-76/FK5 or IAU-2000/2006 model-based conversions from ECI to ECEF

pymap3d.enu2aer(e, n, u, deg=True)[source]

Convert ENU (meters) to azimuth, elevation, range (meters)

input: east, north, up [m]

output: azimuth (deg), elevation (deg), slant range (m) for Obs->Point

pymap3d.enu2ecef(e1, n1, u1, lat0, lon0, alt0, ell=None, deg=True)[source]

convert ENU to ECEF coordinates

inputs:
ENU e1, n1, u1 (meters) observer lat0, lon0, alt0 (degrees,degrees,meters)

output: ECEF x,y,z (meters)

pymap3d.enu2geodetic(e, n, u, lat0, lon0, h0, ell=None, deg=True)[source]

convert target ENU from observer at lat0,lon0,h0 to geodetic coordinates

pymap3d.geodetic2aer(lat, lon, h, lat0, lon0, h0, ell=None, deg=True)[source]

gives az,el,range from observer looking to target geodetic coordinates.

input: Point(s): lat, lon, h (altitude, meters)
Observer: lat0, lon0, h0 (altitude, meters)

output: azimuth (deg), elevation (deg), slant range (m) for Obs->Point

pymap3d.geodetic2ecef(lat, lon, alt, ell=None, deg=True)[source]

convert geodetic latitude, longitude, altiude (meters) to ECEF

output: ECEF x,y,z (meters)

pymap3d.geodetic2enu(lat, lon, h, lat0, lon0, h0, ell=None, deg=True)[source]

convert target geodetic coordinates to ENU (meters) from observer at lat0,lon0,h0 (degrees,degrees,meters)

pymap3d.geodetic2ned(lat, lon, h, lat0, lon0, h0, ell=None, deg=True)[source]

convert target geodetic coordinates to NED (meters) from observer at lat0,lon0,h0

pymap3d.ned2aer(n, e, d, deg=True)[source]

Convert target NED to azimuth, elevation, range (meters)

output: azimuth (deg), elevation (deg), slant range (m) for Obs->Point

pymap3d.ned2ecef(n, e, d, lat0, lon0, h0, ell=None, deg=True)[source]

convert NED to ECEF coordinates, from observer at lat0,lon0,h0 (meters)

output: NED (meters)

pymap3d.ned2geodetic(n, e, d, lat0, lon0, h0, ell=None, deg=True)[source]

convert target NED from observer at lat0,lon0,h0 to geodetic coordinates

pymap3d.radec2azel(ra_deg, dec_deg, lat_deg, lon_deg, t)[source]

convert astronomical target ecliptic right ascension, declination to horizontal azimuth, eelvation (degrees)

Ported by Michael Hirsch to Python.

pymap3d.vincenty.vdist(lat1, lon1, lat2, lon2)[source]

Using the WGS-84 Earth ellipsoid, compute the distance between two points within a few millimeters of accuracy, compute forward azimuth, and compute backward azimuth, all using a vectorized version of Vincenty’s algorithm:

s = vdist(lat1,lon1,lat2,lon2)
s,a12 = vdist(lat1,lon1,lat2,lon2)
s,a12,a21 = vdist(lat1,lon1,lat2,lon2)
s
distance in meters (inputs may be scalars, vectors, or matrices)
a12
azimuth in degrees from first point to second point (forward)
a21
azimuth in degrees from second point to first point (backward)

(Azimuths are in degrees clockwise from north.)

lat1
GEODETIC latitude of first point (degrees)
lon1
longitude of first point (degrees)
lat2, lon2
second point (degrees)

Original algorithm source: T. Vincenty, “Direct and Inverse Solutions of Geodesics on the Ellipsoid with Application of Nested Equations”, Survey Review, vol. 23, no. 176, April 1975, pp 88-93. Available at: http://www.ngs.noaa.gov/PUBS_LIB/inverse.pdf

Notes:
  1. lat1,lon1,lat2,lon2 can be any (identical) size/shape. Outputs will have the same size and shape.

  2. Error correcting code, convergence failure traps, antipodal corrections, polar error corrections, WGS84 ellipsoid parameters, testing, and comments: Michael Kleder, 2004.

  3. Azimuth implementation (including quadrant abiguity resolution) and code vectorization, Michael Kleder, Sep 2005.

  4. Vectorization is convergence sensitive; that is, quantities which have already converged to within tolerance are not recomputed during subsequent iterations (while other quantities are still converging).

  5. Vincenty describes his distance algorithm as precise to within 0.01 millimeters, subject to the ellipsoidal model.

  6. For distance calculations, essentially antipodal points are treated as exactly antipodal, potentially reducing accuracy slightly.

  7. Distance failures for points exactly at the poles are eliminated by moving the points by 0.6 millimeters.

  8. The Vincenty distance algorithm was transcribed verbatim by Peter Cederholm, August 12, 2003. It was modified and translated to English by Michael Kleder. Mr. Cederholm’s website is http://www.plan.aau.dk/~pce/

  9. Distances agree with the Mapping Toolbox, version 2.2 (R14SP3) with a max relative difference of about 5e-9, except when the two points are nearly antipodal, and except when one point is near the equator and the two longitudes are nearly 180 degrees apart. This function (vdist) is more accurate in such cases. For example, note this difference (as of this writing):

    vdist(0.2,305,15,125)
    

    > 18322827.0131551

    distance(0.2,305,15,125,[6378137 0.08181919])
    

    > 0

  10. Azimuths FROM the north pole (either forward starting at the north pole or backward when ending at the north pole) are set to 180 degrees by convention. Azimuths FROM the south pole are set to 0 degrees by convention.

  11. Azimuths agree with the Mapping Toolbox, version 2.2 (R14SP3) to within about a hundred-thousandth of a degree, except when traversing to or from a pole, where the convention for this function is described in (10), and except in the cases noted above in (9).

  12. No warranties; use at your own risk.

pymap3d.vincenty.vreckon(lat1, lon1, rng, azim, ellipsoid=None)[source]

Computes points at a specified azimuth and range in an ellipsoidal earth. Using the WGS-84 Earth ellipsoid, travel a given distance along a given azimuth starting at a given initial point, and return the endpoint within a few millimeters of accuracy, using Vincenty’s algorithm.

USAGE:

lat2,lon2 = vreckon(lat1, lon1, rng, azim)

Transmits ellipsoid definition (either as [a,b] or [a,f]) as fifth argument ELLIPSOID

VARIABLES

lat1
inital latitude (degrees)
lon1
initial longitude (degrees)
rng
distance (meters). Scalar or a vector. Latter case computes a series of circles (or arc circles, see azim) centered on X,Y (which are scalars)
azim
intial azimuth (degrees). “azim” is a scalar or vector
ellipsoid
two-element ellipsoid vector. Either [a b] or [a f] If omitted, defaults to WGS-84
lat2, lon2
second point (degrees)
a21
reverse azimuth (degrees), at final point facing back toward the intial point
Original algorithm:
 
  1. Vincenty, “Direct and Inverse Solutions of Geodesics on the Ellipsoid with Application of Nested Equations”, Survey Review, vol. 23, no. 176, April 1975, pp 88-93. http://www.ngs.noaa.gov/PUBS_LIB/inverse.pdf

Notes:

  1. The Vincenty reckoning algorithm was transcribed verbatim into JavaScript by Chris Veness. It was modified and translated to Matlab by Michael Kleder. Mr. Veness’s website is: http://www.movable-type.co.uk/scripts/latlong-vincenty-direct.html
  2. Error correcting code, polar error corrections, WGS84 ellipsoid parameters, testing, and comments by Michael Kleder.
  3. By convention, when starting at a pole, the longitude of the initial point (otherwise meaningless) determines the longitude line along which to traverse, and hence the longitude of the final point.
  4. The convention noted in (3) above creates a discrepancy with VDIST when the the intial or final point is at a pole. In the VDIST function, when traversing from a pole, the azimuth is 0 when heading away from the south pole and 180 when heading away from the north pole. In contrast, this VRECKON function uses the azimuth as noted in (3) above when traversing away form a pole.
  5. In testing, where the traversal subtends no more than 178 degrees, this function correctly inverts the VDIST function to within 0.2 millimeters of distance, 5e-10 degrees of forward azimuth, and 5e-10 degrees of reverse azimuth. Precision reduces as test points approach antipodal because the precision of VDIST is reduced for nearly antipodal points. (A warning is given by VDIST.)
  6. Tested but no warranty. Use at your own risk.
  7. Ver 1.0, Michael Kleder, November 2007. Ver 2.0, Joaquim Luis, September 2008

Added ellipsoid and vectorized whenever possible. Also, lon2 is always converted to the [-180 180] interval. Joaquim Luis

pymap3d.timeconv.str2dt(t)[source]

Converts times in string or list of strings to datetime(s)

output: datetime

pymap3d.datetime2hourangle.datetime2julian(t)[source]

Python datetime to Julian time

from D.Vallado Fundamentals of Astrodynamics and Applications p.187
and J. Meeus Astronomical Algorithms 1991 Eqn. 7.1 pg. 61
pymap3d.datetime2hourangle.datetime2sidereal(t, lon_radians, usevallado=True)[source]

Convert datetime to sidereal time

Algorithm:
  1. Vallado Fundamentals of Astrodynamics and Applications
t
Python datetime
lon
longitude in RADIANS
pymap3d.datetime2hourangle.julian2sidereal(juliandate)[source]

Convert Julian time to sidereal time

  1. Vallado Ed. 4

input:

juliandate
Julian centuries from J2000.0
pymap3d.haversine.angledist(lon1, lat1, lon2, lat2)[source]

inputs:

r0,d0
for first point, rightAscension,Declination [degrees] or (azimuth,elevation)
r1,d1
for second point, rightAscension,Declination [degrees] or (azimuth,elevation)

(or, azimuth/elevation respectively)

For reference, this is from astropy astropy/coordinates/angle_utilities.py Angular separation between two points on a sphere.

pymap3d.haversine.angledist_meeus(r0, d0, r1, d1)[source]

inputs:

r0,d0
for first point, rightAscension,Declination [degrees] or (azimuth,elevation)
r1,d1
for second point, rightAscension,Declination [degrees] or (azimuth,elevation)

(or, azimuth/elevation respectively)

from “Astronomical Algorithms” by Jean Meeus Ch. 16 p. 111 (16.5) gives angular distance in degrees between two rightAscension,Declination points in the sky. Neglecting atmospheric effects, of course.

Advantage of Meeus haversine method is stability all the way to exactly 0 deg.

assumes degrees input, degrees output

either the arrays must be the same size, or one of them must be a scalar

pymap3d.haversine.haversine(theta)[source]

Compute haversine of angle theta (radians)

http://en.wikipedia.org/wiki/Haversine Meeus p. 111

converts right ascension, declination to azimuth, elevation and vice versa. Normally do this via AstroPy. These functions are fallbacks for those who don’t wish to use AstroPy (perhaps Python 2.7 users).

Michael Hirsch implementation of algorithms from D. Vallado

pymap3d.vallado.vazel2radec(az_deg, el_deg, lat_deg, lon_deg, t)[source]

convert azimuth, elevation to right ascension, declination

Inputs

az_deg
Numpy ndarray of azimuth to point [degrees]
el_deg
Numpy ndarray of elevation to point [degrees]
lat_deg
scalar observer WGS84 latitude [degrees]
lon_deg
scalar observer WGS84 longitude [degrees]
t
time of observation

Outputs

ra_deg
Numpy ndarray of right ascension values [degrees]
dec_deg
Numpy ndarray of declination values [degrees]

from D.Vallado Fundamentals of Astrodynamics and Applications p.258-259

pymap3d.vallado.vradec2azel(ra_deg, dec_deg, lat_deg, lon_deg, t)[source]

convert right ascension, declination to azimuth, elevation

Inputs

ra_deg
Numpy ndarray of right ascension values [degrees]
dec_deg
Numpy ndarray of declination values [degrees]
lat_deg
scalar observer WGS84 latitude [degrees]
lon_deg
scalar observer WGS84 longitude [degrees]
t
time of observation

Outputs

az_deg
Numpy ndarray of azimuth to point [degrees]
el_deg
Numpy ndarray of elevation to point [degrees]
from D. Vallado “Fundamentals of Astrodynamics and Applications “
4th Edition Ch. 4.4 pg. 266-268

Indices and tables