Metadata-Version: 2.4
Name: gmat-czml
Version: 0.1.0
Summary: Convert GMAT (and any canonical-schema) trajectories to CZML for browser-based 3D Cesium visualization.
Project-URL: Homepage, https://github.com/astro-tools/gmat-czml
Project-URL: Repository, https://github.com/astro-tools/gmat-czml
Project-URL: Issues, https://github.com/astro-tools/gmat-czml/issues
Project-URL: Documentation, https://astro-tools.github.io/gmat-czml/
Project-URL: Changelog, https://github.com/astro-tools/gmat-czml/blob/main/CHANGELOG.md
Author: Dimitrije Jankovic
License-Expression: MIT
License-File: LICENSE
Keywords: astrodynamics,cesium,czml,gmat,orbital-mechanics,space,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: czml3<4,>=3.3
Requires-Dist: numpy>=1.24
Requires-Dist: orbit-formats>=0.5
Requires-Dist: pandas>=2.0
Description-Content-Type: text/markdown

# gmat-czml

[![CI](https://github.com/astro-tools/gmat-czml/actions/workflows/ci.yml/badge.svg)](https://github.com/astro-tools/gmat-czml/actions/workflows/ci.yml)
[![Docs](https://github.com/astro-tools/gmat-czml/actions/workflows/docs.yml/badge.svg)](https://astro-tools.github.io/gmat-czml/)
[![PyPI](https://img.shields.io/pypi/v/gmat-czml.svg)](https://pypi.org/project/gmat-czml/)
[![Python versions](https://img.shields.io/pypi/pyversions/gmat-czml.svg)](https://pypi.org/project/gmat-czml/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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](https://github.com/AnalyticalGraphicsInc/czml-writer/wiki/CZML-Structure)
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

```python
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](https://astro-tools.github.io/gmat-czml/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](https://astro-tools.github.io/gmat-czml/schema/).

## Supported Cesium clients

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

| Client | How |
|--------|-----|
| [CesiumJS](https://cesium.com/platform/cesiumjs/) | `Cesium.CzmlDataSource.load(czml)` in the core library |
| [Cesium ion](https://cesium.com/platform/cesium-ion/) | stream/host assets and imagery; load the document with the same call |
| [Resium](https://resium.reearth.io/) | the CesiumJS components for React |

No setup beyond a Cesium viewer is needed; for a zero-install look, drop a `.czml` onto
[Cesium Sandcastle](https://sandcastle.cesium.com/).

## 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](https://cesium.com/) 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

```bash
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](docs/design/decisions.md).

## Development

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for the branch / PR / test workflow.

## Licence

MIT. See [LICENSE](LICENSE).
