use_rotation_matrices: Module to rotate instrument and transform between reference frames — cavsiopy 1.1.0 documentation

# 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.

  utc_dt: datetime.datetime

    time in UTC.

  GMST: float

    GMST in radians.

  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.

  time_arraydatetime.datetime

    time in UTC.

  GMST: float

    GMST in radians.

  GMST = calculate_GMST_noon(time_array)

use_rotation_matrices.RX_i2r(x)
  xfloat

    roll angle (radians).

  numpy.ndarray

    Rotation matrix about x axis.

  Rx = RX_i2r(roll)

use_rotation_matrices.RX_r2i(x)
  xfloat

    roll angle (radians).

  numpy.ndarray

    Rotation matrix about x axis.

  Rx = RX_r2i(roll)

use_rotation_matrices.RY_i2r(y)
  yfloat

    pitch angle (radians).

  numpy.ndarray

    Rotation matrix about y axis.

  Ry = RY_i2r(pitch)

use_rotation_matrices.RY_r2i(y)
  yfloat

    pitch angle (radians).

  numpy.ndarray

    Rotation matrix about y axis.

  Ry = RY_r2i(pitch)

use_rotation_matrices.RZ_i2r(z)
  zfloat

    yaw angle (radians).

  numpy.ndarray

    Rotation matrix about z axis.

  Rz = RZ_i2r(yaw)

use_rotation_matrices.RZ_r2i(z)
  zfloat

    yaw angle (radians).

  numpy.ndarray

    Rotation matrix about z axis.

  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.

  theta_radfloat

    GMST_midnight.

  GEI2ECEFnumpy.ndarray[float]

    Rotation matrix for transformations from GEI to ECEF.

  R = ecef_to_gei_rm(theta_rad)

use_rotation_matrices.gei2ecef(inst_GEI, time_array)

  function for GEIJ2K to ECEF transformations

  inst_GEInp.ndarray[float]

    instrument look direction in GEIJ2K .

  time_arraydatetime.datetime

    experiment time interval.

  inst_ECEFnp.ndarray[float]

    instrument look direction in GEIJ2K.

  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

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

  theta_radfloat

    GMST_midnight.

  rm_GEI2ECEFnumpy.ndarray[float]

    Rotation matrix for transformations from GEI to ECEF.

  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.

  incfloat

    satellite inclination (in radians).

  raanfloat

    satellite right ascension of ascending node (in radians).

  apfloat

    satellite argument of periapsis (in radians).

  rm_GEI2OEnumpy.ndarray[float]

    orbital frame to GEI matrix using satellite orbital elements.

  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.

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

  inst_GEInumpy.ndarray[float]

    instrument look direction in GEIJ2K.

  path_to_filesstr

    IES and EOP file path.

  time_arraydatetime.datetime

    time array.

  inst_ITRFnumpy.ndarray[float]

    instrument look direction in ITRF.

  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.

  path_to_filesstr

    path_to_initialization files (IERS and EOP).

  input_timedatetime.datetime

    time.

  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.

  path_to_filesstr

    path_to_initialization files (IERS and EOP).

  time_arraydatetime.datetime

    time array.

  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.

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

  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.

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

  inst_ternumpy.ndarray[float]

    Instrument look direction in ITRF.

  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.

  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)

  rm_nec2ternumpy.ndarray[float]

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

  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

  inst_NEDnp.ndarray[float]

    instrument look direction in NED.

  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.

  latnumpy.ndarray[float]

    Geodetic latitude in degrees.

  lonnumpy.ndarray[float]

    Geodetic longitude in degrees.

  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

  incfloat

    satellite inclination (in radians).

  raanfloat

    satellite right ascension of ascending node (in radians).

  apfloat

    satellite argument of periapsis (in radians).

  rm_OE2GEInumpy.ndarray[float]

    ORF to GEI matrix using orbital elements.

  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.

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

  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

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

  inst_GEInumpy.ndarray[float]

    instrument look direction in GEIJ2K.

  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:

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

  inst_GEInumpy.ndarray[float]

    instrument look direction in GEIJ2K.

  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.

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

  inst_NECnumpy.ndarray[float]

    instrument look direction in NEC.

  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)

  inst_ternp.ndarray[float]

    instrument look direction in terrestrial frame.

  latnumpy.ndarray[float]

    Geodetic latitude in degrees.

  lonnumpy.ndarray[float]

    Geodetic longitude in degrees.

  inst_NEDnp.ndarray[float]

    instrument look direction in NED.

  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)

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

  R_NECnumpy.ndarray[float]

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

  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

  latnumpy.ndarray[float]

    Geodetic latitude in degrees.

  lonnumpy.ndarray[float]

    Geodetic longitude in degrees.

  rm_ter2nednumpy.ndarray[float]

    Rotation matrix for transformations from ECEF to NED.