For the complete documentation index, see 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 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
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 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.
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 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). |
| 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 |
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:
- Select SpaceX OPM as the format in the import dialog
- VALAR automatically converts the ECEF state to an inertial frame
- The Longitude of Ascending Node is converted to Right Ascension
- Position and velocity units are converted from meters to kilometers
SpaceX OPM format is documented in the Falcon User’s Guide. VALAR’s SpaceX OPM parser handles all necessary coordinate transformations automatically. 