File formats

Who this section is for. Anyone moving data between this software and another tool. It assumes you know what you want to exchange and need to know exactly what the bytes mean.

What each format is for

Format	Direction	Purpose
Constellation JSON	Read and written	The design document: satellites, shells, and initial orbits
CZML	Written	Time-dynamic scene for the CesiumJS globe viewer
CCSDS OEM	Read and written	Ephemeris interchange with other flight-dynamics tools
TLE	Read	Import of cataloged objects
SP3	Read	Precise ephemeris products
GeoJSON	Written	Coverage grids for mapping tools
CSV	Written	Ephemeris and contact tables for analysis

Choosing between them

The most common mistake is using a visualization format for interchange.

CZML describes a scene over time. It is not a precise interchange format, it carries no frame or time-system declaration in the way OEM does, and handing it to another organization as a trajectory is a mistake. Use OEM for that.

The unit trap

CZML uses meters. Every other format uses kilometers.

The same state, exported both ways from one run:


CZML : 6928137.0
OEM  : 6928.137

Nothing about either file announces the difference, and a mixed-up conversion produces positions wrong by a factor of 1000, which places a low Earth orbit satellite well beyond the Moon or inside the Earth depending on direction.

CZML uses meters because the CesiumJS convention is meters. Everything else uses kilometers because that is the working unit of orbital mechanics.

Format	Position unit	Velocity unit
CZML	m	m/s
CCSDS OEM	km	km/s
CSV ephemeris	km	km/s
Constellation JSON	km (semi-major axis)	n/a
SP3	km	km/s, where present

The ordering trap

GeoJSON coordinates are [longitude, latitude], in that order. Every other surface here lists latitude first.

That ordering is required by the GeoJSON specification, not a choice made here, and it is the standard cause of a map with everything transposed into the wrong hemisphere.

Provenance travels with the data, or it does not

Format	Carries frame	Carries time system	Carries epoch
CCSDS OEM	Yes, `REF_FRAME`	Yes, `TIME_SYSTEM`	Yes, per record
CZML	Partly, `referenceFrame`	No	Yes, as an offset base
CSV ephemeris	No	No	No, elapsed seconds only
TLE	Implicit, TEME	Implicit, UTC	Yes, in the element set
Constellation JSON	No	No	No

A CSV of positions carries no frame, no time system, and no absolute epoch. Its time_s column is elapsed seconds from a scenario start that lives somewhere else.

Export the scenario metadata alongside any CSV you intend to keep. Without it the file is a table of numbers that cannot be reproduced or checked, which is exactly what makes a result impossible to audit months later.

OEM is the opposite case, and that is why it is the interchange format: frame, time system, and epoch are all declared in the file itself.