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

# OCM (Orbit Comprehensive Message)

> Working with CCSDS Orbit Comprehensive Message format in VALAR

> For the complete documentation index, see [llms.txt](https://docs.valar.space/llms.txt).

The Orbit Comprehensive Message (OCM) is the most feature-rich standardized format for exchanging spacecraft orbital information. Unlike OPM (single-epoch state) and OEM (ephemeris time series), OCM combines multiple data types into a single comprehensive message, supporting trajectory state history, spacecraft physical properties, covariance time history, multiple maneuvers, perturbation parameters, and user-defined data.

## Why OCM is "Comprehensive"

OCM aggregates and extends the capabilities of OPM, OMM, and OEM into one unified format:

* **Multiple Trajectory States**: Time series of state vectors or Keplerian elements (like OEM)
* **Single-Epoch States**: State snapshots at specific times (like OPM)
* **Multiple Maneuvers**: Comprehensive maneuver planning with impulsive and continuous thrust
* **Physical Properties**: Spacecraft mass, area, drag/SRP coefficients, attitude information
* **Covariance Time History**: Uncertainty evolution over time
* **Perturbation Parameters**: Force model configuration for propagation
* **User-Defined Data**: Custom parameters for mission-specific needs
* **Parent-Child Scenarios**: Support for deployment and separation events

> [!NOTE]
>
> OCM is the recommended format when you need to exchange comprehensive mission planning data, including orbital states, maneuver plans, spacecraft properties, and uncertainties in a single file.

## Key Components

An OCM file contains several distinct sections (all optional except Header and Metadata):

* **Header**: File-level metadata (format version, creation date, originator)
* **Metadata**: Mission context (object identification, time system, reference frame)
* **Trajectory State Time History**: Cartesian state vectors or Keplerian elements over time
* **Physical Descriptor**: Spacecraft physical properties (mass, area, drag coefficient, etc.)
* **Covariance Time History**: Position/velocity uncertainty matrices over time
* **Maneuver Parameters**: Multiple maneuver definitions (impulsive or continuous thrust)
* **Perturbation Parameters**: Force model specification for propagation
* **Orbit Determination Parameters**: OD configuration and results
* **User-Defined Parameters**: Custom mission-specific data

## Structure Overview

### OCM Hierarchy

```
OCM File
├── Header (CCSDS_OCM_VERS, CREATION_DATE, ORIGINATOR)
├── Metadata Section (META_START to META_STOP)
│   ├── Time system, reference frame
│   ├── Object identification
│   ├── Epoch reference (EPOCH_TZERO)
│   └── Trajectory interpolation settings
├── Trajectory State Blocks (TRAJ_START to TRAJ_STOP) [Optional]
│   └── Multiple state vector or Keplerian element time series
├── Physical Descriptor Block (PHYS_START to PHYS_STOP) [Optional]
│   └── Mass, area, attitude, drag/SRP coefficients
├── Covariance Blocks (COV_START to COV_STOP) [Optional]
│   └── Time series of covariance matrices
├── Maneuver Blocks (MAN_START to MAN_STOP) [Optional]
│   └── Multiple maneuver definitions with unique IDs
├── Perturbation Block (PERT_START to PERT_STOP) [Optional]
│   └── Force model configuration
├── Orbit Determination Block (OD_START to OD_STOP) [Optional]
│   └── OD settings and results
└── User-Defined Block (USER_START to USER_STOP) [Optional]
    └── Custom parameters
```

## Metadata Fields

### Required Metadata

| Field | Description | Example Values |
| - | - | - |
| **TIME\_SYSTEM** | Time system for all epochs | UTC, TAI, GPS |
| **EPOCH\_TZERO** | Reference epoch for relative times | 2024-01-01T00:00:00 |

### Object Identification

| Field | Description | Example |
| - | - | - |
| **OBJECT\_NAME** | Spacecraft common name | SPACECRAFT-ALPHA |
| **INTERNATIONAL\_DESIGNATOR** | COSPAR ID | 2023-001A |
| **CATALOG\_NAME** | Catalog identifier source | SATCAT |
| **OBJECT\_DESIGNATOR** | Object ID in catalog | 12345 |

### Trajectory Configuration

| Field | Description | Values |
| - | - | - |
| **REF\_FRAME** | Reference frame for states | GCRF, EME2000, ITRF |
| **REF\_FRAME\_EPOCH** | Epoch for reference frame | J2000 epoch |
| **TRAJ\_TYPE** | Trajectory representation | CARTESIAN, KEPLERIAN, GEODETIC |
| **TRAJ\_UNITS** | Units for trajectory data | \[km, km, km, km/s, km/s, km/s] |

> [!NOTE]
>
> EPOCH\_TZERO serves as the time origin for all relative time references in the OCM. Absolute times can also be used where appropriate.

## Trajectory State Time History

OCM supports time series of orbital states in multiple representations:

### Cartesian State Vectors

```
TRAJ_START
TRAJ_TYPE   = CARTESIAN
TRAJ_UNITS  = [km, km, km, km/s, km/s, km/s]

EPOCH       X           Y           Z           X_DOT       Y_DOT       Z_DOT
+0.000      6655.994    -40218.575  -82.918     3.115482    0.470426    -0.001015
+3600.000   6892.441    -39845.123  -76.234     3.087234    0.501287    -0.000923
+7200.000   7112.873    -39458.892  -69.445     3.058012    0.531456    -0.000831
TRAJ_STOP
```

### Keplerian Elements

```
TRAJ_START
TRAJ_TYPE   = KEPLERIAN
TRAJ_UNITS  = [km, n/a, deg, deg, deg, deg]

EPOCH       SEMI_MAJOR_AXIS  ECCENTRICITY  INCLINATION  RA_ASC_NODE  ARG_PERICENTER  TRUE_ANOMALY
+0.000      42164.140        0.0001234     0.05         75.123       180.456         90.789
+3600.000   42164.245        0.0001245     0.05         75.234       180.567         95.123
TRAJ_STOP
```

Time values can be:

* **Absolute**: Full ISO 8601 timestamp
* **Relative**: Offset in seconds from EPOCH\_TZERO (indicated by `+` or `-` prefix)

## Physical Descriptor Block

Spacecraft physical properties for accurate propagation:

```
PHYS_START
WET_MASS            = 2000.000 [kg]
DRY_MASS            = 1850.000 [kg]
SRP_CONST_AREA      = 10.000 [m**2]
SOLAR_RAD_COEFF     = 1.300
DRAG_CONST_AREA     = 10.000 [m**2]
DRAG_COEFF_NOM      = 2.300
OEB_PARENT_FRAME    = SPACECRAFT_BODY
OEB_Q1              = 0.707
OEB_Q2              = 0.000
OEB_Q3              = 0.000
OEB_QC              = 0.707
PHYS_STOP
```

### Key Physical Parameters

| Parameter | Description | Units |
| - | - | - |
| **WET\_MASS** | Fully fueled mass | kg |
| **DRY\_MASS** | Mass without propellant | kg |
| **SRP\_CONST\_AREA** | Cross-sectional area for solar radiation pressure | m² |
| **SOLAR\_RAD\_COEFF** | SRP coefficient (typically 1.0-1.5) | dimensionless |
| **DRAG\_CONST\_AREA** | Cross-sectional area for atmospheric drag | m² |
| **DRAG\_COEFF\_NOM** | Nominal drag coefficient (typically 2.0-2.5) | dimensionless |
| **OEB\_Q1, Q2, Q3, QC** | Attitude quaternion | dimensionless |

## Covariance Time History

OCM supports time-varying covariance matrices to represent uncertainty evolution:

```
COV_START
COV_TYPE        = CARTESIAN
COV_ORDERING    = LTRI
COV_UNITS       = [km**2, km**2, km**2, km**2/s**2, km**2/s**2, km**2/s**2]

EPOCH           CX_X    CY_X    CY_Y    CZ_X    CZ_Y    CZ_Z
+0.000          4.142e+01  -8.579e+00  5.189e+01  -4.788e+01  -4.472e+01  5.960e+01

EPOCH           CX_DOT_X    CX_DOT_Y    CX_DOT_Z    CX_DOT_X_DOT
+0.000          3.523e-03   1.045e-03   -1.234e-03  8.945e-07

EPOCH           CY_DOT_X    CY_DOT_Y    CY_DOT_Z    CY_DOT_X_DOT    CY_DOT_Y_DOT
+0.000          -2.678e-03  -5.234e-04  1.876e-03   -3.456e-07      7.234e-07

EPOCH           CZ_DOT_X    CZ_DOT_Y    CZ_DOT_Z    CZ_DOT_X_DOT    CZ_DOT_Y_DOT    CZ_DOT_Z_DOT
+0.000          -1.234e-03  2.345e-03   -8.765e-04  2.134e-07       -4.567e-07      6.789e-07
COV_STOP
```

The covariance matrix is stored in lower-triangular form, representing the 6×6 position-velocity uncertainty.

## Maneuver Parameters

OCM's most powerful feature is comprehensive maneuver specification supporting both impulsive and continuous thrust maneuvers.

### Impulsive Maneuver

A single instantaneous velocity change:

```
MAN_START
MAN_ID              = MAN-001
MAN_DEVICE_ID       = THRUSTER-PRIMARY
MAN_PREV_ID         = N/A
MAN_NEXT_ID         = MAN-002
MAN_REF_FRAME       = RTN
MAN_FRAME_EPOCH     = 2024-06-03T09:00:00.000

DC_TYPE             = IMPULSIVE
MAN_COMPOSITION     = TIME_ABSOLUTE, MAN_DV_1, MAN_DV_2, MAN_DV_3
MAN_UNITS           = [s, km/s, km/s, km/s]

2024-06-03T09:00:34.100  -0.02325700  0.01683160  -0.00893444
MAN_STOP
```

### Continuous Thrust Maneuver

Extended burn with time-varying thrust profile:

```
MAN_START
MAN_ID              = MAN-002
MAN_DEVICE_ID       = THRUSTER-ION
MAN_REF_FRAME       = RTN
DC_TYPE             = CONTINUOUS
MAN_COMPOSITION     = TIME_ABSOLUTE, MAN_DURA, THR_X, THR_Y, THR_Z, THR_ISP, DELTA_MASS
MAN_UNITS           = [s, s, N, N, N, s, kg]

2024-06-04T01:10:00.000  500.0  0.0000  0.0650  0.0000  3000.0  -0.78
2024-06-04T01:20:00.000  500.0  0.0000  0.0000  0.0650  3000.0  -0.78
2024-06-04T01:30:00.000  500.0  0.0650  0.0000  0.0000  3000.0  -0.78
MAN_STOP
```

### Maneuver Metadata Fields

| Field | Description | Values |
| - | - | - |
| **MAN\_ID** | Unique maneuver identifier | MAN-001, BURN-A, etc. |
| **MAN\_BASIS** | Optional CCSDS provenance metadata | Does not classify a stored VALAR record or select import behavior; omitted on export |
| **MAN\_DEVICE\_ID** | Thruster or device ID | Thruster name or ALL |
| **MAN\_PREV\_ID** | Previous maneuver in sequence | MAN\_ID or N/A |
| **MAN\_NEXT\_ID** | Next maneuver in sequence | MAN\_ID or N/A |
| **MAN\_REF\_FRAME** | Reference frame for delta-V | RTN, LVLH, TNW, inertial |
| **DC\_TYPE** | Maneuver type | IMPULSIVE, CONTINUOUS |

### MAN\_COMPOSITION — Customizable Data Columns

The `MAN_COMPOSITION` field defines which data columns appear in the maneuver data rows. This allows flexible maneuver specification tailored to the mission needs.

**Common composition fields:**

| Field | Description | Typical Units |
| - | - | - |
| **TIME\_ABSOLUTE** | Absolute time stamp | ISO 8601 string |
| **TIME\_RELATIVE** | Time relative to EPOCH\_TZERO | seconds |
| **MAN\_DURA** | Burn duration | seconds |
| **MAN\_DV\_1, MAN\_DV\_2, MAN\_DV\_3** | Delta-V components | km/s |
| **THR\_X, THR\_Y, THR\_Z** | Thrust components | Newtons |
| **THR\_MAG** | Thrust magnitude | Newtons |
| **THR\_ISP** | Specific impulse | seconds |
| **DELTA\_MASS** | Mass change (negative for consumption) | kg |
| **THR\_EFFICIENCY** | Thruster efficiency | 0.0 to 1.0 |

> [!WARNING]
>
> The order of fields in MAN\_COMPOSITION must exactly match the order of data columns in subsequent maneuver data rows. Units must be specified in MAN\_UNITS in the same order.

### Maneuver Chaining

OCM supports maneuver sequences through **MAN\_PREV\_ID** and **MAN\_NEXT\_ID**, enabling:

* Maneuver dependency tracking
* Sequence validation
* Mission timeline reconstruction

## Perturbation Parameters

Define the force model configuration for orbit propagation:

```
PERT_START
ATMOSPHERIC_MODEL       = NRLMSISE00
GRAVITY_MODEL           = EGM-96: 70D 70O
EQUATORIAL_RADIUS       = 6378.137 [km]
GM                      = 398600.4415 [km**3/s**2]
N_BODY_PERTURBATIONS    = SUN, MOON
SOLAR_RAD_PRESSURE      = YES
SOLID_EARTH_TIDES       = YES
OCEAN_TIDES             = YES
THIRD_BODY_GRAVITY      = YES
PERT_STOP
```

### Perturbation Parameters

| Parameter | Description | Example Values |
| - | - | - |
| **ATMOSPHERIC\_MODEL** | Atmospheric density model | NRLMSISE00, JB2008, Harris-Priester |
| **GRAVITY\_MODEL** | Geopotential model with degree/order | EGM-96: 70D 70O, WGS84: 8D 8O |
| **GM** | Gravitational parameter | 398600.4415 km³/s² |
| **N\_BODY\_PERTURBATIONS** | Third-body perturbations | SUN, MOON, JUPITER |
| **SOLAR\_RAD\_PRESSURE** | Include SRP | YES, NO |
| **SOLID\_EARTH\_TIDES** | Include solid Earth tides | YES, NO |
| **OCEAN\_TIDES** | Include ocean tides | YES, NO |

> [!NOTE]
>
> Perturbation parameters ensure the receiving system can accurately propagate the orbit using the same force model configuration as the originating system.

## User-Defined Parameters

OCM allows custom parameters for mission-specific data:

```
USER_START
USER_PARAM_1 = MISSION_PHASE
USER_VALUE_1 = OPERATIONAL
USER_PARAM_2 = BATTERY_SOC
USER_VALUE_2 = 87.5 [%]
USER_PARAM_3 = CONTACT_FREQUENCY
USER_VALUE_3 = 2.2e9 [Hz]
USER_STOP
```

> [!WARNING]
>
> User-defined parameters should be used sparingly and documented in Interface Control Documents (ICDs). Their meaning must be clearly communicated to all parties exchanging the OCM file.

## Common Use Cases

* **Comprehensive Mission Planning**: Complete mission state including trajectory, maneuvers, and spacecraft properties
* **Maneuver Sequencing**: Planning and tracking multiple burn sequences
* **Conjunction Data Submission**: Providing detailed orbital information to conjunction assessment services
* **Formation Flying**: Parent-child deployment scenarios and relative state information
* **Mission Handover**: Comprehensive state transfer between control centers
* **Long-Duration Missions**: Time-varying properties (mass, drag coefficient) over mission lifetime
* **High-Fidelity Propagation**: Providing complete force model and spacecraft parameters

> [!NOTE]
>
> Complete definition of the OCM standard in [CCSDS 502.0-B-3](https://ccsds.org/Pubs/502x0b3e1.pdf) specification.

## Complete OCM Example

Here is a comprehensive OCM file demonstrating multiple features:

```
CCSDS_OCM_VERS     = 3.0
CREATION_DATE      = 2024-06-15T08:30:00.000
ORIGINATOR         = VALAR

COMMENT Comprehensive mission planning file
COMMENT Includes trajectory, maneuvers, and physical properties

META_START
TIME_SYSTEM        = UTC
EPOCH_TZERO        = 2024-06-15T00:00:00.000
OBJECT_NAME        = SPACECRAFT-GAMMA
INTERNATIONAL_DESIGNATOR = 2024-001A
CATALOG_NAME       = SATCAT
OBJECT_DESIGNATOR  = 59234
REF_FRAME          = EME2000
TRAJ_TYPE          = CARTESIAN
TRAJ_UNITS         = [km, km, km, km/s, km/s, km/s]
META_STOP

COMMENT Initial trajectory state history

TRAJ_START
EPOCH       X           Y           Z           X_DOT       Y_DOT       Z_DOT
+0.000      6655.994    -40218.575  -82.918     3.115482    0.470426    -0.001015
+3600.000   6892.441    -39845.123  -76.234     3.087234    0.501287    -0.000923
+7200.000   7112.873    -39458.892  -69.445     3.058012    0.531456    -0.000831
TRAJ_STOP

COMMENT Spacecraft physical properties

PHYS_START
WET_MASS            = 2000.000 [kg]
DRY_MASS            = 1850.000 [kg]
SRP_CONST_AREA      = 10.000 [m**2]
SOLAR_RAD_COEFF     = 1.300
DRAG_CONST_AREA     = 10.000 [m**2]
DRAG_COEFF_NOM      = 2.300
PHYS_STOP

COMMENT First orbit-raising maneuver

MAN_START
MAN_ID              = RAISE-PERIGEE-1
MAN_DEVICE_ID       = THRUSTER-MAIN
MAN_PREV_ID         = N/A
MAN_NEXT_ID         = RAISE-APOGEE-1
MAN_REF_FRAME       = RTN
DC_TYPE             = IMPULSIVE
MAN_COMPOSITION     = TIME_ABSOLUTE, MAN_DV_1, MAN_DV_2, MAN_DV_3
MAN_UNITS           = [s, km/s, km/s, km/s]

2024-06-15T09:00:34.100  0.05234000  0.00124500  -0.00012300
MAN_STOP

COMMENT Second orbit-raising maneuver

MAN_START
MAN_ID              = RAISE-APOGEE-1
MAN_DEVICE_ID       = THRUSTER-MAIN
MAN_PREV_ID         = RAISE-PERIGEE-1
MAN_NEXT_ID         = CIRCULARIZE-1
MAN_REF_FRAME       = RTN
DC_TYPE             = IMPULSIVE
MAN_COMPOSITION     = TIME_ABSOLUTE, MAN_DV_1, MAN_DV_2, MAN_DV_3
MAN_UNITS           = [s, km/s, km/s, km/s]

2024-06-15T21:45:12.300  0.04876000  -0.00087600  0.00023400
MAN_STOP

COMMENT Circularization burn using low-thrust ion propulsion

MAN_START
MAN_ID              = CIRCULARIZE-1
MAN_DEVICE_ID       = ION-THRUSTER-1
MAN_PREV_ID         = RAISE-APOGEE-1
MAN_NEXT_ID         = N/A
MAN_REF_FRAME       = RTN
DC_TYPE             = CONTINUOUS
MAN_COMPOSITION     = TIME_ABSOLUTE, MAN_DURA, THR_X, THR_Y, THR_Z, THR_ISP, DELTA_MASS
MAN_UNITS           = [s, s, N, N, N, s, kg]

2024-06-16T10:00:00.000  600.0  0.0000  0.0850  0.0000  3200.0  -0.92
2024-06-16T10:10:00.000  600.0  0.0000  0.0850  0.0000  3200.0  -0.92
2024-06-16T10:20:00.000  600.0  0.0000  0.0850  0.0000  3200.0  -0.92
MAN_STOP

COMMENT Perturbation parameters for propagation

PERT_START
ATMOSPHERIC_MODEL       = NRLMSISE00
GRAVITY_MODEL           = EGM-96: 70D 70O
EQUATORIAL_RADIUS       = 6378.137 [km]
GM                      = 398600.4415 [km**3/s**2]
N_BODY_PERTURBATIONS    = SUN, MOON
SOLAR_RAD_PRESSURE      = YES
SOLID_EARTH_TIDES       = YES
OCEAN_TIDES             = NO
PERT_STOP
```

## VALAR Import Requirements

VALAR uses OCM as its file format for importing and exporting maneuver data. When importing an OCM file, VALAR validates several requirements beyond the base CCSDS standard. This section is the canonical reference for all import validation rules.

> [!NOTE]
>
> VALAR uses OCM exclusively for maneuver data. Other OCM sections (trajectory state history, covariance, perturbation parameters, orbit determination, user-defined parameters) are parsed but not imported.

### File Requirements

| Requirement | Details |
| - | - |
| **Format** | OCM (CCSDS 502.0-B-3), KVN notation |
| **Maximum file size** | 52 MB; the complete multipart request also has a 52 MB limit |
| **Content** | File must not be empty and must contain at least one maneuver block |

### Required Maneuver Fields

Every maneuver block (`MAN_START` to `MAN_STOP`) must include the following fields:

| Field | Requirement |
| - | - |
| `MAN_ID` | Nonblank, at most 63 characters, with no leading/trailing whitespace, control characters, `/`, `\`, `=`, `#`, or `?`. Exact `.` and `..` identities are not permitted. Commas, internal spaces and Unicode are supported. |
| `MAN_REF_FRAME` | Required. Must be one of the supported reference frames listed below. |
| `THR_X`, `THR_Y`, `THR_Z` | Required in the maneuver composition. At least one thrust component must be non-zero. |
| `THR_ISP` | Required. Specific impulse must be between **50** and **10,000 seconds**. A value of zero is not accepted. |

`MAN_BASIS` is **optional** format metadata. When supplied, it must be parseable as CCSDS
metadata; the customary `TELEMETRY` spelling is accepted as `DETERMINED_TLM`. Its value does
not select an import mode, become a stored classification, or authorize replacement of records.
Maneuver blocks do not need a uniform basis. Generic VALAR exports omit this field.

Stored burn segments also require an epoch and a positive finite duration. The general OCM
examples above illustrate the format; delta-V-only impulsive examples do not meet VALAR's
thrust, ISP, and duration requirements for stored maneuver imports.

> [!WARNING]
>
> Specific impulse values outside the 50–10,000 second range will be rejected. This range covers all common propulsion technologies, from cold-gas thrusters (\~50 s) to advanced ion engines (\~10,000 s).

### Physical Properties

Your OCM file must include a physical properties block (`PHYS_START` to `PHYS_STOP`) with the `WET_MASS` field:

```
PHYS_START
WET_MASS = 2000.000 [kg]
PHYS_STOP
```

### Supported Reference Frames

Stored maneuver thrust must use a supported **local orbital frame**. The general
OCM standard can describe other frames, but VALAR's stored-maneuver importer does
not accept `EME2000`, `J2000`, `GCRF`, `ICRF`, `ITRF`, `TOD`, `TEME`, or `MOD` for
`MAN_REF_FRAME`. Blank or unknown names are rejected rather than replaced with a default.

Common supported spellings and their handling are:

| Frame | Stored-maneuver handling |
| - | - |
| `RTN`, `RIC`, `QSW`, `RSW_ROTATING` | Rotating radial/transverse/normal convention. OCM `RIC` is retained as `RTN`; `RTN` reconstructs as Orekit `QSW`. |
| `RSW_INERTIAL`, `QSW_INERTIAL` | Inertial orbital-frame convention; distinct from the rotating variants. |
| `TNW_ROTATING` | Rotating TNW convention. Stored internal `TNW` exports with this unambiguous CCSDS spelling. |
| `TNW`, `TNW_INERTIAL` in OCM | Inertial TNW convention; the deprecated CCSDS `TNW` spelling is decoded as `TNW_INERTIAL`, distinct from stored internal rotating `TNW`. |
| `VNC`, `VNC_ROTATING` | VNC convention. **VNC is not mapped to QSW.** |
| `VNC_INERTIAL` | Inertial VNC convention; distinct from rotating VNC. |

Other Orekit local-orbital tokens and CCSDS orbit-relative names are accepted only
when the stored-maneuver frame decoder can resolve them. Internal acceptance does
not guarantee OCM representability: for example, a stored `ENU` frame cannot be
exported as OCM.

> [!NOTE]
>
> CCSDS `LVLH` and `LVLH_INERTIAL` in an OCM file retain their CCSDS meaning through
> the unambiguous stored token `LVLH_CCSDS_INERTIAL`. The historical internal Orekit
> token `LVLH` instead has QSW axes and exports as `RSW_ROTATING`; internal
> `LVLH_INERTIAL` exports as `RSW_INERTIAL`. Do not substitute these names or change
> a frame label to convert a thrust vector.

Manual record creation and editing require equivalent record and segment frames,
including the same rotation convention. VALAR validates this relationship without
transforming the supplied thrust components. Existing mixed-frame records remain
readable. A genuinely mixed-frame historical record exports as a **preservation
ZIP**, with a manifest describing the original resource and ordered, frame-labelled
OCM parts. The identity appears once per OCM part; the source record is not split
or renamed. This archive is for preservation, not reimport, and import rejects it.
Consistent-frame records retain the ordinary whole-record OCM workflow.

### Spacecraft Matching

Select a target spacecraft in the import dialog, or pass its VALAR `spacecraftId` to the API,
when an explicit target is needed. Otherwise VALAR looks for candidates using OCM metadata
in this order:

1. `OBJECT_NAME` — spacecraft name
2. `INTERNATIONAL_DESIGNATOR` — COSPAR ID (e.g., `2024-001A`)
3. `OBJECT_DESIGNATOR` — NORAD catalog number

The first identifier with candidates resolves the spacecraft only if there is one match. An
ambiguous match requires an explicit selection; VALAR does not choose an arbitrary spacecraft.
If no identifier matches an accessible spacecraft in the current organization and environment,
the import fails.

After resolving the spacecraft, file identifiers with corresponding non-null values on the
spacecraft record are cross-validated **case-insensitively**. A mismatch rejects the import,
including when you select the spacecraft explicitly.

> [!TIP]
>
> Before importing, verify that the `OBJECT_NAME`, `INTERNATIONAL_DESIGNATOR`, or `OBJECT_DESIGNATOR` in your OCM file matches what is configured on the spacecraft details page in VALAR.

### Consistency Rules

* **Unique identities:** Each `MAN_ID` must be new for the target spacecraft, both within the file and relative to existing stored records.
* **No temporal overlaps:** Enclosing maneuver intervals within the file and relative to stored records on the same spacecraft must not intersect, including gaps between a record's segments. Two maneuvers may share an endpoint (one ends exactly when the next begins).

### Import Behavior

Import adds records. Each file is atomic: if a record fails validation or conflicts, none of
that file is saved. Other successfully imported files remain saved. Review per-file outcomes
before retrying.

Duplicate identities and overlaps with stored records are rejected with `MANEUVER_CONFLICT`.
To change a record manually, use **Edit** on the [Maneuvers page](https://docs.valar.space/features/burn-plan.md#edit-a-record).
A name edit does not change the stable identity or exported `MAN_ID`. Through the
[Maneuver API](https://docs.valar.space/api-reference/maneuvers.md#correct-a-stored-maneuver), prepare corrected OCM,
explicitly delete the stored record, then import the corrected file. These are separate
operations, not an atomic replacement: a failed import leaves the record deleted. Import
does not overwrite existing records, and all file and physical validation still applies.

Conflicts require an explicit edit or delete; import never merges, trims, or deletes another
record. Pre-existing overlaps remain viewable in the application and exportable, but an
application edit or a corrected import must satisfy the non-overlap rule.

### Exporting Maneuvers

* **OCM Export**: Export individual stored maneuvers or a selected time range from VALAR as OCM files
* **Multi-Maneuver Support**: Multiple maneuvers are included in a single OCM file
* **Standard Compliance**: Exported OCM files follow CCSDS 502.0-B-3 specification
* **Interoperability**: OCM format enables maneuver data exchange with external systems and agencies
* **Identity**: `MAN_ID` stays fixed after name edits; optional `MAN_BASIS` is omitted

## Best Practices

### Data Organization

1. **Use EPOCH\_TZERO effectively**: Set to mission start or a significant epoch for cleaner relative times
2. **Include physical properties**: Always provide mass, area, and coefficient data for accurate propagation
3. **Document maneuver sequences**: Use MAN\_PREV\_ID and MAN\_NEXT\_ID to chain related maneuvers

### Maneuver Specification

4. **Choose appropriate DC\_TYPE**: IMPULSIVE for chemical burns, CONTINUOUS for ion/low-thrust
5. **Specify reference frames clearly**: Document whether RTN, LVLH, or other LOF is used
6. **Include all composition fields**: Don't omit important fields like DELTA\_MASS or THR\_ISP

### File Quality

7. **Add comments liberally**: Explain mission phases, maneuver purposes, assumptions
8. **Validate before sharing**: Ensure all referenced IDs exist and data is self-consistent
9. **Use appropriate units**: Follow CCSDS conventions and specify units explicitly in MAN\_UNITS

### Interoperability

10. **Minimize user-defined parameters**: Use standard fields whenever possible
11. **Document extensions**: If using USER blocks, provide clear documentation in ICDs
12. **Test interchange**: Check supported burn values on import/export. Optional classification metadata is not retained, and importing an identity already stored on the target spacecraft is rejected.

## Comparison with Other Formats

| Feature | OCM | OPM | OEM | TDM |
| - | - | - | - | - |
| Data Type | Comprehensive | Single state | Ephemeris | Observations |
| Temporal Scope | Time series + snapshots | Single epoch | Time series | Observation period |
| Maneuvers | Multiple (full specification) | One impulsive | None | None |
| Physical Properties | Extensive | Basic | None | None |
| Covariance | Time-varying | Optional single | Optional per epoch | None |
| Perturbations | Force model specification | None | None | None |
| Use Case | Mission planning | State exchange | Trajectory sharing | OD input |
| Complexity | High | Low | Medium | Medium |

## When to Use OCM

**Use OCM when you need:**

* Multiple maneuvers in a single file
* Time-varying spacecraft properties (mass, drag coefficient)
* Complete force model specification for propagation
* Maneuver sequencing and dependencies
* Parent-child deployment scenarios
* Comprehensive mission state exchange

**Use OPM instead when:**

* Sharing a simple single-epoch state vector
* Only one maneuver needs to be specified
* Simplicity and minimal file size are priorities

**Use OEM instead when:**

* Providing pre-computed ephemeris for interpolation
* No maneuvers or physical properties needed
* Standard trajectory exchange format expected


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.