> ## 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. # AEM (Attitude Ephemeris Message) > Working with CCSDS Attitude Ephemeris Message format in VALAR > For the complete documentation index, see [llms.txt](/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](/file-formats/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 carries `CCSDS_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_B` ordering — every sample rotates a vector from `REF_FRAME_A` into `REF_FRAME_B`, so a separate `ATTITUDE_DIR` keyword is redundant. * **Quaternion component order** is mandated **scalar-last** (`Q1 Q2 Q3 QC`) by B-2, so the `QUATERNION_TYPE` indicator is redundant. If you consume a VALAR-exported AEM, read the rotation direction from the frame ordering and assume scalar-last quaternions — do not expect `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_ANGLE` data, 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 the `ATTITUDE_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 CCSDS 504.0-B-2 mandates **scalar-last** ordering, and VALAR reads and writes scalar-last quaternions. Because the order is fixed by the standard, B-2 files do not carry the legacy `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 When `ATTITUDE_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 | | The rotation order is non-commutative — applying the same three angles under a different sequence produces a different orientation, so a consumer must read `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](/features/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 from `REF_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`, and `LVLH_ROTATING` (the local orbital frame). CCSDS-standard inertial labels such as `GCRF` and `ICRF` may 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. Because direction follows the `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 When `REF_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](/file-formats/oem): ``` COMMENT Companion OEM filename: _orbit-ephemeris__.txt COMMENT Companion OEM reference epoch: ``` The spacecraft name has every non-alphanumeric character replaced with `_`, 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 The `TIME_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. All times in VALAR are stored and displayed in UTC; an AEM file using a different time system is converted to UTC on import. Complete definition of the AEM standard on [CCSDS 504.0-B-2](https://ccsds.org/Pubs/504x0b2.pdf) guidelines. ## Sample AEM File Here is a sample AEM file in KVN format with quaternion attitude data: ``` CCSDS_AEM_VERS = 2.0 CREATION_DATE = 2024-06-15T08:30:00.000 ORIGINATOR = VALAR META_START OBJECT_NAME = SPACECRAFT-1 OBJECT_ID = 2023-001A CENTER_NAME = EARTH REF_FRAME_A = EME2000 REF_FRAME_B = SC_BODY_1 TIME_SYSTEM = UTC START_TIME = 2024-06-15T00:00:00.000 STOP_TIME = 2024-06-15T00:05:00.000 USEABLE_START_TIME = 2024-06-15T00:00:00.000 USEABLE_STOP_TIME = 2024-06-15T00:05:00.000 ATTITUDE_TYPE = QUATERNION INTERPOLATION = LAGRANGE INTERPOLATION_DEGREE = 7 META_STOP COMMENT Attitude rotates EME2000 (REF_FRAME_A) into SC_BODY_1 (REF_FRAME_B) COMMENT Quaternion components ordered scalar-last (Q1, Q2, Q3, QC) DATA_START 2024-06-15T00:00:00.000 0.0000000 0.0000000 0.0000000 1.0000000 2024-06-15T00:01:00.000 0.0004999 0.0000000 0.0000000 0.9999999 2024-06-15T00:02:00.000 0.0009999 0.0000000 0.0000000 0.9999995 2024-06-15T00:03:00.000 0.0014999 0.0000000 0.0000000 0.9999989 2024-06-15T00:04:00.000 0.0019998 0.0000000 0.0000000 0.9999980 2024-06-15T00:05:00.000 0.0024998 0.0000000 0.0000000 0.9999969 DATA_STOP ``` ## Euler-Angle and Two-Segment Files When the export includes the **Euler angles** representation, the segment sets `ATTITUDE_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: ``` CCSDS_AEM_VERS = 2.0 CREATION_DATE = 2024-06-15T08:30:00.000 ORIGINATOR = VALAR META_START OBJECT_NAME = SPACECRAFT-1 REF_FRAME_A = EME2000 REF_FRAME_B = SC_BODY_1 ATTITUDE_TYPE = QUATERNION META_STOP DATA_START 2024-06-15T00:00:00.000 0.0000000 0.0000000 0.0000000 1.0000000 DATA_STOP META_START OBJECT_NAME = SPACECRAFT-1 REF_FRAME_A = EME2000 REF_FRAME_B = SC_BODY_1 ATTITUDE_TYPE = EULER_ANGLE EULER_ROT_SEQ = ZYX META_STOP DATA_START 2024-06-15T00:00:00.000 0.0000000 0.0000000 0.0000000 DATA_STOP ``` Each segment declares its own `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. ## Using AEM in VALAR AEM files are imported and exported through the spacecraft attitude ephemeris workflow. See [Attitude Ephemeris](/features/attitude/ephemeris) for the full operational reference, including the import dialog, validation messages surfaced when a file is rejected, the export dialog, and recovery steps for imports that left the spacecraft in a broken state.