# ctrans - Coordinate transformation backend

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.

## 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

## 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

## Submodules

`iau80n` | IAU 1980 Nutation model