Documentation Index
Fetch the complete documentation index at: https://docs.valar.space/llms.txt
Use this file to discover all available pages before exploring further.
For the complete documentation index, see llms.txt.The Attitude Ephemeris Message (AEM) is a standardized ASCII text format for exchanging spacecraft attitude data over time. AEM is the attitude-data sibling of OEM: where OEM carries time-ordered position and velocity, AEM carries time-ordered orientation samples (quaternions or Euler angles) so receiving systems can reconstruct how a spacecraft was pointed throughout an interval.
Key Components
An AEM file contains several distinct sections:- Header: File-level metadata including format version, creation date, and originator information
- Metadata: Attitude context information such as object identification, the two reference frames involved, time system, attitude representation, and time bounds
- Attitude Data: Time-ordered attitude samples (typically quaternions) at specific epochs, optionally including angular rates
Critical Fields
Metadata Section
- OBJECT_NAME / OBJECT_ID: Spacecraft identification
- REF_FRAME_A: First reference frame in the rotation (typically the inertial frame, e.g., EME2000)
- REF_FRAME_B: Second reference frame in the rotation (typically the spacecraft body frame, e.g., SC_BODY_1)
- ATTITUDE_DIR: Direction of the rotation, either
A2B(inertial-to-body) orB2A(body-to-inertial) - TIME_SYSTEM: Time system used for all epochs in the file (e.g., UTC, TAI)
- START_TIME / STOP_TIME: Temporal bounds of the attitude ephemeris
- USEABLE_START_TIME / USEABLE_STOP_TIME: Subset of the bounds within which interpolation is valid
- ATTITUDE_TYPE: Attitude representation in the data block (e.g.,
QUATERNION,QUATERNION/DERIVATIVE,QUATERNION/RATE,EULER_ANGLE) - INTERPOLATION: Method for interpolating attitude between samples (e.g., Lagrange, Hermite)
- INTERPOLATION_DEGREE: Polynomial degree for interpolation
Attitude Data Format
Each line contains an epoch followed by the attitude sample. For quaternion data, the line layout is:Epoch Q1 Q2 Q3 QC
Where QC is the scalar (real) component and Q1, Q2, Q3 are the vector components. When angular rates accompany the quaternion (QUATERNION/RATE or QUATERNION/DERIVATIVE), three additional values are appended per line.
Attitude Representations
AEM supports several attitude representations selected via theATTITUDE_TYPE field. VALAR accepts the quaternion family on import: QUATERNION, QUATERNION/DERIVATIVE, QUATERNION/RATE, and QUATERNION/ANGVEL.
Quaternion Component Order
A quaternion has four components: a scalar (real) part and a three-element vector part. Two ordering conventions exist in the wild:- Scalar-first:
QC, Q1, Q2, Q3— the scalar is the first value on each data line - Scalar-last:
Q1, Q2, Q3, QC— the scalar is the last value on each data line
QUATERNION_TYPE = FIRST or LAST) is not used in v2 files: v2 always orders components scalar-last, and VALAR’s exporter emits v2 only.
When importing a third-party AEM file, confirm the producing system uses scalar-last ordering. A scalar-first file parsed as scalar-last will yield rotations that are silently wrong rather than producing a parse error.
Euler Angle Sequences
WhenATTITUDE_TYPE = EULER_ANGLE, the data lines contain three rotation angles instead of four quaternion components. The metadata field EULER_ROT_SEQ declares which axis sequence the angles follow. Common sequences include:
- 3-1-3: rotate about Z, then X, then Z again — the classical Euler sequence used for many astrodynamics applications (e.g., right ascension, inclination, argument of latitude)
- 3-2-1: rotate about Z, then Y, then X — the aircraft-style yaw-pitch-roll convention
(Φ, Θ, Ψ) describes a rotation by Φ around Z, then Θ around the new X-axis, then Ψ around the resulting Z-axis. The rotation order is non-commutative — applying the same three numbers under a different sequence will produce a different orientation.
Reference Frame Conventions
AEM expresses attitude as a rotation between two named frames, REF_FRAME_A and REF_FRAME_B, with the direction declared byATTITUDE_DIR (A2B or B2A).
- REF_FRAME_A is typically the inertial reference frame the attitude is measured against. Common values include
EME2000(Earth Mean Equator and Equinox of J2000),GCRF(Geocentric Celestial Reference Frame), andICRF(International Celestial Reference Frame). - REF_FRAME_B is typically the spacecraft body frame. Body frames are named by mission convention; CCSDS allows local labels such as
SC_BODY_1,INSTRUMENT, or any frame defined elsewhere in the metadata.
ATTITUDE_DIR = A2B means the quaternion rotates a vector expressed in REF_FRAME_A into REF_FRAME_B (inertial-to-body). The opposite direction (B2A) expresses the conjugate rotation. Always cross-check both fields together — flipping either one alone inverts the meaning of every sample in the file.
Time System Conventions
TheTIME_SYSTEM field declares the time scale that every epoch in the metadata and data sections is expressed in. AEM accepts several time scales; the most commonly seen are:
- UTC: Coordinated Universal Time. Subject to leap seconds.
- TAI: International Atomic Time. Continuous, no leap seconds.
- GPS: GPS time. Continuous, offset from TAI by a fixed 19 seconds.
- TDB: Barycentric Dynamical Time. Used in deep-space and planetary applications.
Complete definition of the AEM standard on CCSDS 504.0-B-2 guidelines.
Sample AEM File
Here is a sample AEM file in KVN format with quaternion attitude data:Common Use Cases
- Importing externally-computed attitudes: Load attitude profiles produced by an external GNC tool, attitude-determination pipeline, or partner mission control system into VALAR for downstream analysis and visualisation.
- Exporting VALAR-computed attitudes: Hand off an attitude profile generated in VALAR to ground-segment tools, payload planners, or contractors that consume CCSDS-standard inputs.
- Mission coordination: Exchange the planned or reconstructed attitude history between organisations (operator, payload provider, ground stations) using a vendor-neutral interchange format.
- Cross-checking attitude solutions: Compare attitude profiles from different sources by importing each as a separate AEM and inspecting the resulting orientation timelines side by side.