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. Note that the functionality here may be used independent of the Tudat models in numerical_simulation. For more details on the use of frames in the context of these models, see this page

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 the most ‘typical’ 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 an inertial orientation 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#

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]).