Reference Frames Module¶

Reference frame transformations between ECI and ECEF coordinate systems.

frames ¶

Reference Frames Module

Reference frame transformations between ECI and ECEF coordinate systems.

This module provides transformations between: - ECI (Earth-Centered Inertial): J2000/GCRF frame - ECEF (Earth-Centered Earth-Fixed): ITRF frame

The transformations implement the IAU 2006/2000A precession-nutation model and use Earth Orientation Parameters (EOP) for high-precision conversions.

Functions are provided for: - Rotation matrices (bias-precession-nutation, Earth rotation, polar motion) - Position vector transformations - State vector (position + velocity) transformations

bias_precession_nutation `builtin` ¶

bias_precession_nutation(epc: Epoch) -> Any

Computes the Bias-Precession-Nutation matrix transforming the GCRS to the CIRS intermediate reference frame. This transformation corrects for the bias, precession, and nutation of Celestial Intermediate Origin (CIO) with respect to inertial space.

This formulation computes the Bias-Precession-Nutation correction matrix according using a CIO based model using using the IAU 2006 precession and IAU 2000A nutation models.

The function will utilize the global Earth orientation and loaded data to apply corrections to the Celestial Intermediate Pole (CIP) derived from empirical observations.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch instant for computation of transformation matrix	required

Returns:

Type	Description
`ndarray`	3x3 rotation matrix transforming `GCRS` -> `CIRS`

References

IAU SOFA Tools For Earth Attitude, Example 5.5 http://www.iausofa.org/2021_0512_C/sofa/sofa_pn_c.pdf Software Version 18, 2021-04-18

earth_rotation `builtin` ¶

earth_rotation(epc: Epoch) -> Any

Computes the Earth rotation matrix transforming the CIRS to the TIRS intermediate reference frame. This transformation corrects for the Earth rotation.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch instant for computation of transformation matrix	required

Returns:

Type	Description
`ndarray`	3x3 rotation matrix transforming `CIRS` -> `TIRS`

polar_motion `builtin` ¶

polar_motion(epc: Epoch) -> Any

Computes the Earth rotation matrix transforming the TIRS to the ITRF reference frame.

The function will utilize the global Earth orientation and loaded data to apply corrections to compute the polar motion correction based on empirical observations of polar motion drift.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch instant for computation of transformation matrix	required

Returns:

Type	Description
`ndarray`	3x3 rotation matrix transforming `TIRS` -> `ITRF`

rotation_eci_to_ecef `builtin` ¶

rotation_eci_to_ecef(epc: Epoch) -> Any

Computes the combined rotation matrix from the inertial to the Earth-fixed reference frame. Applies corrections for bias, precession, nutation, Earth-rotation, and polar motion.

The transformation is accomplished using the IAU 2006/2000A, CIO-based theory using classical angles. The method as described in section 5.5 of the SOFA C transformation cookbook.

The function will utilize the global Earth orientation and loaded data to apply corrections for Celestial Intermidate Pole (CIP) and polar motion drift derived from empirical observations.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch instant for computation of transformation matrix	required

Returns:

Type	Description
`ndarray`	3x3 rotation matrix transforming `GCRF` -> `ITRF`

Example

import brahe as bh
import numpy as np

# Create epoch
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)

# Get rotation matrix
R = bh.rotation_eci_to_ecef(epc)
print(f"Rotation matrix shape: {R.shape}")
# Output: Rotation matrix shape: (3, 3)

rotation_ecef_to_eci `builtin` ¶

rotation_ecef_to_eci(epc: Epoch) -> Any

Computes the combined rotation matrix from the Earth-fixed to the inertial reference frame. Applies corrections for bias, precession, nutation, Earth-rotation, and polar motion.

The transformation is accomplished using the IAU 2006/2000A, CIO-based theory using classical angles. The method as described in section 5.5 of the SOFA C transformation cookbook.

The function will utilize the global Earth orientation and loaded data to apply corrections for Celestial Intermidate Pole (CIP) and polar motion drift derived from empirical observations.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch instant for computation of transformation matrix	required

Returns:

Type	Description
`ndarray`	3x3 rotation matrix transforming `ITRF` -> `GCRF`

Example

import brahe as bh

# Create epoch
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)

# Get rotation matrix from ECEF to ECI
R = bh.rotation_ecef_to_eci(epc)
print(f"Rotation matrix shape: {R.shape}")

position_eci_to_ecef `builtin` ¶

position_eci_to_ecef(epc: Epoch, x: ndarray) -> Any

Transforms a position vector from the Earth Centered Inertial (ECI/GCRF) frame to the Earth Centered Earth Fixed (ECEF/ITRF) frame.

Applies the full IAU 2006/2000A transformation including bias, precession, nutation, Earth rotation, and polar motion corrections using global Earth orientation parameters.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch instant for the transformation	required
`x`	`ndarray`	Position vector in `ECI` frame (m), shape `(3,)`	required

Returns:

Type	Description
`ndarray`	Position vector in `ECEF` frame (m), shape `(3,)`

Example

import brahe as bh
import numpy as np

# Create epoch
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)

# Position vector in ECI (meters)
r_eci = np.array([7000000.0, 0.0, 0.0])

# Transform to ECEF
r_ecef = bh.position_eci_to_ecef(epc, r_eci)
print(f"ECEF position: {r_ecef}")

position_ecef_to_eci `builtin` ¶

position_ecef_to_eci(epc: Epoch, x: ndarray) -> Any

Transforms a position vector from the Earth Centered Earth Fixed (ECEF/ITRF) frame to the Earth Centered Inertial (ECI/GCRF) frame.

Applies the full IAU 2006/2000A transformation including bias, precession, nutation, Earth rotation, and polar motion corrections using global Earth orientation parameters.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch instant for the transformation	required
`x`	`ndarray`	Position vector in `ECEF` frame (m), shape `(3,)`	required

Returns:

Type	Description
`ndarray`	Position vector in `ECI` frame (m), shape `(3,)`

Example

import brahe as bh
import numpy as np

# Create epoch
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)

# Position in ECEF (ground station)
r_ecef = np.array([4000000.0, 3000000.0, 4000000.0])

# Transform to ECI
r_eci = bh.position_ecef_to_eci(epc, r_ecef)
print(f"ECI position: {r_eci}")

state_eci_to_ecef `builtin` ¶

state_eci_to_ecef(epc: Epoch, x_eci: ndarray) -> ndarray

Transforms a state vector (position and velocity) from the Earth Centered Inertial (ECI/GCRF) frame to the Earth Centered Earth Fixed (ECEF/ITRF) frame.

Applies the full IAU 2006/2000A transformation including bias, precession, nutation, Earth rotation, and polar motion corrections using global Earth orientation parameters. The velocity transformation accounts for the Earth's rotation rate.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch instant for the transformation	required
`x_eci`	`ndarray`	State vector in `ECI` frame `[position (m), velocity (m/s)]`, shape `(6,)`	required

Returns:

Type	Description
`ndarray`	State vector in `ECEF` frame `[position (m), velocity (m/s)]`, shape `(6,)`

Example

import brahe as bh
import numpy as np

# Create epoch
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)

# State vector in ECI [x, y, z, vx, vy, vz] (meters, m/s)
state_eci = np.array([bh.R_EARTH + 500e3, 0.0, 0.0, 0.0, 7600.0, 0.0])

# Transform to ECEF
state_ecef = bh.state_eci_to_ecef(epc, state_eci)
print(f"ECEF state: {state_ecef}")

state_ecef_to_eci `builtin` ¶

state_ecef_to_eci(epc: Epoch, x_ecef: ndarray) -> ndarray

Transforms a state vector (position and velocity) from the Earth Centered Earth Fixed (ECEF/ITRF) frame to the Earth Centered Inertial (ECI/GCRF) frame.

Applies the full IAU 2006/2000A transformation including bias, precession, nutation, Earth rotation, and polar motion corrections using global Earth orientation parameters. The velocity transformation accounts for the Earth's rotation rate.

Parameters:

Name	Type	Description	Default
`epc`	`Epoch`	Epoch instant for the transformation	required
`x_ecef`	`ndarray`	State vector in `ECEF` frame `[position (m), velocity (m/s)]`, shape `(6,)`	required

Returns:

Type	Description
`ndarray`	State vector in `ECI` frame `[position (m), velocity (m/s)]`, shape `(6,)`

Example

import brahe as bh
import numpy as np

# Create epoch
epc = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0.0, 0.0, bh.TimeSystem.UTC)

# State vector in ECEF [x, y, z, vx, vy, vz] (meters, m/s)
state_ecef = np.array([4000000.0, 3000000.0, 4000000.0, 100.0, -50.0, 200.0])

# Transform to ECI
state_eci = bh.state_ecef_to_eci(epc, state_ecef)
print(f"ECI state: {state_eci}")

Reference Frames Module¶

frames ¶

bias_precession_nutation builtin ¶

earth_rotation builtin ¶

polar_motion builtin ¶

rotation_eci_to_ecef builtin ¶

rotation_ecef_to_eci builtin ¶

position_eci_to_ecef builtin ¶

position_ecef_to_eci builtin ¶

state_eci_to_ecef builtin ¶

state_ecef_to_eci builtin ¶

bias_precession_nutation `builtin` ¶

earth_rotation `builtin` ¶

polar_motion `builtin` ¶

rotation_eci_to_ecef `builtin` ¶

rotation_ecef_to_eci `builtin` ¶

position_eci_to_ecef `builtin` ¶

position_ecef_to_eci `builtin` ¶

state_eci_to_ecef `builtin` ¶

state_ecef_to_eci `builtin` ¶