frame_conversion#

Conversions between different reference frames.

This module provide a variety of functions and classes to convert between different reference frames. Functionality to convert between different state representations is provided in the element_conversion module.

Notes#

  • All reference frames used should be assumed as right handed: \(\mathbf{X}\times\mathbf{Y}=\mathbf{Z}\).

  • We distinguish between two different uses of the term ‘inertial:

    • An inertial origin: the frame has a non-accelerating origin. On solar system scales, the solar system barycenter (SSB) is considered to be the only inertial origin.

    • An inertial orientation: the unit axes of the frame are non-rotating with respect to the celestial background. This module is concerned primarily with conversions between different orientations.

  • Examples of and inertial origin include J2000 (a.k.a EME2000), as well as the SPICE-defined ECLIPJ2000 frame (see this description on our user guide). The use of the ICRF frame (difference from J2000 is <0.1 arcseconds) in Tudat is presently limited to the numerical_simulation model, see gcrs_to_itrs().

References#

1(1,2)

Archinal, B.A., Acton, C.H., A’Hearn, M.F. et al. Report of the IAU Working Group on Cartographic Coordinates and Rotational Elements: 2015. Celest Mech Dyn Astr 130, 22 (2018). https://doi.org/10.1007/s10569-017-9805-5

Functions#

inertial_to_rsw_rotation_matrix(...)

Computes the rotation matrix from inertial to RSW frame.

rsw_to_inertial_rotation_matrix(...)

Computes the rotation matrix from RSW to inertial frame.

inertial_to_tnw_rotation_matrix(...[, ...])

Computes the rotation matrix from inertial to TNW frame.

tnw_to_inertial_rotation_matrix(...[, ...])

Computes the rotation matrix from TNW to inertial frame.

inertial_to_body_fixed_rotation_matrix(...)

Computes the rotation matrix from inertial to body-fixed frame.

body_fixed_to_inertial_rotation_matrix(...)

Computes the rotation matrix from body-fixed to inertial frame.
inertial_to_rsw_rotation_matrix(inertial_cartesian_state: numpy.ndarray[numpy.float64[6, 1]]) → numpy.ndarray[numpy.float64[3, 3]]#

Computes the rotation matrix from inertial to RSW frame.

Function to compute the rotation matrix from inertial to RSW frame. The RSW frame is defined by the state of a body w.r.t. to some central body. The x-axis of the RSW frame points away from the origin, and the y-axis lies in the orbital plane, and is positive for in the direction of the velocity vector (but is not colinear with the velocity vector, except for circular orbits). The z-axis is perpendicular to the orbital plane, and completes the right-handed coordinate system.

Parameters

inertial_cartesian_state (numpy.ndarray) – Cartesian state, in an inertial frame, for which the rotation matrix is to be calculated. Note that the RSW frame is defined w.r.t. some central body, and this Cartesian state must be defined w.r.t. that central body (e.g. central body at the origin).

Returns

Rotation matrix from inertial to RSW frame.

Return type

numpy.ndarray

rsw_to_inertial_rotation_matrix(inertial_cartesian_state: numpy.ndarray[numpy.float64[6, 1]]) → numpy.ndarray[numpy.float64[3, 3]]#

Computes the rotation matrix from RSW to inertial frame.

Function to compute the rotation matrix from RSW to inertial. The RSW frame is defined by the state of a body w.r.t. to some central body. The x-axis of the RSW frame points away from the origin, and the y-axis lies in the orbital plane, and is positive for in the direction of the velocity vector (but is not colinear with the velocity vector, except for circular orbits). The z-axis is perpendicular to the orbital plane, and completes the right-handed coordinate system.

Parameters

inertial_cartesian_state (numpy.ndarray) – Cartesian state, in an inertial frame, for which the rotation matrix is to be calculated. Note that the RSW frame is defined w.r.t. some central body, and this Cartesian state must be defined w.r.t. that central body (e.g. central body at the origin).

Returns

Rotation matrix from RSW to inertial frame.

Return type

numpy.ndarray

inertial_to_tnw_rotation_matrix(inertial_cartesian_state: numpy.ndarray[numpy.float64[6, 1]], n_axis_points_away_from_central_body: bool = True) → numpy.ndarray[numpy.float64[3, 3]]#

Computes the rotation matrix from inertial to TNW frame.

Function to compute the rotation matrix from inertial to TNW frame. The TNW frame is defined by the state of a body w.r.t. to some central body. The x-axis of the TNW frame points along the velocity vector, and the y-axis lies in the orbital plane, and is positive in the direction away from the central body (or positive towards the central body if the n_axis_points_away_from_central_body variable is set to false, see below). The z-axis is perpendicular to the orbital plane, and completes the right-handed coordinate system.

Parameters

  • inertial_cartesian_state (numpy.ndarray) – Cartesian state, in an inertial frame, for which the rotation matrix is to be calculated. Note that the RSW frame is defined w.r.t. some central body, and this Cartesian state must be defined w.r.t. that central body (e.g. central body at the origin).

  • n_axis_points_away_from_central_body (Boolean) – Boolean (default is True) defining whether the N axis of the TNW frame points away from the central body (if True) or towards the central body (if False).

Returns

Rotation matrix from inertial to TNW frame.

Return type

numpy.ndarray

tnw_to_inertial_rotation_matrix(inertial_cartesian_state: numpy.ndarray[numpy.float64[6, 1]], n_axis_points_away_from_central_body: bool = True) → numpy.ndarray[numpy.float64[3, 3]]#

Computes the rotation matrix from TNW to inertial frame.

Function to compute the rotation matrix from TNW to inertial frame. The TNW frame is defined by the state of a body w.r.t. to some central body. The x-axis of the TNW frame points along the velocity vector, and the y-axis lies in the orbital plane, and is positive in the direction away from the central body (or positive towards the central body if the n_axis_points_away_from_central_body variable is set to false, see below). The z-axis is perpendicular to the orbital plane, and completes the right-handed coordinate system.

Parameters

  • inertial_cartesian_state (numpy.ndarray) – Cartesian state, in an inertial frame, for which the rotation matrix is to be calculated. Note that the TNW frame is defined w.r.t. some central body, and this Cartesian state must be defined w.r.t. that central body (e.g. central body at the origin).

  • n_axis_points_away_from_central_body (bool) – Boolean (default=``True``) defining whether the N axis of the TNW frame points away from the central body (if True) or towards the central body (if False).

Returns

Rotation matrix from TNW to inertial frame

Return type

numpy.ndarray

inertial_to_body_fixed_rotation_matrix(pole_declination: float, pole_right_ascension: float, prime_meridian_longitude: float) → numpy.ndarray[numpy.float64[3, 3]]#

Computes the rotation matrix from inertial to body-fixed frame.

Function to compute the rotation matrix from inertial to body-fixed frame, using typical pole right ascension (\(\alpha\)), pole declination (\(\delta\)), and prime meridian longitude (\(W\)) angles.

Parameters

  • pole_declination (float) – Declination of body pole in inertial frame (\(\delta\)).

  • pole_right_ascension (float) – Right ascension of body pole in inertial frame (\(\alpha\)).

  • prime_meridian_longitude (float) – Longitude of prime meridian w.r.t. intermediate frame (\(W\)).

Returns

Rotation matrix from inertial to body-fixed frame

Return type

numpy.ndarray

Notes

This definition of a body-fixed orientation is used by, for instance, the IAU Working Group on Cartographic Coordinates and Rotational Elements. Rotation is performed by a successive z-x-z Euler angle rotation (see Archinal et al. 1).

body_fixed_to_inertial_rotation_matrix(pole_declination: float, pole_right_ascension: float, pole_meridian: float) → numpy.ndarray[numpy.float64[3, 3]]#

Computes the rotation matrix from body-fixed to inertial frame.

Function to compute the rotation matrix from body-fixed to inertial frame, using typical pole right ascension (\(\alpha\)), pole declination (\(\delta\)), and prime meridian longitude (\(W\)) angles.

Parameters

  • pole_declination (float) – Declination of body pole in inertial frame (\(\delta\)).

  • pole_right_ascension (float) – Right ascension of body pole in inertial frame (\(\alpha\)).

  • prime_meridian_longitude (float) – Longitude of prime meridian w.r.t. intermediate frame (\(W\)).

Returns

Rotation matrix from body-fixed to inertial frame.

Return type

numpy.ndarray

Notes

This definition of a body-fixed orientation is used by, for instance, the IAU Working Group on Cartographic Coordinates and Rotational Elements. Rotation is performed by a successive z-x-z Euler angle rotation (see Archinal et al. 1).