use_rotation_matrices: Module to rotate instrument and transform between reference frames

use_rotation_matrices contains functions to

  1. calculate the GMST time from noon or midnight

2. compute the rotation matrices for the transformations between spacecraft orbital frame(ORF) and GEI J2000, J2K and ECEF, J2K and ITRF, ECEF and NED, ITRF and NEC, ITRF and NED, and NED and ENU.

Two sets of rotation matrices are provided to build up direction cosine matrix.

1. SET-1: According to Coordinate Transformations via Euler Angles, Riggs, 2019. Rev. E. expresses the inertial frame vectors in terms of rotated frame vectors used for transformation from a rotated frame to inertial frame gives i, j, k in terms of i’, j’, k’; abbreviated as r2i in the code definition of the reference: x (out), y (right), and z (up)

ROLL: positive is from +Y towards +Z PITCH: positive is from +Z towards +X YAW: positive is from +X towards +Y

2. SET-2: According to Curtis, H. D. (2013). Orbital mechanics for engineering students. expresses the rotated frame vectors in terms of inertial frame vectors for transformation from an inertial frame to rotated frame gives i’, j’, k’ in terms of i, j, k; abbreviated as i2r in the code RRI description: x (out), y (right), and z (down)

ROLL: positive is from +Y towards +Z PITCH: positive is from +Z towards +X YAW: positive is from +X towards +Y

@author: ceren, warren

use_rotation_matrices.GMST_midnight(utc_dt)

Calculates GMST in radians.

Includes day fraction corrected with respect to midnight.

Follows: Curtis, H. D. (2013). Orbital mechanics for engineering students. Butterworth-Heinemann. This formula gives GMST in degrees.

Parameters

utc_dt: datetime.datetime

time in UTC.

Returns

GMST: float

GMST in radians.

Examples

GMST = calculate_GMST_midnight(utc_dt_array)

use_rotation_matrices.GMST_noon(time_array)

Follows: Curtis, H. D. (2013). Orbital mechanics for engineering students. Butterworth-Heinemann. This formula gives GMST in degrees.

Includes day fraction corrected with respect to noon.

Parameters

time_arraydatetime.datetime

time in UTC.

Returns

GMST: float

GMST in radians.

Examples

GMST = calculate_GMST_noon(time_array)

use_rotation_matrices.RX_i2r(x)

Parameters

xfloat

roll angle (radians).

Returns

numpy.ndarray

Rotation matrix about x axis.

Examples

Rx = RX_i2r(roll)

use_rotation_matrices.RX_r2i(x)

Parameters

xfloat

roll angle (radians).

Returns

numpy.ndarray

Rotation matrix about x axis.

Examples

Rx = RX_r2i(roll)

use_rotation_matrices.RY_i2r(y)

Parameters

yfloat

pitch angle (radians).

Returns

numpy.ndarray

Rotation matrix about y axis.

Examples

Ry = RY_i2r(pitch)

use_rotation_matrices.RY_r2i(y)

Parameters

yfloat

pitch angle (radians).

Returns

numpy.ndarray

Rotation matrix about y axis.

Examples

Ry = RY_r2i(pitch)

use_rotation_matrices.RZ_i2r(z)

Parameters

zfloat

yaw angle (radians).

Returns

numpy.ndarray

Rotation matrix about z axis.

Examples

Rz = RZ_i2r(yaw)

use_rotation_matrices.RZ_r2i(z)

Parameters

zfloat

yaw angle (radians).

Returns

numpy.ndarray

Rotation matrix about z axis.

Examples

Rz = RZ_r2i(yaw)

use_rotation_matrices.ecef_to_gei_rm(theta_rad)

Function to calculate ECEF to GEI rotation matrix.

Uses the transpose of GEIJ2K to ECEF rotation matrix.

Parameters

theta_radfloat

GMST_midnight.

Returns

GEI2ECEFnumpy.ndarray[float]

Rotation matrix for transformations from GEI to ECEF.

Examples

R = ecef_to_gei_rm(theta_rad)

use_rotation_matrices.gei2ecef(inst_GEI, time_array)

function for GEIJ2K to ECEF transformations

Parameters

inst_GEInp.ndarray[float]

instrument look direction in GEIJ2K .

time_arraydatetime.datetime

experiment time interval.

Returns

inst_ECEFnp.ndarray[float]

instrument look direction in GEIJ2K.

Examples

inst_ECEF = gei2ecef(inst_GEI, time_array)

use_rotation_matrices.gei_to_ecef_rm(theta_rad)

Function to calculate the GEI to ECEF rotation matrix.

One rotation is needed in xy frame (yaw rotation) to transform from GEIJ2K to ECEF. Yaw angle is the azimuth angle between GEIJ2K and ECEF in this case.

Azimuth= Greenwich sidereal time + Earth’s rotation speed * UTC.

Ref: 1. J. Riggs, Coordinate transformations via Euler Angle Rotations, Rev. E - 10 April 2019

    1. Sofyali, Orbital Mechanics notes, 7 February 2019.

Parameters

theta_radfloat

GMST_midnight.

Returns

rm_GEI2ECEFnumpy.ndarray[float]

Rotation matrix for transformations from GEI to ECEF.

Examples

R = gei_to_ecef_rm(theta_rad)

use_rotation_matrices.gei_to_oe_rm(inc, raan, ap)

Function to calculate the GEI to orbital frame matrix.

GEI2OE matrix is the transpose of OE2GEI matrix.

Parameters

incfloat

satellite inclination (in radians).

raanfloat

satellite right ascension of ascending node (in radians).

apfloat

satellite argument of periapsis (in radians).

Returns

rm_GEI2OEnumpy.ndarray[float]

orbital frame to GEI matrix using satellite orbital elements.

Examples

R = gei_to_oe(sat_raan, sat_inc, sat_ap)

use_rotation_matrices.icrf2itrf(inst_GEI, path_to_files, time_array)

Function to transform the pointing vector in GEIJ2K to ITRF.

Notes

Uses Python wrappers for the Standards of Fundamental Astronomy library https://www.iausofa.org/

Parameters

inst_GEInumpy.ndarray[float]

instrument look direction in GEIJ2K.

path_to_filesstr

IES and EOP file path.

time_arraydatetime.datetime

time array.

Returns

inst_ITRFnumpy.ndarray[float]

instrument look direction in ITRF.

Examples

inst_ITRF = icrf2itrf(inst_GEI, path_to_files, time_array,

GEOx, GEOy, GEOz)

use_rotation_matrices.icrf_to_itrf_rm(path_to_files, input_time)

Function to calculate the ICRF to ITRF matrix using pysofa routines.

Parameters

path_to_filesstr

path_to_initialization files (IERS and EOP).

input_timedatetime.datetime

time.

Returns

rm_ICRF2ITRFnumpy.ndarray[float]

ICRF to ITRF rotation matrix.

use_rotation_matrices.itrf_to_icrf_rm(path_to_files, time_array)

Function to calculate ITRF to ICRF rotation matrix using pysofa routines.

Uses the transpose of ITRF to ICRF rotation matrix.

Parameters

path_to_filesstr

path_to_initialization files (IERS and EOP).

time_arraydatetime.datetime

time array.

Returns

rm_ICRF2ITRFnumpy.ndarray[float]

ICRF to ITRF rotation matrix.

use_rotation_matrices.j2k_to_orf_rm(pX, pY, pZ, Vx, Vy, Vz)

Given 6 floats of the J2K/ICRF position and velocity data, Returns a 3x3 rotation matrix describing the rotation of J2K-> ORF.

Uses the transpose of rNadir_to_J2K.

Ref: Canuto, E., Novara, C., Carlucci, D., Montenegro, C. P., & Massotti, L. (2018). Orbital Control and Prediction Problems. In Spacecraft Dynamics and Control: The Embedded Model Control Approach. Butterworth-Heinemann.

Parameters

pXnumpy.ndarray[float]

X position in GEIJ2K (km).

pYnumpy.ndarray[float]

Y position in GEIJ2K (km).

pZnumpy.ndarray[float]

Z position in GEIJ2K (km).

Vxnumpy.ndarray[float]

X component of velocity in GEIJ2K (km/s).

VyTnumpy.ndarray[float]

Y component of velocity in GEIJ2K (km/s).

Vznumpy.ndarray[float]

Z component of velocity in GEIJ2K (km/s).

Returns

rJ2K_to_Nadirnp.ndarray[float]

rotation matrice for the transformation from GEIJ2K to ORF.

use_rotation_matrices.nec2terrestrial(inst_NEC, gX, gY, gZ)

Function to transform instrument look direction from NEC to terrestrial frame. Uses the transpose of ITRF to NEC rotation matrix.

Parameters

inst_NECnumpy.ndarray[float]

Instrument look direction in NEC.

gXnumpy.ndarray[float]

X position in GEO/ITRF (km).

gYnumpy.ndarray[float]

Y position in GEO/ITRF (km).

gZnumpy.ndarray[float]

Z position in GEO/ITRF (km).

Returns

inst_ternumpy.ndarray[float]

Instrument look direction in ITRF.

Examples

inst_ITRF = nec2itrf(inst_NEC, GEOx, GEOy, GEOz)

use_rotation_matrices.nec_to_terrestrial_rm(gX, gY, gZ)

Function to calculate NEC to ITRF rotation matrix.

Uses the transpose of ITRF to NEC rotation matrix.

Parameters

gXnumpy.ndarray[float]

X position in GEO/ITRF (km)

gYnumpy.ndarray[float]

Y position in GEO/ITRF (km)

gZnumpy.ndarray[float]

Z position in GEO/ITRF (km)

Returns

rm_nec2ternumpy.ndarray[float]

3d rotation matrix describing the rotation from NEC to ITRF.

Examples

r_nec2ter = nec_to_terrestrial_rm(GEOx, GEOy, GEOz)

use_rotation_matrices.ned2enu(inst_NED)

Function for NED to ENU transformations

The transformation matrice from NED to ENU and ENU to NED are the same. [0 1 0 ; 1 0 0 , 0 0 -1] in ENU, z increases in upward direction.

Ref: Grewal, M. S., Weill, L. R., & Andrews, A. P. (2008). Appendix C: Coordinate Transformations. In Global Positioning Systems, Inertial Navigation, and Integration (pp. 456–501). John Wiley & Sons, Inc. https://doi.org/10.1002/9780470099728.app3

Parameters

inst_NEDnp.ndarray[float]

instrument look direction in NED.

Returns

inst_ENUnp.ndarray[float]

instrument look direction in ENU.

use_rotation_matrices.ned_to_terrestrial_rm(lat, lon)

Function to calculate NED to ECEF rotation matrix.

Uses the transpose of ECEF to NED rotation matrix.

Parameters

latnumpy.ndarray[float]

Geodetic latitude in degrees.

lonnumpy.ndarray[float]

Geodetic longitude in degrees.

Returns

rm_ned2ternumpy.ndarray[float]

Rotation matrix for transformations from NED to ECEF.

use_rotation_matrices.oe_to_gei_rm(raan, inc, ap)

Function to calculate the perifocal frame (OE) to GEI rotation matrix

To transform from OE to J2K using orbital elements: RZ_r2i(raan) @ RX_r2i(inc) @ RZ_r2i(ap)

Ref: Frame rotations and quaternions, Pedro A. Capó-Lugo, Peter M. Bainum, in Orbital Mechanics and Formation Flying, 2011

Parameters

incfloat

satellite inclination (in radians).

raanfloat

satellite right ascension of ascending node (in radians).

apfloat

satellite argument of periapsis (in radians).

Returns

rm_OE2GEInumpy.ndarray[float]

ORF to GEI matrix using orbital elements.

Examples

R = oe_to_gei(sat_raan, sat_inc, sat_ap)

use_rotation_matrices.orf_to_j2k_rm(pX, pY, pZ, Vx, Vy, Vz)

Given 6 floats of the J2K/ICRF position and velocity data, Returns a 3x3 rotation matrix describing the rotation of ORF -> J2K.

Ref: Canuto, E., Novara, C., Carlucci, D., Montenegro, C. P., & Massotti, L. (2018). Orbital Control and Prediction Problems. In Spacecraft Dynamics and Control: The Embedded Model Control Approach. Butterworth-Heinemann.

Parameters

pXnumpy.ndarray[float]

X position in GEIJ2K (km).

pYnumpy.ndarray[float]

Y position in GEIJ2K (km).

pZnumpy.ndarray[float]

Z position in GEIJ2K (km).

Vxnumpy.ndarray[float]

X component of velocity in GEIJ2K (km/s).

VyTnumpy.ndarray[float]

Y component of velocity in GEIJ2K (km/s).

Vznumpy.ndarray[float]

Z component of velocity in GEIJ2K (km/s).

Returns

rNadir_to_J2Knp.ndarray[float]

rotation matrice for the transformation from ORF to GEIJ2K

use_rotation_matrices.orf_to_j2k_use_orbital_elements(body_vec, pX, pY, pZ, Vx, Vy, Vz, P=array([[0, 0, -1], [1, 0, 0], [0, -1, 0]]))

Employs orbital elements to transform from ORF to GEIJ2K:

To align the perifocal frame with the orbital frame RZ_r2i(TA) @ P @ body_vec

Ref:Canuto, E., Novara, C., Carlucci, D., Montenegro, C. P., & Massotti, L. (2018). Orbital Control and Prediction Problems. In Spacecraft Dynamics and Control: The Embedded Model Control Approach. Butterworth-Heinemann

Parameters

body_vecnp.ndarray[float]

rotated body frame vector.

pXnumpy.ndarray[float]

X position in GEIJ2K (km).

pYnumpy.ndarray[float]

Y position in GEIJ2K (km).

pZnumpy.ndarray[float]

Z position in GEIJ2K (km).

Vxnumpy.ndarray[float]

X component of velocity in GEIJ2K (km/s).

Vynumpy.ndarray[float]

Y component of velocity in GEIJ2K (km/s).

Vznumpy.ndarray[float]

Z component of velocity in GEIJ2K (km/s).

Pnumpy.ndarray

optional reordering matrix to align the perifocal frame with the

orbital frame.The default is P= np.array([[0, 0, -1],[1, 0, 0],[0,-1,0]])

Returns

inst_GEInumpy.ndarray[float]

instrument look direction in GEIJ2K.

Examples

inst_GEI =

orf_to_j2k_use_orbital_elements(body_vec, pX, pY, pZ, Vx, Vy, Vz)

use_rotation_matrices.orf_to_j2k_use_spacecraft_ephemeris(body_vec, pX, pY, pZ, Vx, Vy, Vz)

Employs spacecraft ephemeris to transform from ORF to GEIJ2K:

Parameters

body_vecnp.ndarray[float]

rotated body frame vector.

pXnumpy.ndarray[float]

X position in GEIJ2K (km).

pYnumpy.ndarray[float]

Y position in GEIJ2K (km).

pZnumpy.ndarray[float]

Z position in GEIJ2K (km).

Vxnumpy.ndarray[float]

X component of velocity in GEIJ2K (km/s).

Vynumpy.ndarray[float]

Y component of velocity in GEIJ2K (km/s).

Vznumpy.ndarray[float]

Z component of velocity in GEIJ2K (km/s).

Pnumpy.ndarray

optional reordering matrix to align the perifocal frame with the

orbital frame. Default is P= np.array([[0, 0, -1],[1, 0, 0],[0,-1,0]])

Returns

inst_GEInumpy.ndarray[float]

instrument look direction in GEIJ2K.

Examples

inst_GEI =

orf_to_j2k_use_spacecraft_ephemeris(body_vec, pX, pY, pZ, Vx, Vy, Vz)

use_rotation_matrices.terrestrial2nec(inst_ter, gX, gY, gZ)

Function to transform instrument look direction from terrestrial frame to NEC. Uses (Nielsen, 2019) method.

Parameters

inst_ternumpy.ndarray[float]

Instrument look direction in terrestrial frame.

gXnumpy.ndarray[float]

X position in GEO/ITRF (km).

gYnumpy.ndarray[float]

Y position in GEO/ITRF (km).

gZnumpy.ndarray[float]

Z position in GEO/ITRF (km).

Returns

inst_NECnumpy.ndarray[float]

instrument look direction in NEC.

Examples

inst_NEC = itrf2nec(inst_ITRF, GEOx, GEOy, GEOz)

use_rotation_matrices.terrestrial2ned(inst_ter, lat, lon)

function for transformations from ECEF to NED (z is positive downwards)

Parameters

inst_ternp.ndarray[float]

instrument look direction in terrestrial frame.

latnumpy.ndarray[float]

Geodetic latitude in degrees.

lonnumpy.ndarray[float]

Geodetic longitude in degrees.

Returns

inst_NEDnp.ndarray[float]

instrument look direction in NED.

Examples

inst_NED = terrestrial2ned(inst_ter, lat, lon)

use_rotation_matrices.terrestrial_to_nec_rm(gX, gY, gZ)

Given the Geographic Cartesian Position ephemeris data return a 3d rotation matrix describing the rotation from ITRF to NEC

Ref: https://earth.esa.int/documents/10174/1514862/Swarm_Level-1b_Processor_Algorithms Page 137, “C.3 North East Center (NEC)

Parameters

gXnumpy.ndarray[float]

X position in GEO/ITRF (km).

gYnumpy.ndarray[float]

Y position in GEO/ITRF (km).

gZnumpy.ndarray[float]

Z position in GEO/ITRF (km).

Returns

R_NECnumpy.ndarray[float]

3d rotation matrix describing the rotation from ITRF to NEC.

Examples

rter2nec = terrestrial_to_nec_rm(GEOx, GEOy, GEOz)

use_rotation_matrices.terrestrial_to_ned_rm(lat, lon)

Function to calculate the ECEF to NED rotation matrix.

Y-Z (pitch-yaw) sequence with longitude and latitude are needed.

  1. Aligning the x-y plane of ECEF and NED using longitude: yaw(longitude)

  2. Aligning the x-z plane using latitude: pitch(-(pi/2+latitude))

Ref: 1. J. Riggs, Coordinate transformations via Euler Angle Rotations, Rev. E - 10 April 2019

2. Cai, G., Chen, B.M., Lee, T.H. (2011). Coordinate Systems and Transformations. In: Unmanned Rotorcraft Systems. Advances in Industrial Control. Springer, London. https://doi.org/10.1007/978-0-85729-635-1_2

Parameters

latnumpy.ndarray[float]

Geodetic latitude in degrees.

lonnumpy.ndarray[float]

Geodetic longitude in degrees.

Returns

rm_ter2nednumpy.ndarray[float]

Rotation matrix for transformations from ECEF to NED.