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.
CCSDS 504.0-B-2 Conformance
VALAR reads and writes AEM at CCSDS 504.0-B-2 — every file the exporter produces carriesCCSDS_AEM_VERS = 2.0. Two keywords that older B-1 files used to carry, ATTITUDE_DIR and QUATERNION_TYPE, are no longer emitted under B-2, because the standard now fixes the conventions they used to declare:
- Rotation direction is implicit in the
REF_FRAME_A→REF_FRAME_Bordering — every sample rotates a vector fromREF_FRAME_AintoREF_FRAME_B, so a separateATTITUDE_DIRkeyword is redundant. - Quaternion component order is mandated scalar-last (
Q1 Q2 Q3 QC) by B-2, so theQUATERNION_TYPEindicator is redundant.
ATTITUDE_DIR or QUATERNION_TYPE to be present.
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 (quaternions or Euler angles) 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 — the frame attitude is measured from (typically the inertial frame, e.g., EME2000)
- REF_FRAME_B: Second reference frame in the rotation — the frame attitude is measured to (typically the spacecraft body frame, e.g., SC_BODY_1)
- 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) - EULER_ROT_SEQ: For
EULER_ANGLEdata, the rotation-axis sequence the angles follow (e.g.,ZYX) - 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. On export, VALAR writes QUATERNION, EULER_ANGLE, or both.
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 indicator.
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, each data line carries three rotation angles — roll, pitch, yaw — instead of four quaternion components, and the metadata field EULER_ROT_SEQ declares which axis sequence the angles follow. VALAR writes the sequence in letter form, and the exporter offers three:
EULER_ROT_SEQ | Rotation order | Notes |
|---|---|---|
| ZYX (default) | Z, then Y, then X | Yaw-pitch-roll — the default export sequence |
| XYZ | X, then Y, then Z | Roll-pitch-yaw axis order |
| ZXY | Z, then X, then Y |
EULER_ROT_SEQ before interpreting the angles. Euler angles are also undefined at gimbal lock (pitch at ±90°); when the chosen sequence is singular over the requested window, VALAR refuses the export rather than writing ambiguous angles. See Exporting Attitude Ephemeris for the export-side behaviour.
Reference Frame Conventions
AEM expresses attitude as a rotation between two named frames, REF_FRAME_A and REF_FRAME_B. Under CCSDS 504.0-B-2 the direction is implicit in the ordering: every sample rotates a vector fromREF_FRAME_A into REF_FRAME_B.
- REF_FRAME_A is the frame the attitude is measured from — typically an inertial reference frame. VALAR exports offer
EME2000(Earth Mean Equator and Equinox of J2000),ITRF2014, andLVLH_ROTATING(the local orbital frame). CCSDS-standard inertial labels such asGCRFandICRFmay also appear in imported files. - REF_FRAME_B is the frame the attitude is measured to — 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.
REF_FRAME_A → REF_FRAME_B ordering, there is no separate direction keyword to cross-check — reversing the two frames inverts the meaning of every sample in the file.
LVLH Files and the Companion OEM
WhenREF_FRAME_A is LVLH_ROTATING, the attitude is expressed against the spacecraft’s Local-Vertical/Local-Horizontal frame, which is defined by the orbit itself. Such a file is not self-contained — it cannot be interpreted without the matching orbit ephemeris. VALAR therefore writes two COMMENT lines into the segment metadata pointing at the companion OEM:
_, and each timestamp has its colons and dots replaced with - (so 2026-06-01T00:00:00Z becomes 2026-06-01T00-00-00Z); the reference epoch is the segment’s start instant. Fetch the named OEM and use its reference epoch to reconstruct the LVLH frame before consuming the attitude samples.
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:Euler-Angle and Two-Segment Files
When the export includes the Euler angles representation, the segment setsATTITUDE_TYPE = EULER_ANGLE and adds EULER_ROT_SEQ (for example, ZYX) to its metadata; each data line then carries three angles — roll, pitch, yaw — in place of the four quaternion components.
Selecting both representations writes a single AEM with two segments — the QUATERNION segment first, then the EULER_ANGLE segment — each with its own metadata block and reference frame:
REF_FRAME_A, so a combined file can, for example, carry the quaternion segment in EME2000 and the Euler-angle segment in LVLH_ROTATING.
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.