TLE2nadir

A VTS Timeloop Generator plugin that generates nadir-pointing quaternions for a satellite over a specified time period. It can process orbital data from Two-Line Element (TLE) sets or from CCSDS Orbit Ephemeris Message (OEM) position files.

Features

This plugin supports two primary methods for inputting satellite orbital data:

1. TLE (Two-Line Element) Input:

   • Manual TLE: Users can directly provide the TLE (two lines of text) for the satellite.
   • Automatic Download via NORAD ID: Users can input the satellite's NORAD Catalog ID. The plugin can then fetch the latest TLE data from CelesTrak.

2. CCSDS OEM (Orbit Ephemeris Message) File Input:

   • Users can provide a CCSDS OEM file containing satellite state vectors (position and optionally velocity).
   • These files are often generated by other VTS Timeloop generator plugins or external orbit determination tools.

How it Works: Quaternion Generation

The core functionality is to determine the satellite's orientation (attitude) such that one of its axes always points towards the Earth's center (nadir). This orientation is expressed as a quaternion. The process involves these steps for each time point:

1. Satellite State Vector:

   • For TLE input, the satellite's position (r_sat) and velocity (v_sat) vectors in the EME2000 inertial frame are calculated at the desired epoch using an SGP4/SDP4 propagator.
   • For OEM input, the position (r_sat) and velocity (v_sat) vectors are read directly from the file for the corresponding epoch.

2. Defining the Satellite Body Frame: A right-handed coordinate system is defined for the satellite body:

   • Z-axis (Body): Points directly towards the Earth's center (nadir). This is calculated as the negative of the normalized satellite position vector (-r_sat / ||r_sat||).
   • X-axis (Body):
     • Primarily, it aligns with the satellite's velocity vector projected onto the plane perpendicular to the body Z-axis. This helps orient the satellite "forward" along its direction of motion.
     • If the velocity vector is unusable (e.g., zero, purely radial, or not provided in the OEM file), a conventional X-axis is chosen. This typically involves using the EME2000 inertial Z-axis (celestial North) to form a basis, ensuring a consistent orientation. For instance, if the body Z-axis is aligned with the inertial Z-axis (satellite over a pole), the body X-axis might be aligned with the inertial X-axis (towards the Vernal Equinox).
   • Y-axis (Body): Completes the right-handed system, calculated as the cross product of the body Z-axis and body X-axis (Y_body = Z_body x X_body).

3. Rotation Matrix Construction: A 3x3 rotation matrix (R) is constructed. This matrix represents the transformation from the EME2000 inertial reference frame to the satellite's nadir-pointing body frame. The columns of this matrix are the normalized body X, Y, and Z axes expressed in the EME2000 frame.

4. Quaternion Conversion: The rotation matrix R is converted into a quaternion [qw, qx, qy, qz] (scalar component qw first). This conversion uses Sheppard's method.

The resulting quaternion defines the orientation of the satellite's body frame relative to the EME2000 inertial frame at each specified time step.

Output Format

The generated attitude data is written to a CCSDS Attitude Ephemeris Message (AEM) file. Key characteristics of the output file include:

• Format: CIC_AEM_VERS = 1.0
• Metadata: Includes OBJECT_NAME, OBJECT_ID, CREATION_DATE, ORIGINATOR.
• Reference Frames: REF_FRAME_A = EME2000, REF_FRAME_B = UNDEFINED (as the body frame is specific to the satellite's nadir pointing).
• Attitude Direction: ATTITUDE_DIR = A2B (from EME2000 to the satellite body frame).
• Time System: TIME_SYSTEM = UTC.
• Attitude Type: ATTITUDE_TYPE = QUATERNION.
• Data Lines: Each data line contains: MJD_days MJD_seconds_of_day q_scalar q_x q_y q_z (Modified Julian Date day, MJD seconds of the day, and the four quaternion components).

Dependencies

Python 3.6 or newer is required.

The core application relies on the following Python packages:

• numpy
• skyfield
• argparse
• requests

The graphical user interface (GUI) also uses tkinter, which is typically included with standard Python installations.

You can install the required packages using pip:

pip install -r bin/requirements.txt

Installation instructions

1. Clone/move repository into the Generators folder in the VTS Timeloop install directory.
2. Use the generator under Satellite > Position/Orientation > Orientation > File > Generators

Screenshots