> ## 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.
# Orbit Parameter Message (OPM)
> Working with CCSDS and SpaceX Orbit Parameter Message formats in VALAR
> For the complete documentation index, see [llms.txt](/llms.txt).
The Orbit Parameter Message (OPM) is a standardized ASCII text format for exchanging spacecraft orbital state information at a single epoch. Unlike [OEM](/file-formats/oem) which contains time-series ephemeris data, OPM represents a snapshot of spacecraft state and can include optional physical parameters and one or more maneuver definitions.
## Key Components
An OPM file contains several distinct sections:
* **Header**: File-level metadata including format version, creation date, and originator
* **Metadata**: Orbital context such as object identification, reference frame, and time system
* **State Vector**: Spacecraft position and velocity at a specific epoch (Cartesian coordinates)
* **Keplerian Elements (Optional)**: Supplementary orbital element representation (semi-major axis, eccentricity, inclination, etc.) that accompanies the state vector
* **Spacecraft Parameters (Optional)**: Physical properties for orbit propagation (mass, drag coefficient, solar radiation pressure)
* **Maneuver Parameters (Optional)**: One or more maneuvers (impulsive or finite), each with delta-V components
## State Representation
Every OPM carries a mandatory **Cartesian state vector**. Osculating **Keplerian elements** may be added as an optional supplementary block describing the same state — they do not replace the state vector.
### Cartesian State Vector (Mandatory)
Position and velocity at the epoch, in the reference frame given by `REF_FRAME`:
| Element | Description | Unit |
| -------------------------- | ------------------- | ---- |
| **X, Y, Z** | Position components | km |
| **X\_DOT, Y\_DOT, Z\_DOT** | Velocity components | km/s |
### Osculating Keplerian Elements (Optional)
A supplementary block. If included, **all** of its elements must be present — including `GM`:
| Element | Description | Unit |
| -------------------------------------- | ------------------------------------------------------- | ------ |
| **SEMI\_MAJOR\_AXIS** | Size of the orbit | km |
| **ECCENTRICITY** | Shape of the orbit (0 = circular, \< 1 = elliptical) | — |
| **INCLINATION** | Angle between the orbital plane and the reference plane | deg |
| **RA\_OF\_ASC\_NODE** | Right ascension of ascending node | deg |
| **ARG\_OF\_PERICENTER** | Argument of pericenter | deg |
| **TRUE\_ANOMALY** or **MEAN\_ANOMALY** | Position along the orbit | deg |
| **GM** | Gravitational coefficient (G × central mass) | km³/s² |
## Spacecraft Physical Parameters
OPM can include physical properties required for accurate orbit propagation:
* **MASS**: Spacecraft mass (kg)
* **SOLAR\_RAD\_AREA**: Cross-sectional area for solar radiation pressure (m²)
* **SOLAR\_RAD\_COEFF**: Solar radiation pressure coefficient
* **DRAG\_AREA**: Cross-sectional area for atmospheric drag (m²)
* **DRAG\_COEFF**: Atmospheric drag coefficient
## Common Use Cases
* **Orbit Determination Results**: Sharing fitted state vectors after measurement processing
* **State Vector Import**: Loading initial conditions into mission planning systems
* **Data Exchange**: Transferring orbital state between organizations
* **Mission Analysis**: Providing reference states for trajectory studies
Complete definition of the OPM standard on [CCSDS 502.0-B-3](https://ccsds.org/Pubs/502x0b3e1.pdf) guidelines.
Here is a sample OPM file in KVN format:
```
CCSDS_OPM_VERS = 3.0
CREATION_DATE = 2024-06-03T05:33:00.000
ORIGINATOR = VALAR
COMMENT Orbit determination solution from tracking pass
COMMENT State vector after maneuver execution
OBJECT_NAME = SPACECRAFT-ALPHA
OBJECT_ID = 2023-001A
CENTER_NAME = EARTH
REF_FRAME = EME2000
TIME_SYSTEM = UTC
EPOCH = 2024-06-03T00:00:00.000
X = 6655.9942 [km]
Y = -40218.5751 [km]
Z = -82.9177 [km]
X_DOT = 3.11548208 [km/s]
Y_DOT = 0.47042605 [km/s]
Z_DOT = -0.00101495 [km/s]
COMMENT Spacecraft physical parameters for propagation
MASS = 1913.000 [kg]
SOLAR_RAD_AREA = 10.000 [m**2]
SOLAR_RAD_COEFF = 1.300
DRAG_AREA = 10.000 [m**2]
DRAG_COEFF = 2.300
COMMENT Planned orbit-raising maneuver
MAN_EPOCH_IGNITION = 2024-06-03T09:00:34.1
MAN_DURATION = 132.60 [s]
MAN_DELTA_MASS = -18.418 [kg]
MAN_REF_FRAME = RTN
MAN_DV_1 = -0.02325700 [km/s]
MAN_DV_2 = 0.01683160 [km/s]
MAN_DV_3 = -0.00893444 [km/s]
```
## OPM with Optional Keplerian Elements
```
CCSDS_OPM_VERS = 3.0
CREATION_DATE = 2024-06-03T05:33:00.000
ORIGINATOR = VALAR
OBJECT_NAME = SPACECRAFT-BETA
OBJECT_ID = 2023-002B
CENTER_NAME = EARTH
REF_FRAME = EME2000
TIME_SYSTEM = UTC
EPOCH = 2024-06-03T12:00:00.000
X = 36127.350 [km]
Y = 21794.520 [km]
Z = 36.800 [km]
X_DOT = -1.588400 [km/s]
Y_DOT = 2.632800 [km/s]
Z_DOT = 0.000100 [km/s]
COMMENT Osculating Keplerian elements for the state above
SEMI_MAJOR_AXIS = 42164.140 [km]
ECCENTRICITY = 0.0001234
INCLINATION = 0.05 [deg]
RA_OF_ASC_NODE = 75.123 [deg]
ARG_OF_PERICENTER = 180.456 [deg]
TRUE_ANOMALY = 90.789 [deg]
GM = 398600.4418 [km**3/s**2]
MASS = 2500.000 [kg]
SOLAR_RAD_AREA = 15.000 [m**2]
SOLAR_RAD_COEFF = 1.200
DRAG_AREA = 12.000 [m**2]
DRAG_COEFF = 2.200
```
## Importing OPM in VALAR
Import an OPM from the [State Vectors](/features/state-vectors) page: click **Import**, choose **OPM (CCSDS Standard)** as the format, and upload a `.txt` or `.opm` file. VALAR resolves the target spacecraft automatically from the file's `OBJECT_ID` (COSPAR ID) or `OBJECT_NAME`, so you do not select a spacecraft for CCSDS OPM imports. A successful import adds a state vector to that spacecraft.
VALAR imports the **Cartesian state vector** — position (`X`, `Y`, `Z`) in km and velocity (`X_DOT`, `Y_DOT`, `Z_DOT`) in km/s. An OPM that provides only Keplerian elements (`SEMI_MAJOR_AXIS`, `ECCENTRICITY`, …) and no Cartesian state vector is **not a conformant OPM and cannot be imported**. Re-export the OPM with the Cartesian state vector before importing.
Every imported OPM must also include a `MASS` value (kg), which VALAR uses to propagate the state.
### Import Error Modes
If an import is rejected, the dialog shows a red alert with an error code and message. The most common OPM import errors:
| Code | Cause | Remediation |
| ----------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **OS-4004** | The OPM has no Cartesian state vector — for example, it provides only Keplerian elements. | Re-export the OPM with the Cartesian state-vector block (`X`, `Y`, `Z`, `X_DOT`, `Y_DOT`, `Z_DOT`). Keplerian-only OPMs are not supported. |
| **OS-4003** | The file is not valid CCSDS OPM — unrecognized keywords, malformed values, or stray non-CCSDS text. | Check the file against the CCSDS OPM format and remove any non-CCSDS labels or stray text. |
| **OS-4001** | The OPM has no `MASS` keyword. Mass is required to propagate the imported state. | Add a `MASS` line (kg) to the OPM and re-import. |
| **OS-4014** | The OPM `MASS` is less than the spacecraft's configured dry mass. | Correct the OPM mass, or update the spacecraft's dry mass on the [Spacecraft](/features/spacecraft-management) page. |
| **OS-4016** | The OPM has neither `OBJECT_ID` nor `OBJECT_NAME`, so VALAR cannot match it to a spacecraft. | Add an `OBJECT_ID` (COSPAR ID) or `OBJECT_NAME` that matches a spacecraft in your fleet. |
| **OS-4015** | The `OBJECT_ID` or `OBJECT_NAME` does not match any spacecraft in your fleet. | Create the spacecraft first, or correct the identifier in the OPM. |
| **OS-4012** | (SpaceX OPM) The OPM's `OBJECT_ID` does not match the spacecraft you selected. | Select the matching spacecraft, or correct the OPM's `OBJECT_ID`. |
| **SV-4003** | The state vector `EPOCH` is in the future. | Use an OPM whose `EPOCH` is at or before the current time (UTC). |
## Differences Between OPM and Other Formats
| Feature | OPM | OEM | OCM |
| ------------------ | --------------------------------- | ------------------ | --------------------------- |
| Temporal Scope | Single epoch | Time series | Single or multiple epochs |
| Maneuvers | One or more (impulsive or finite) | Not supported | Multiple maneuvers |
| Keplerian Elements | Optional | Not supported | Optional |
| Covariances | Optional | Optional per epoch | Optional |
| Primary Use Case | State snapshots, OD output | Ephemeris sharing | Comprehensive mission plans |
## SpaceX OPM Format
SpaceX provides state vectors to customers via a proprietary OPM variant derived from the CCSDS standard. This format is generated from Falcon second stage flight telemetry and has several key differences from standard CCSDS OPM.
The SpaceX OPM represents the state of the **second stage**, not the deployed spacecraft. Any position, velocity, attitude, or attitude-rate differences between the second stage and your spacecraft at separation must be accounted for by the recipient.
### SpaceX OPM Fields
| Field | Description | Units |
| ------------------------------- | ------------------------------------------- | --------------- |
| **UTC time at liftoff** | Launch time reference | DOY:HH:MM:SS.SS |
| **UTC time of current state** | Epoch of the state vector | DOY:HH:MM:SS.SS |
| **Mission elapsed time** | Time since liftoff | seconds |
| **ECEF Position (X,Y,Z)** | Position in WGS84 ECEF frame | meters |
| **ECEF Velocity (X,Y,Z)** | Earth-relative velocity in ECEF | m/s |
| **LVLH to BODY quaternion** | Attitude quaternion (scalar-first: S,X,Y,Z) | dimensionless |
| **Inertial body rates (X,Y,Z)** | Angular velocity | deg/s |
| **Apogee Altitude** | Maximum altitude (spherical Earth) | km |
| **Perigee Altitude** | Minimum altitude (spherical Earth) | km |
| **Inclination** | Orbital inclination | degrees |
| **Argument of Perigee** | Orientation of orbit ellipse | degrees |
| **Longitude of Asc. Node** | Ascending node referenced to Greenwich | degrees |
| **True Anomaly** | Position along orbit | degrees |
### Key Differences from CCSDS OPM
| Aspect | CCSDS OPM | SpaceX OPM |
| ---------------------- | -------------------------------- | -------------------------------------------- |
| **Reference Frame** | Inertial (EME2000, GCRF) | WGS84 ECEF, inertially frozen at state epoch |
| **Position Units** | kilometers | meters |
| **Velocity Units** | km/s | m/s |
| **Velocity Reference** | Inertial | Earth-relative |
| **Time Format** | ISO 8601 | Day-of-Year (DOY:HH:MM:SS.SS) |
| **Ascending Node** | Right Ascension (vernal equinox) | Longitude (Greenwich Meridian) |
| **Altitude Reference** | Typically WGS84 ellipsoid | Spherical Earth (6378.137 km radius) |
| **Attitude Data** | Not included | LVLH-to-body quaternion + body rates |
### Sample SpaceX OPM
```
SpaceX OPM output (generated 2024-06-15-Sat-14-30-00):
All orbital elements are defined as osculating at the instant of the printed state.
Orbital elements are computed in an inertial frame realized by inertially freezing
the WGS84 ECEF frame at time of current state.
UTC time at liftoff: 166:14:00:00.00
UTC time of current state: 166:14:45:30.25
Mission elapsed time (s): +2730.25
ECEF (X,Y,Z) Position (m): +4523156.789, -3298765.432, +4012345.678
ECEF (X,Y,Z) Velocity* (m/s): +5234.567, +4123.456, -3456.789
LVLH to BODY quaternion (S,X,Y,Z): +0.7071068, +0.0000000, +0.7071068, +0.0000000
Inertial body rates (X,Y,Z) (deg/s): +0.0012345, -0.0023456, +0.0034567
Apogee Altitude** (km): +00850.123
Perigee Altitude** (km): +00320.456
Inclination (deg): +53.215
Argument of Perigee (deg): +090.123
Longitude of the Asc. Node*** (deg): +125.678
True Anomaly (deg): +45.890
Notes:
* ECEF velocity is Earth-relative
** Apogee/Perigee altitude assumes a spherical Earth, 6378.137 km radius
*** LAN is defined as the angle between Greenwich Meridian and the ascending node
```
### Importing SpaceX OPM in VALAR
When importing SpaceX OPM files:
1. Select **SpaceX OPM** as the format in the import dialog
2. VALAR automatically converts the ECEF state to an inertial frame
3. The Longitude of Ascending Node is converted to Right Ascension
4. Position and velocity units are converted from meters to kilometers
SpaceX OPM format is documented in the [Falcon User's Guide](https://www.spacex.com/vehicles/falcon-9/). VALAR's SpaceX OPM parser handles all necessary coordinate transformations automatically.