use_rotation_matrices: Module to rotate instrument and transform between reference frames
use_rotation_matrices contains functions to
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
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.
Aligning the x-y plane of ECEF and NED using longitude: yaw(longitude)
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.