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

# File Formats Overview

> Overview of supported file formats for spacecraft data in VALAR

> For the complete documentation index, see [llms.txt](/llms.txt).

VALAR supports industry-standard file formats for importing and exporting spacecraft orbital data, tracking observations, maneuver plans, and conjunction information. Most formats follow **CCSDS (Consultative Committee for Space Data Systems)** standards, ensuring interoperability with other space agencies, operators, and mission control systems worldwide.

## Supported File Formats

VALAR supports eight primary file formats, each designed for specific operational needs:

| Format                       | Full Name                   | Primary Use            | Data Type                   | Standard          |
| ---------------------------- | --------------------------- | ---------------------- | --------------------------- | ----------------- |
| [**OPM**](/file-formats/opm) | Orbit Parameter Message     | State vector snapshots | Single-epoch orbital state  | CCSDS 502.0-B-3   |
| [**OMM**](/file-formats/omm) | Orbit Mean-elements Message | Mean orbital elements  | Single-epoch mean state     | CCSDS 502.0-B-3   |
| [**OEM**](/file-formats/oem) | Orbit Ephemeris Message     | Trajectory time series | Position/velocity over time | CCSDS 502.0-B-3   |
| [**OCM**](/file-formats/ocm) | Orbit Comprehensive Message | Mission planning       | Comprehensive orbital data  | CCSDS 502.0-B-3   |
| [**TDM**](/file-formats/tdm) | Tracking Data Message       | Orbit determination    | Ground-based observations   | CCSDS 503.0-B-2   |
| [**CDM**](/file-formats/cdm) | Conjunction Data Message    | Collision assessment   | Conjunction event data      | CCSDS 508.0-B-1   |
| [**TLE**](/file-formats/tle) | Two-Line Element            | Catalog data           | Mean orbital elements       | NORAD/Space-Track |
| [**SP3**](/file-formats/sp3) | Standard Product 3          | Precise GNSS orbits    | Multi-satellite ephemeris   | IGS SP3-c         |

## Format Categories

### Orbital State Formats

These formats describe spacecraft position and velocity:

* **OPM**: Single orbital state at a specific epoch, optionally with spacecraft properties
* **OMM**: Mean Keplerian elements at a single epoch, derived from osculating state via DSST
* **OEM**: Time series of orbital states with interpolation support for continuous trajectories
* **OCM**: Comprehensive format combining state history, maneuvers, physical properties, and force models
* **SP3**: Multi-satellite ephemeris with integrated clock corrections, primarily used for GNSS precise orbits

### Observation Formats

These formats contain raw or processed measurement data from ground sensors:

* **TDM**: Tracking observations (angles, range, range-rate) from ground stations or optical telescopes

### Specialized Formats

* **CDM**: Conjunction analysis results with collision probability and miss distance
* **TLE**: Public catalog format using simplified perturbation models (SGP4/SDP4)

## Quick Format Selection Guide

### I want to...

**Share a spacecraft state vector** → Use [**OPM**](/file-formats/opm) for a single-epoch snapshot

**Export mean orbital elements** → Use [**OMM**](/file-formats/omm) for TLE-equivalent mean element representation

**Provide a pre-computed trajectory** → Use [**OEM**](/file-formats/oem) for a time series of state vectors

**Import/export maneuver plans** → Use [**OCM**](/file-formats/ocm) for comprehensive maneuver sequences

**Upload measurements for orbit determination** → Use [**TDM**](/file-formats/tdm) for observation data from ground sensors

**Analyze conjunction events** → Use [**CDM**](/file-formats/cdm) for collision assessment information

**Work with public catalog data** → Use [**TLE**](/file-formats/tle) format (note: VALAR does not import TLEs directly)

**Import precise GNSS or LEO satellite orbits** → Use [**SP3**](/file-formats/sp3) for IGS or similar precise orbit products

## Format Comparison

### Temporal Scope

| Format | Time Coverage                | Typical Use                              |
| ------ | ---------------------------- | ---------------------------------------- |
| OPM    | Single epoch                 | State snapshots, OD results              |
| OMM    | Single epoch (mean elements) | Catalog exchange, conjunction screening  |
| OEM    | Time series                  | Ephemeris generation, trajectory sharing |
| OCM    | Single or multiple epochs    | Mission planning, comprehensive state    |
| TDM    | Observation period           | Tracking passes, sensor data             |
| CDM    | Event-specific               | Conjunction analysis                     |
| TLE    | Single epoch (mean elements) | Catalog distribution                     |
| SP3    | Time series                  | Precise GNSS orbits, PPP applications    |

### Data Complexity

| Format | Complexity | Required Information                          | Optional Information                                      |
| ------ | ---------- | --------------------------------------------- | --------------------------------------------------------- |
| OPM    | Low        | State vector, epoch, reference frame          | Keplerian elements, covariance                            |
| OMM    | Low        | Mean elements, epoch, mean element theory     | TLE parameters, covariance                                |
| OEM    | Medium     | State vectors, epochs, interpolation method   | Covariance time series                                    |
| OCM    | High       | Metadata, reference frame                     | Trajectory, maneuvers, physical properties, perturbations |
| TDM    | Medium     | Observations, participants, measurement types | Corrections, atmospheric data                             |
| CDM    | Medium     | TCA, miss distance, state vectors             | Covariance, collision probability                         |
| TLE    | Low        | Orbital elements, NORAD catalog number        | None                                                      |
| SP3    | Medium     | Satellite IDs, positions, epochs, time system | Velocities, clock corrections, correlations               |

### Common Use Cases by Mission Phase

| Mission Phase          | Recommended Format                | Alternative                |
| ---------------------- | --------------------------------- | -------------------------- |
| Pre-Launch Planning    | OCM (maneuver plans)              | OPM (state snapshots)      |
| Early Orbit            | TDM (tracking) → OPM (OD results) | OEM (trajectory)           |
| Station-Keeping        | OCM (maneuver sequences)          | OPM (state snapshots)      |
| Conjunction Assessment | CDM (from screening services)     | OEM (predicted trajectory) |
| End-of-Life            | OEM (decay trajectory)            | OPM (final state)          |
| Data Archiving         | OEM (historical trajectory)       | TDM (raw observations)     |

## Format Details

### OPM (Orbit Parameter Message)

**Purpose:** Exchange single-epoch orbital states with optional spacecraft parameters and a single maneuver.

**Key Features:**

* Cartesian state vectors or Keplerian elements
* Spacecraft physical properties (mass, area, coefficients)
* Optional covariance matrix

**Supported Variants:**

* **CCSDS OPM**: Standard format using inertial reference frames (EME2000, GCRF)
* **SpaceX OPM**: Proprietary format from Falcon second stage telemetry using ECEF coordinates

**When to Use:**

* Sharing orbit determination results
* Providing initial conditions for propagation
* Exchanging state vectors between systems
* Importing launch vehicle separation states (SpaceX OPM)

[Read OPM documentation →](/file-formats/opm)

### OMM (Orbit Mean-elements Message)

**Purpose:** Exchange mean Keplerian orbital elements at a single epoch, suitable for catalog distribution and TLE-equivalent data exchange.

**Key Features:**

* Mean Keplerian elements (averaged over short-period perturbations)
* Compatible with SGP4/SDP4 propagation parameters
* DSST-based osculating-to-mean element conversion
* Optional covariance matrix

**When to Use:**

* Exporting mean orbital state for catalog comparison
* Sharing TLE-equivalent data in structured CCSDS format
* Conjunction screening with stable mean elements
* Interoperability with mean-element-based workflows

[Read OMM documentation →](/file-formats/omm)

***

### OEM (Orbit Ephemeris Message)

**Purpose:** Share pre-computed spacecraft trajectories as time-ordered position and velocity data.

**Key Features:**

* Time series of Cartesian state vectors
* Interpolation methods (Hermite, Lagrange, Linear)
* Optional covariance matrices at each epoch
* Multiple data segments for different time periods

**When to Use:**

* Conjunction assessment coordination
* Trajectory sharing between control centers
* High-precision ephemeris distribution
* Orbit visualization and analysis

[Read OEM documentation →](/file-formats/oem)

***

### OCM (Orbit Comprehensive Message)

**Purpose:** Comprehensive mission planning format combining orbital states, maneuvers, spacecraft properties, and force model specifications.

**Key Features:**

* Multiple trajectory state blocks
* Multiple maneuver definitions (impulsive and continuous thrust)
* Maneuver sequencing (MAN\_PREV\_ID, MAN\_NEXT\_ID)
* Physical properties, covariance time history
* Perturbation parameters, user-defined data

**When to Use (in VALAR):**

* **Import maneuvers** from external sources
* **Export maneuver plans** for coordination with other agencies

<Info>
  VALAR uses OCM specifically for maneuver import/export. Other OCM sections (trajectory, physical properties, covariance) are not currently supported.
</Info>

[Read OCM documentation →](/file-formats/ocm)

***

### TDM (Tracking Data Message)

**Purpose:** Exchange ground-based tracking observations for orbit determination.

**Key Features:**

* Multiple measurement types (angles, range, range-rate (Doppler), frequency)
* Angle types: AZEL (radar), RADEC (optical), XEYN, XSYE
* Signal path specification (one-way, two-way)
* Multi-segment support for multiple tracking stations
* Metadata for corrections and biases

**When to Use:**

* Uploading measurements for orbit determination
* Sharing observation data from ground sensors
* Multi-station tracking campaigns
* Validating predicted trajectories against observations

<Warning>
  Sensor configuration in VALAR must match PARTICIPANT\_1 field in TDM metadata. Configure ground stations before importing TDM files.
</Warning>

[Read TDM documentation →](/file-formats/tdm)

***

### CDM (Conjunction Data Message)

**Purpose:** Exchange conjunction assessment results for collision risk evaluation.

**Key Features:**

* Time of Closest Approach (TCA)
* Miss distance and relative velocity
* Collision probability
* State vectors and covariances for both objects
* Screening volume information

**When to Use:**

* Receiving conjunction warnings from Space-Track or other screening services
* Coordinating collision avoidance maneuvers
* Analyzing conjunction geometry
* Risk assessment for operational spacecraft

[Read CDM documentation →](/file-formats/cdm)

***

### TLE (Two-Line Element)

**Purpose:** Compact format for distributing mean orbital elements from public satellite catalogs.

**Key Features:**

* Fixed 69-character line format
* Mean orbital elements (not osculating)
* BSTAR drag term for atmospheric decay
* Requires SGP4/SDP4 propagation models
* Distributed by Space-Track, CelesTrak

**Important Notes:**

* TLE accuracy degrades rapidly (days to weeks depending on orbit)
* TEME reference frame (non-standard)
* Mean elements, not instantaneous orbital state
* **VALAR does not support direct TLE import**

**If you need to use TLE data:**

1. Use external SGP4/SDP4 library to propagate TLE
2. Convert resulting state from TEME to GCRF or ITRF
3. Import the state vector into VALAR as OPM format

[Read TLE documentation →](/file-formats/tle)

***

### SP3 (Standard Product 3)

**Purpose:** Distribute precise satellite orbits and clock corrections, primarily for GNSS constellations and LEO satellites.

**Key Features:**

* Multi-satellite support (up to 85 satellites per file)
* Integrated clock corrections at each epoch
* Multiple GNSS systems (GPS, GLONASS, Galileo, BeiDou, QZSS)
* LEO satellite support
* Optional velocity and correlation records
* Accuracy information via exponents and standard deviations

**When to Use:**

* Importing IGS precise orbit products
* Working with GNSS satellite ephemerides
* Precise Point Positioning (PPP) applications
* Orbit comparison and validation against IGS products

<Info>
  SP3 is an IGS (International GNSS Service) standard, not a CCSDS format. It is widely used in the geodetic and GNSS communities.
</Info>

[Read SP3 documentation →](/file-formats/sp3)

***

## File Format Standards

### CCSDS Standards

Most formats follow CCSDS (Consultative Committee for Space Data Systems) recommendations:

* **CCSDS 502.0-B-3**: Orbit Data Messages (OPM, OEM, OCM, OMM)
* **CCSDS 503.0-B-2**: Tracking Data Message (TDM)
* **CCSDS 508.0-B-1**: Conjunction Data Message (CDM)

### Other Standards

* **IGS SP3-c**: Standard Product 3 format for precise GNSS orbits and clocks

These standards ensure global interoperability between:

* Space agencies (NASA, ESA, JAXA, etc.)
* Commercial satellite operators
* Ground station networks
* Mission control centers
* Orbit determination systems

### KVN vs XML Format

CCSDS formats support two representations:

**KVN (Keyword-Value Notation)**

* Human-readable ASCII text format
* Easier to parse and debug
* Smaller file sizes
* Preferred for operational use
* **VALAR uses KVN format**

**XML (Extensible Markup Language)**

* Structured hierarchical format
* Machine-readable with schema validation
* Better for complex nested data
* Common in enterprise systems

All examples in VALAR documentation use KVN format.

***

## Reference Frames and Time Systems

All CCSDS formats specify reference frames and time systems explicitly:

### Common Reference Frames

| Frame       | Type          | Use Case                                         |
| ----------- | ------------- | ------------------------------------------------ |
| **GCRF**    | Inertial      | Orbit propagation, recommended for most purposes |
| **EME2000** | Inertial      | Legacy systems, CCSDS file compatibility         |
| **ITRF**    | Earth-fixed   | Ground tracks, ground station coordinates        |
| **RTN**     | Local Orbital | Maneuver planning (radial-tangential-normal)     |
| **LVLH**    | Local Orbital | Formation flying, relative guidance              |

### Common Time Systems

| Time System | Description                | Use Case                          |
| ----------- | -------------------------- | --------------------------------- |
| **UTC**     | Coordinated Universal Time | Operational tracking, most common |
| **TAI**     | International Atomic Time  | High-precision applications       |
| **GPS**     | GPS Time                   | GPS-based navigation              |
| **TDB**     | Barycentric Dynamical Time | Deep space missions               |

<Info>
  See [Reference Frames documentation](/platform-overview/reference-frames) for detailed information about coordinate systems and transformations.
</Info>

***

## Best Practices

### File Import/Export

1. **Validate before sharing**: Ensure files conform to CCSDS standards
2. **Include comments**: Document assumptions, corrections, and data sources
3. **Specify units explicitly**: Don't rely on default unit assumptions
4. **Use appropriate precision**: Match numerical precision to accuracy requirements
5. **Test round-trip**: Verify data integrity through import/export cycles

### Format Selection

6. **Match format to purpose**: Don't use OCM when OPM suffices
7. **Consider file size**: OEM files can be large for long time spans
8. **Document extensions**: If using non-standard fields, provide ICD documentation
9. **Standardize internally**: Use consistent formats within your organization
10. **Maintain compatibility**: Verify receiving systems support your format choices

### Reference Frame Selection

11. **Use GCRF for propagation**: Modern inertial frame, well-defined
12. **Use ITRF for ground operations**: Earth-fixed frame for station coordinates
13. **Document LOF definitions**: LVLH, RTN naming varies between organizations
14. **Convert early**: Transform non-standard frames (TEME) to standard frames quickly

### Time System Selection

15. **Prefer UTC for operations**: Most universally understood
16. **Use TAI for precision work**: Avoids leap second discontinuities
17. **Document time system clearly**: Ambiguity causes significant errors
18. **Maintain consistency**: Don't mix time systems within a file

***

## Getting Help

For detailed information about each format:

* Browse individual format documentation pages
* Consult CCSDS specifications (linked in each format page)
* Review example files provided in documentation
* Contact VALAR support for import/export questions

For questions about which format to use for your specific use case, consult the format selection guide above or reach out to support.