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

# CDM (Conjunction Data Message)

> Prepare and import complete CCSDS Conjunction Data Messages in VALAR

The Conjunction Data Message (CDM) is a standardized format for communicating close-approach assessment data between spacecraft operators and tracking organizations. Use this page to prepare a complete `.cdm` file for the **Import** dialog on the conjunctions page and to check the required metadata, state vectors, and covariance terms before uploading.

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

## Key Components

| Component | Description |
| - | - |
| **Header** | Message metadata including format version, creation date, and originator information. |
| **Relative metadata** | Conjunction information such as Time of Closest Approach (TCA), miss distance, relative speed, and collision probability. |
| **Object metadata** | Identification, covariance method, maneuverability, and reference-frame information for both objects. |
| **Object data** | A state vector and covariance matrix for each object. |

## Critical Fields

| Field | Description | Unit |
| - | - | - |
| **TCA** | The UTC timestamp when the two objects are closest. | UTC |
| **MISS\_DISTANCE** | Overall separation distance between objects at TCA. | m |
| **COLLISION\_PROBABILITY** | Statistical probability of collision. | Dimensionless, from `0.0` to `1.0` |
| **RELATIVE\_SPEED** | Magnitude of relative velocity. | m/s |
| **Covariance terms** | The lower-triangular uncertainty matrix for each object. | See [Covariance Matrix](#covariance-matrix) |

## Object Data Requirements

Each object block in an importable CDM must contain the following:

| Requirement | What to Include |
| - | - |
| **Object identity** | `OBJECT_DESIGNATOR`, `OBJECT_NAME`, and `INTERNATIONAL_DESIGNATOR` when available. |
| **State vector** | `X`, `Y`, `Z`, `X_DOT`, `Y_DOT`, and `Z_DOT`, with units in `km` and `km/s`. |
| **Reference frame** | `REF_FRAME`, such as `EME2000`. |
| **Covariance method** | `COVARIANCE_METHOD`, such as `CALCULATED`, when covariance data is provided. Include it for both objects. |
| **Covariance matrix** | All 21 lower-triangular covariance terms for the object. Do not omit the position-velocity or velocity-velocity terms. |

## Covariance Matrix

The covariance matrix has 21 independent lower-triangular terms for each object. Include every term in the following groups:

| Matrix Block | Required Terms | Unit |
| - | - | - |
| **Position-position** | `CR_R`, `CT_R`, `CT_T`, `CN_R`, `CN_T`, `CN_N` | `m**2` |
| **Position-velocity** | `CRDOT_R`, `CRDOT_T`, `CRDOT_N`, `CTDOT_R`, `CTDOT_T`, `CTDOT_N`, `CNDOT_R`, `CNDOT_T`, `CNDOT_N` | `m**2/s` |
| **Velocity-velocity** | `CRDOT_RDOT`, `CTDOT_RDOT`, `CTDOT_TDOT`, `CNDOT_RDOT`, `CNDOT_TDOT`, `CNDOT_NDOT` | `m**2/s**2` |

## Common Use Cases

* **Conjunction assessment**: Share close-approach predictions for collision-risk analysis.
* **Collision avoidance**: Provide the state and uncertainty data used to evaluate a conjunction.
* **STM exchange**: Transfer a conjunction prediction between a tracking provider and a spacecraft operator.

<Info>
  See the complete [CCSDS 508.0-B-1 CDM standard](https://ccsds.org/Pubs/508x0b1e2c2.pdf) for the authoritative format definition.
</Info>

## Worked Example

The following KVN example is complete and can be used as a starting point. It includes `COVARIANCE_METHOD` and all 21 covariance terms for both objects.

```text theme={null}
CCSDS_CDM_VERS = 1.0
CREATION_DATE = 2024-06-15T12:30:00.000
ORIGINATOR = SPACE-TRACK
MESSAGE_FOR = ISS (ZARYA)
MESSAGE_ID = SPACE-TRACK_CDM_001

COMMENT This is a complete example. All timestamps are UTC.

TCA = 2024-06-20T14:30:45.500
MISS_DISTANCE = 847.5 [m]
RELATIVE_SPEED = 14500.0 [m/s]
RELATIVE_POSITION_R = 125.3 [m]
RELATIVE_POSITION_T = -623.7 [m]
RELATIVE_POSITION_N = 498.2 [m]
RELATIVE_VELOCITY_R = -1.25 [m/s]
RELATIVE_VELOCITY_T = 14499.5 [m/s]
RELATIVE_VELOCITY_N = 0.85 [m/s]
START_SCREEN_PERIOD = 2024-06-20T14:00:00.000
STOP_SCREEN_PERIOD = 2024-06-20T15:00:00.000
SCREEN_VOLUME_FRAME = RTN
SCREEN_VOLUME_SHAPE = ELLIPSOID
SCREEN_VOLUME_X = 50000.0 [m]
SCREEN_VOLUME_Y = 50000.0 [m]
SCREEN_VOLUME_Z = 50000.0 [m]
SCREEN_ENTRY_TIME = 2024-06-20T14:29:30.000
SCREEN_EXIT_TIME = 2024-06-20T14:31:30.000
COLLISION_PROBABILITY = 5.678E-05
COLLISION_PROBABILITY_METHOD = FOSTER-1992

OBJECT = OBJECT1
OBJECT_DESIGNATOR = 25544
CATALOG_NAME = SATCAT
OBJECT_NAME = ISS (ZARYA)
INTERNATIONAL_DESIGNATOR = 1998-067A
OBJECT_TYPE = PAYLOAD
OPERATOR_CONTACT_POSITION = Flight Director
OPERATOR_ORGANIZATION = NASA
OPERATOR_PHONE = +1-281-483-0000
OPERATOR_EMAIL = flightdirector@nasa.gov
EPHEMERIS_NAME = JSC EPHEMERIS
COVARIANCE_METHOD = CALCULATED
MANEUVERABLE = YES
ORBIT_CENTER = EARTH
REF_FRAME = EME2000
GRAVITY_MODEL = EGM-96: 36D 36O
ATMOSPHERIC_MODEL = JACCHIA 70 DCA
N_BODY_PERTURBATIONS = MOON,SUN
SOLAR_RAD_PRESSURE = YES
EARTH_TIDES = YES
INTRACK_THRUST = NO

COMMENT Object 1 State Vector
X = 6778.137 [km]
Y = 0.0 [km]
Z = 0.0 [km]
X_DOT = 0.0 [km/s]
Y_DOT = 7.668 [km/s]
Z_DOT = 0.0 [km/s]

COMMENT Object 1 Covariance Matrix RTN
CR_R = 4.142E+01 [m**2]
CT_R = 5.461E+01 [m**2]
CT_T = 2.345E+02 [m**2]
CN_R = -3.456E+00 [m**2]
CN_T = 1.234E+01 [m**2]
CN_N = 9.876E+01 [m**2]
CRDOT_R = -3.878E-02 [m**2/s]
CRDOT_T = 5.213E-02 [m**2/s]
CRDOT_N = -1.234E-03 [m**2/s]
CRDOT_RDOT = 6.789E-05 [m**2/s**2]
CTDOT_R = 5.678E-02 [m**2/s]
CTDOT_T = -4.321E-02 [m**2/s]
CTDOT_N = 2.345E-03 [m**2/s]
CTDOT_RDOT = -1.234E-05 [m**2/s**2]
CTDOT_TDOT = 8.765E-05 [m**2/s**2]
CNDOT_R = 1.111E-03 [m**2/s]
CNDOT_T = -2.222E-03 [m**2/s]
CNDOT_N = 3.333E-03 [m**2/s]
CNDOT_RDOT = 4.444E-06 [m**2/s**2]
CNDOT_TDOT = -5.555E-06 [m**2/s**2]
CNDOT_NDOT = 6.666E-06 [m**2/s**2]

OBJECT = OBJECT2
OBJECT_DESIGNATOR = 43567
CATALOG_NAME = SATCAT
OBJECT_NAME = COSMOS 2251 DEB
INTERNATIONAL_DESIGNATOR = 2009-043FG
OBJECT_TYPE = DEBRIS
EPHEMERIS_NAME = NORAD TLE
COVARIANCE_METHOD = CALCULATED
MANEUVERABLE = N/A
ORBIT_CENTER = EARTH
REF_FRAME = EME2000

COMMENT Object 2 State Vector
X = 6778.260 [km]
Y = 0.125 [km]
Z = -0.498 [km]
X_DOT = 0.001 [km/s]
Y_DOT = 7.669 [km/s]
Z_DOT = -0.001 [km/s]

COMMENT Object 2 Covariance Matrix RTN
CR_R = 8.234E+02 [m**2]
CT_R = 1.567E+02 [m**2]
CT_T = 5.678E+03 [m**2]
CN_R = -2.345E+01 [m**2]
CN_T = 3.456E+02 [m**2]
CN_N = 4.567E+02 [m**2]
CRDOT_R = -7.890E-01 [m**2/s]
CRDOT_T = 1.234E+00 [m**2/s]
CRDOT_N = -5.678E-02 [m**2/s]
CRDOT_RDOT = 9.012E-04 [m**2/s**2]
CTDOT_R = 1.111E+00 [m**2/s]
CTDOT_T = -2.222E+00 [m**2/s]
CTDOT_N = 3.333E-01 [m**2/s]
CTDOT_RDOT = -4.444E-04 [m**2/s**2]
CTDOT_TDOT = 5.555E-03 [m**2/s**2]
CNDOT_R = 6.666E-02 [m**2/s]
CNDOT_T = -7.777E-02 [m**2/s]
CNDOT_N = 8.888E-02 [m**2/s]
CNDOT_RDOT = 9.999E-05 [m**2/s**2]
CNDOT_TDOT = -1.111E-04 [m**2/s**2]
CNDOT_NDOT = 2.222E-04 [m**2/s**2]
```

<Note>
  Save the example with the `.cdm` extension before uploading it. Replace the primary object's identifiers with a spacecraft registered in your VALAR fleet; otherwise the file can be structurally valid but cannot be linked to a spacecraft during import.
</Note>

## Importing a CDM in VALAR

1. Open **Conjunctions** at `/conjunctions/current`.
2. Click **Import** to open the **Import Alerts** dialog.
3. Drag and drop one or more `.cdm` files into the upload area, or click **Drag and drop files here or click to browse**.
4. Confirm that the primary object in each file matches a registered spacecraft by NORAD ID or COSPAR ID.
5. Click **Import**.

If the file is structurally incomplete, VALAR rejects it without importing a partial conjunction. Regenerate the CDM with complete metadata, state vectors, and covariance terms instead of filling missing uncertainty values with zeros.

## Differences Between CDM and Other Formats

| Attribute | CDM | [OPM](/file-formats/opm) | [OEM](/file-formats/oem) |
| - | - | - | - |
| **Temporal Scope** | One conjunction event at a TCA. | One spacecraft state at one epoch. | A time-ordered trajectory. |
| **Primary Content** | Two-object close-approach data, state vectors, and covariance. | One spacecraft state vector with optional elements and maneuvers. | Multiple spacecraft state vectors with optional covariance. |
| **Primary Use** | Conjunction assessment and collision-risk analysis. | State-vector exchange and import. | Ephemeris exchange and propagation. |

## Related Pages

* [Conjunction classification](/features/conjunction-classification): Review conjunction criticality and risk categories.
* [Conjunction computation](/features/conjunction-computation): Compute conjunction events from spacecraft states.
* [File format overview](/file-formats/overview): Compare the orbital and mission file formats supported by VALAR.


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