gmat-czml 0.1.0

Convert GMAT (and any canonical-schema) trajectories to CZML for browser-based 3D Cesium visualization.

gmat-czml

Convert GMAT (and any canonical-schema) trajectories to CZML for browser-based 3D Cesium visualization.

What this is

gmat-czml takes an already-computed trajectory — a state history in the canonical state-series form — and turns it into a CZML document a Cesium client can animate: an orbit path, a ground track, a point and a label, on a clock synthesized from the trajectory's own time span. The input is not GMAT-specific — any producer that yields the canonical schema (a TLE propagation, a transfer, a read ephemeris) works through one call.

It does not propagate, integrate, or solve orbits, and it does not render: the producer is the source of geometric truth, and Cesium is the renderer. gmat-czml is the bridge between them.

Quick start

from gmat_czml import to_czml

czml = to_czml(trajectory, ground_track=True)
czml.save("orbit.czml")          # load in any Cesium viewer
# czml.to_json() / czml.to_dict()  # in-memory, no file needed

trajectory is a canonical state-series DataFrame, an orbit-formats Ephemeris, a file orbit-formats can read (OEM, GMAT report, SP3, STK ephemeris, …), or an iterable of these for a multi-object scene. See the gallery for runnable examples.

The canonical input

A trajectory is one row per sample with the columns and DataFrame.attrs metadata below — the shape orbit-formats emits and a headless GMAT run produces, so it flows in with no reshaping.

Columns	Epoch (datetime), X Y Z (required); VX VY VZ (optional)
Metadata	object_name, central_body, coordinate_system, time_scale (required), units, interpolation, interpolation_degree

The reference frame and time scale are required, never guessed; everything else has a sensible default. A malformed input raises a typed error naming exactly what is wrong. Full contract: the schema reference.

Supported Cesium clients

The output is a standard CZML document — any Cesium client renders it:

Client	How
CesiumJS	Cesium.CzmlDataSource.load(czml) in the core library
Cesium ion	stream/host assets and imagery; load the document with the same call
Resium	the CesiumJS components for React

No setup beyond a Cesium viewer is needed; for a zero-install look, drop a .czml onto Cesium Sandcastle.

What this is not

• Not a propagation or astrodynamics library — it converts a trajectory, never computes one.
• Not a CZML renderer — it produces CZML; Cesium renders it.
• Not a format parser — reading trajectory files is delegated to the org's format-I/O library.
• Not a hosted service — viewing happens in your own Cesium client.

Installation

pip install gmat-czml

gmat-czml requires Python 3.10, 3.11, or 3.12.

Documentation

Full docs — getting started, the schema, per-entity conversion, the CLI, the gallery, and the API reference — at https://astro-tools.github.io/gmat-czml/. The design rationale lives in the design decisions.

Development

git clone https://github.com/astro-tools/gmat-czml.git
cd gmat-czml
uv sync --all-groups

See CONTRIBUTING.md for the branch / PR / test workflow.

Licence

MIT. See LICENSE.