Frames¶

Frame transformations.

This sub-module provides functions for converting between common coordinate frames used in astrodynamics:

GCRF-ITRF transformations: converting between the Geocentric Celestial Reference Frame and the International Terrestrial Reference Frame using the full IAU 2006/2000A CIO-based model (bias-precession-nutation, Earth rotation angle, and polar motion).
TEME transformations: converting SGP4 output (TEME frame) to PEF, ITRF, and GCRF via GMST rotation and polar motion.
Ecliptic-ICRF transformations: converting between the ecliptic coordinate frame and ICRF via a fixed rotation by the J2000 mean obliquity.
ECI-ECEF aliases: backward-compatible names mapping to GCRF/ITRF functions.

`bias_precession_nutation(eop, epc)` ¶

Compute the bias-precession-nutation matrix (GCRF -> CIRS).

Uses the IAU 2006/2000A CIO-based model with dX/dY corrections from EOP data applied to the CIP coordinates.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data providing dX, dY celestial pole offsets.	required
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 rotation matrix (GCRF -> CIRS).

`earth_rotation(eop, epc)` ¶

Compute the Earth rotation matrix at the given epoch.

This is the full IAU 2006/2000A GCRF -> ITRF rotation combining bias-precession-nutation, Earth rotation angle, and polar motion. Equivalent to :func:rotation_gcrf_to_itrf.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 Earth rotation matrix (GCRF -> ITRF).

`earth_rotation_angle(eop, epc)` ¶

Compute the Earth rotation matrix (CIRS -> TIRS).

Uses the IAU 2000 Earth Rotation Angle with UT1 time from EOP data.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data providing UT1-UTC offset.	required
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 Earth rotation matrix.

`polar_motion(eop, epc)` ¶

Compute the polar motion matrix (TIRS -> ITRF).

Uses polar motion parameters from EOP data and the TIO locator s'.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data providing pm_x, pm_y polar motion parameters.	required
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 polar motion matrix.

`rotation_ecef_to_eci(eop, epc)` ¶

Compute the 3x3 rotation matrix from ECEF (ITRF) to ECI (GCRF).

Alias for :func:rotation_itrf_to_gcrf.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 rotation matrix (ECEF -> ECI).

`rotation_eci_to_ecef(eop, epc)` ¶

Compute the 3x3 rotation matrix from ECI (GCRF) to ECEF (ITRF).

Alias for :func:rotation_gcrf_to_itrf.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 rotation matrix (ECI -> ECEF).

`rotation_ecliptic_to_icrf()` ¶

Compute the 3x3 rotation matrix from ecliptic to ICRF.

Returns the matrix Rx(-ε) where ε is the J2000 mean obliquity.

Returns:

Type	Description
`Array`	3x3 rotation matrix (ecliptic -> ICRF).

Examples:

from astrojax.frames import rotation_ecliptic_to_icrf
R = rotation_ecliptic_to_icrf()
R.shape

`rotation_gcrf_to_itrf(eop, epc)` ¶

Compute the full 3x3 rotation matrix from GCRF to ITRF.

Combines polar motion, Earth rotation, and bias-precession-nutation: R = PM @ ER @ BPN

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 rotation matrix (GCRF -> ITRF).

Examples:

from astrojax import Epoch
from astrojax.eop import zero_eop
from astrojax.frames import rotation_gcrf_to_itrf
eop = zero_eop()
epc = Epoch(2024, 1, 1)
R = rotation_gcrf_to_itrf(eop, epc)
R.shape

`rotation_icrf_to_ecliptic()` ¶

Compute the 3x3 rotation matrix from ICRF to ecliptic.

Returns the matrix Rx(ε) where ε is the J2000 mean obliquity. This is the transpose of :func:rotation_ecliptic_to_icrf.

Returns:

Type	Description
`Array`	3x3 rotation matrix (ICRF -> ecliptic).

Examples:

from astrojax.frames import rotation_icrf_to_ecliptic
R = rotation_icrf_to_ecliptic()
R.shape

`rotation_itrf_to_gcrf(eop, epc)` ¶

Compute the full 3x3 rotation matrix from ITRF to GCRF.

This is the transpose of :func:rotation_gcrf_to_itrf.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 rotation matrix (ITRF -> GCRF).

`rotation_itrf_to_teme(eop, epc)` ¶

Compute the 3x3 rotation matrix from ITRF to TEME.

Transpose of :func:rotation_teme_to_itrf.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 rotation matrix (ITRF -> TEME).

`rotation_pef_to_teme(epc)` ¶

Compute the 3x3 rotation matrix from PEF to TEME.

Transpose of :func:rotation_teme_to_pef.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 rotation matrix (PEF -> TEME).

`rotation_teme_to_itrf(eop, epc)` ¶

Compute the 3x3 rotation matrix from TEME to ITRF.

Combines GMST rotation and polar motion: R = PM @ Rz(GMST)

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data providing polar motion parameters.	required
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 rotation matrix (TEME -> ITRF).

`rotation_teme_to_pef(epc)` ¶

Compute the 3x3 rotation matrix from TEME to PEF.

Applies Rz(GMST) to rotate from the mean equinox frame to the pseudo Earth-fixed frame.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch (UTC).	required

Returns:

Type	Description
`Array`	3x3 rotation matrix (TEME -> PEF).

`state_ecef_to_eci(eop, epc, x_ecef)` ¶

Transform a 6-element state vector from ECEF (ITRF) to ECI (GCRF).

Alias for :func:state_itrf_to_gcrf.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required
`x_ecef`	`ArrayLike`	6-element ECEF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element ECI state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

`state_eci_to_ecef(eop, epc, x_eci)` ¶

Transform a 6-element state vector from ECI (GCRF) to ECEF (ITRF).

Alias for :func:state_gcrf_to_itrf.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required
`x_eci`	`ArrayLike`	6-element ECI state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element ECEF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

`state_ecliptic_to_icrf(x_ecl)` ¶

Transform a 6-element state vector from ecliptic to ICRF.

Both position and velocity are rotated identically (no Coriolis correction) since both frames are inertial.

Parameters:

Name	Type	Description	Default
`x_ecl`	`ArrayLike`	6-element ecliptic state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element ICRF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

Examples:

import jax.numpy as jnp
from astrojax.frames import state_ecliptic_to_icrf
x_ecl = jnp.array([7000e3, 0.0, 0.0, 0.0, 7.5e3, 0.0])
x_icrf = state_ecliptic_to_icrf(x_ecl)

`state_gcrf_to_itrf(eop, epc, x_gcrf)` ¶

Transform a 6-element state vector from GCRF to ITRF.

Position is rotated directly. Velocity includes the correction for Earth's rotation (Coriolis effect):

.. math::

\mathbf{r}_{\text{ITRF}} &= PM \cdot ER \cdot BPN \cdot
    \mathbf{r}_{\text{GCRF}} \\
\mathbf{v}_{\text{ITRF}} &= PM \cdot \left(
    ER \cdot BPN \cdot \mathbf{v}_{\text{GCRF}}
    - \boldsymbol{\omega} \times (ER \cdot BPN \cdot
    \mathbf{r}_{\text{GCRF}}) \right)

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required
`x_gcrf`	`ArrayLike`	6-element GCRF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element ITRF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

`state_gcrf_to_teme(eop, epc, x_gcrf)` ¶

Transform a 6-element state vector from GCRF to TEME.

Chains GCRF -> ITRF -> TEME.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required
`x_gcrf`	`ArrayLike`	6-element GCRF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element TEME state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

`state_icrf_to_ecliptic(x_icrf)` ¶

Transform a 6-element state vector from ICRF to ecliptic.

Both position and velocity are rotated identically (no Coriolis correction) since both frames are inertial.

Parameters:

Name	Type	Description	Default
`x_icrf`	`ArrayLike`	6-element ICRF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element ecliptic state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

Examples:

import jax.numpy as jnp
from astrojax.frames import state_icrf_to_ecliptic
x_icrf = jnp.array([7000e3, 0.0, 0.0, 0.0, 7.5e3, 0.0])
x_ecl = state_icrf_to_ecliptic(x_icrf)

`state_itrf_to_gcrf(eop, epc, x_itrf)` ¶

Transform a 6-element state vector from ITRF to GCRF.

Applies the inverse of :func:state_gcrf_to_itrf.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required
`x_itrf`	`ArrayLike`	6-element ITRF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element GCRF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

`state_itrf_to_teme(eop, epc, x_itrf)` ¶

Transform a 6-element state vector from ITRF to TEME.

Inverse of :func:state_teme_to_itrf.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required
`x_itrf`	`ArrayLike`	6-element ITRF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element TEME state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

`state_pef_to_teme(epc, x_pef)` ¶

Transform a 6-element state vector from PEF to TEME.

Inverse of :func:state_teme_to_pef.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch (UTC).	required
`x_pef`	`ArrayLike`	6-element PEF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element TEME state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

`state_teme_to_gcrf(eop, epc, x_teme)` ¶

Transform a 6-element state vector from TEME to GCRF.

Chains TEME -> ITRF -> GCRF using the existing ITRF-GCRF transformation.

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data.	required
`epc`	`Epoch`	Epoch (UTC).	required
`x_teme`	`ArrayLike`	6-element TEME state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element GCRF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

`state_teme_to_itrf(eop, epc, x_teme)` ¶

Transform a 6-element state vector from TEME to ITRF.

Goes via PEF: applies GMST rotation and omega correction, then applies polar motion (position only, PM has negligible velocity effect).

Parameters:

Name	Type	Description	Default
`eop`	`EOPData`	EOP data providing polar motion parameters.	required
`epc`	`Epoch`	Epoch (UTC).	required
`x_teme`	`ArrayLike`	6-element TEME state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element ITRF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

`state_teme_to_pef(epc, x_teme)` ¶

Transform a 6-element state vector from TEME to PEF.

Velocity includes the Earth-rotation correction: v_pef = R @ v_teme - omega_earth x r_pef

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch (UTC).	required
`x_teme`	`ArrayLike`	6-element TEME state `[x, y, z, vx, vy, vz]`. Units: m, m/s.	required

Returns:

Type	Description
`Array`	6-element PEF state `[x, y, z, vx, vy, vz]`. Units: m, m/s.

Frames¶

bias_precession_nutation(eop, epc) ¶

earth_rotation(eop, epc) ¶

earth_rotation_angle(eop, epc) ¶

polar_motion(eop, epc) ¶

rotation_ecef_to_eci(eop, epc) ¶

rotation_eci_to_ecef(eop, epc) ¶

rotation_ecliptic_to_icrf() ¶

rotation_gcrf_to_itrf(eop, epc) ¶

rotation_icrf_to_ecliptic() ¶

rotation_itrf_to_gcrf(eop, epc) ¶

rotation_itrf_to_teme(eop, epc) ¶

rotation_pef_to_teme(epc) ¶

rotation_teme_to_itrf(eop, epc) ¶

rotation_teme_to_pef(epc) ¶

state_ecef_to_eci(eop, epc, x_ecef) ¶

state_eci_to_ecef(eop, epc, x_eci) ¶

state_ecliptic_to_icrf(x_ecl) ¶

state_gcrf_to_itrf(eop, epc, x_gcrf) ¶

state_gcrf_to_teme(eop, epc, x_gcrf) ¶

state_icrf_to_ecliptic(x_icrf) ¶

state_itrf_to_gcrf(eop, epc, x_itrf) ¶

state_itrf_to_teme(eop, epc, x_itrf) ¶

state_pef_to_teme(epc, x_pef) ¶

state_teme_to_gcrf(eop, epc, x_teme) ¶

state_teme_to_itrf(eop, epc, x_teme) ¶

state_teme_to_pef(epc, x_teme) ¶

`bias_precession_nutation(eop, epc)` ¶

`earth_rotation(eop, epc)` ¶

`earth_rotation_angle(eop, epc)` ¶

`polar_motion(eop, epc)` ¶

`rotation_ecef_to_eci(eop, epc)` ¶

`rotation_eci_to_ecef(eop, epc)` ¶

`rotation_ecliptic_to_icrf()` ¶

`rotation_gcrf_to_itrf(eop, epc)` ¶

`rotation_icrf_to_ecliptic()` ¶

`rotation_itrf_to_gcrf(eop, epc)` ¶

`rotation_itrf_to_teme(eop, epc)` ¶

`rotation_pef_to_teme(epc)` ¶

`rotation_teme_to_itrf(eop, epc)` ¶

`rotation_teme_to_pef(epc)` ¶

`state_ecef_to_eci(eop, epc, x_ecef)` ¶

`state_eci_to_ecef(eop, epc, x_eci)` ¶

`state_ecliptic_to_icrf(x_ecl)` ¶

`state_gcrf_to_itrf(eop, epc, x_gcrf)` ¶

`state_gcrf_to_teme(eop, epc, x_gcrf)` ¶

`state_icrf_to_ecliptic(x_icrf)` ¶

`state_itrf_to_gcrf(eop, epc, x_itrf)` ¶

`state_itrf_to_teme(eop, epc, x_itrf)` ¶

`state_pef_to_teme(epc, x_pef)` ¶

`state_teme_to_gcrf(eop, epc, x_teme)` ¶

`state_teme_to_itrf(eop, epc, x_teme)` ¶

`state_teme_to_pef(epc, x_teme)` ¶