spacepy.ctrans

CTrans: Module for backend coordinate transformations in SpacePy

This module is primarily intended to provide a backend for the standard Coords class rather than direct use, and the interface is subject to change.

The CTrans class calculates all of the necessary information to convert between different coordinate systems at a single time. By using Coords the handling of multiple times is built in, and the calling syntax is backwards compatible with the legacy IRBEM-backed coordinate transforms.

Coordinate systems supported by this module can broadly be described by two categories. The first category is a broad set of Earth-centered coordinate systems that are specified by astronomical parameters. If we consider the International Celestial Reference Frame to be our starting point, then taking the origin as the center of the Earth instead of the solar barycenter gives us the Geocentric Celestial Reference Frame (GCRF). All coordinate systems described here are right-handed Cartesian systems, except geodetic.

Systems and their relationships:

• ECI2000: Earth-Centered Inertial, J2000 epoch

  This system can be considered equivalent to the GCRF, to within 10s of milliarcseconds. The z-axis is aligned with the mean celestial pole at the J2000 epoch. The x-axis is aligned with the mean equinox at the J2000 epoch. The y-axis completes and lies in the plane of the celestial equator.

• ECIMOD: Earth-Centered Inertial, Mean-of-Date

  This system accounts for precession between the J2000 epoch and the date of interest: The coordinate system is time-dependent. The system is defined similarly to ECI2000, but uses the mean equinox and mean equator of the date of interest.

• ECITOD: Earth-Centered Inertial, True-of-Date

  This system builds on ECIMOD and accounts for the nutation (the short- period perturbations on the precession). This system is therefore considered to use the true equator and true equinox of date.

• TEME: Earth-Centered Inertial, True Equator Mean Equinox

  This system is poorly defined in the literature, despite being used in the SGP4 orbital propagator (note that multiple versions of SGP4 exist, see e.g. Vallado et al. 2006; AIAA 2006-6753-Rev2). The mean equinox here is not the same as the mean equinox used in, e.g., ECIMOD, but lies along the true equator between the origin of the Pseudo Earth Fixed and ECITOD frames. It is highly recommended that TEME coordinates are converted to a standard system (e.g., ECI2000) before passing to other users or to different software.

• GSE: Geocentric Solar Ecliptic

  This system is not inertial. It is Earth-centered, with the x-axis pointing towards the Sun. The y-axis lies in the mean ecliptic plane of date, pointing in the anti-orbit direction. The z-axis is parallel to the mean ecliptic pole.

• GEO: Geocentric Geographic

  This system is not inertial. It is Earth-Centered and Earth-Fixed (also called ECEF), so that the coordinates of a point fixed on (or relative to) the surface of the Earth do not change. The x-axis lies in the Earth’s equatorial plane (zero latitude) and intersects the Prime Meridian (zero longitude; Greenwich, UK). The z-axis points to True North (which is roughly aligned with the instantaneous rotation axis).

• GDZ: Geodetic

  This system is not inertial and is defined in terms of altitude above a reference ellipsoid, the geodetic latitude, and geodetic longitude. Geodetic longitude is identical to GEO longitude. Both the altitude and latitude depend on the ellipsoid used. While geodetic latitude is close to geographic latitude, they are not the same. The default here is to use the WGS84 reference ellipsoid.

The remaining coordinate systems are also reference to Earth’s magnetic field. Different versions of these systems exist, but the most common (and those given here) use a centered dipole axis.

• GSM: Geocentric Solar Magnetospheric

  This system is similar to GSE, but is defined such that the centered dipole lies in the x-z plane. As in all of these systems, z is positive northward. The y-axis is thus perpendicular to both the Sun-Earth line and the centered dipole axis (of date, defined using the first 3 coefficients of the IGRF/DGRF). GSM is therefore a rotation about the x-axis from the GSE system.

• SM: Solar Magnetic

  The z-axis is aligned with the centered dipole axis of date (positive northward), and the y-axis is perpendicular to both the Sun-Earth line and the dipole axis. As with GSE and GSM, y is positive in the anti-orbit direction. The x-axis therefore is not aligned with the Sun-Earth line and SM is a rotation about the y-axis from the GSM system.

• CDMAG: Geomagnetic

  This is a geomagnetic analog of the GEO system. The z-axis is aligned with the centered dipole axis of date. The y-axis is perpendicular to to both the dipole axis and True North, i.e., y is the cross product of the z-axis of the GEO system with the dipole axis. The x-axis completes.

Submodules

iau80n

IAU 1980 Nutation model

Functions

convert_multitime(coords, ticks, sys_in, sys_out)	Convert coordinates for N times, where N >= 1
gdz_to_geo(gdzvec[, units, geoid])	Convert geodetic (GDZ) coordinates to geocentric geographic
geo_to_gdz(geovec[, units, geoid])	Convert geocentric geographic (cartesian GEO) to geodetic (spherical GDZ)
geo_to_rll(geovec[, units, geoid])	Calculate RLL from geocentric geographic (GEO) coordinates
rll_to_geo(rllvec[, units, geoid])	Calculate geocentric geographic (GEO) from RLL coordinates

Classes

CTrans(ctime[, ephmodel, pnmodel, eop])	Coordinate transformation class for a single instance in time
Ellipsoid([name, A, iFlat])	Ellipsoid definition class for geodetic coordinates

spacepy.ctrans.convert_multitime(coords, ticks, sys_in, sys_out, defaults=None, itol=None)

Convert coordinates for N times, where N >= 1

Parameters:

coordsarray-like

Coordinates as Nx3 array. Cartesian assumed unless input system is geodetic.

ticksspacepy.time.Ticktock

Times for each element of coords. Must contain either N times or 1 time.

sys_instr

Name of input coordinate system.

sys_outstr

Name of output coordinate system.

Other Parameters:

defaultsnamedtuple or None

Named tuple with parameters from coordinates module

itolfloat

Time tolerance, in seconds, for using a unique set of conversions. Default is 1. Supplying a defaults namedtuple (i.e., if routine is called by spacepy.cooordinates.Coords.convert) will override this value.

spacepy.ctrans.gdz_to_geo(gdzvec, units='km', geoid={'1mE2': 0.9933056200098587, 'A': 6378.137, 'A2': 40680631.59076899, 'A2mB2': 272331.60610755533, 'B': 6356.752314245179, 'B2': 40408299.98466144, 'E2': 0.0066943799901413165, 'E4': 4.481472345240445e-05, 'EP2': 0.0067394967422764514, 'Flat': 0.0033528106647474805, 'iFlat': 298.257223563})

Convert geodetic (GDZ) coordinates to geocentric geographic

Parameters:

gdzvecarray-like

Nx3 array of geodetic altitude, latitude, longitude (in specified units)

Returns:

outnumpy.ndarray

Nx3 array of geocentric geographic x, y, z coordinates

Other Parameters:

unitsstr

Units for input geodetic altitude. Options are ‘km’ or ‘Re’. Default is ‘km’. Output units will be the same as input units.

geoidspacepy.ctrans.Ellipsoid

Instance of a reference ellipsoid to use for geodetic conversion. Default is WGS84.

Notes

Added in version 0.3.0.

spacepy.ctrans.geo_to_gdz(geovec, units='km', geoid={'1mE2': 0.9933056200098587, 'A': 6378.137, 'A2': 40680631.59076899, 'A2mB2': 272331.60610755533, 'B': 6356.752314245179, 'B2': 40408299.98466144, 'E2': 0.0066943799901413165, 'E4': 4.481472345240445e-05, 'EP2': 0.0067394967422764514, 'Flat': 0.0033528106647474805, 'iFlat': 298.257223563})

Convert geocentric geographic (cartesian GEO) to geodetic (spherical GDZ)

Uses Heikkinen’s exact solution [1], see Zhu et al. [2] for details.

Parameters:

geovecarray-like

Nx3 array (or array-like) of geocentric geographic [x, y, z] coordinates

Returns:

outnumpy.ndarray

Nx3 array of geodetic altitude, latitude, and longitude

Notes

Added in version 0.3.0.

References

[1]

Heikkinen, M., “Geschlossene formeln zur berechnung raumlicher geodatischer koordinaten aus rechtwinkligen koordinaten”, Z. Vermess., vol. 107, pp. 207-211, 1982.

[2]

J. Zhu, “Conversion of Earth-centered Earth-fixed coordinates to geodetic coordinates,” in IEEE Transactions on Aerospace and Electronic Systems, vol. 30, no. 3, pp. 957-961, July 1994, doi: 10.1109/7.303772.

spacepy.ctrans.geo_to_rll(geovec, units='km', geoid={'1mE2': 0.9933056200098587, 'A': 6378.137, 'A2': 40680631.59076899, 'A2mB2': 272331.60610755533, 'B': 6356.752314245179, 'B2': 40408299.98466144, 'E2': 0.0066943799901413165, 'E4': 4.481472345240445e-05, 'EP2': 0.0067394967422764514, 'Flat': 0.0033528106647474805, 'iFlat': 298.257223563})

Calculate RLL from geocentric geographic (GEO) coordinates

Parameters:

geovecarray-like

Nx3 array of geographic radius, latitude, longitude (in specified units)

Returns:

rllvecnumpy.ndarray

Nx3 array of [distance from Earth’s center, geodetic latitude, geodetic longitude]

Other Parameters:

unitsstr

Units for input geodetic altitude. Options are ‘km’ or ‘Re’. Default is ‘km’. Output units will be the same as input units.

geoidspacepy.ctrans.Ellipsoid

Instance of a reference ellipsoid to use for geodetic conversion. Default is WGS84.

Notes

Added in version 0.3.0.

spacepy.ctrans.rll_to_geo(rllvec, units='km', geoid={'1mE2': 0.9933056200098587, 'A': 6378.137, 'A2': 40680631.59076899, 'A2mB2': 272331.60610755533, 'B': 6356.752314245179, 'B2': 40408299.98466144, 'E2': 0.0066943799901413165, 'E4': 4.481472345240445e-05, 'EP2': 0.0067394967422764514, 'Flat': 0.0033528106647474805, 'iFlat': 298.257223563})

Calculate geocentric geographic (GEO) from RLL coordinates

Parameters:

rllvecarray-like

Nx3 array of geocentric radius, geodetic latitude, geodetic longitude (in specified units)

Returns:

geoarrnumpy.ndarray

Nx3 array of [altitude, geodetic latitude, geodetic longitude]

Other Parameters:

unitsstr

Units for input geocentric radii. Options are ‘km’ or ‘Re’. Default is ‘km’. Output units will be the same as input units.

geoidspacepy.ctrans.Ellipsoid

Instance of a reference ellipsoid to use for geodetic conversion. Default is WGS84.

Notes

Added in version 0.3.0.