gmat-czml 0.1.0__tar.gz

gmat_czml-0.1.0/.gitattributes

@@ -0,0 +1,5 @@
+# Golden / reference fixtures under tests/data are compared byte-for-byte by the conversion
+# tests. Git's line-ending normalisation (autocrlf on Windows checks out LF as CRLF) would
+# otherwise rewrite them and break those byte-exact assertions, so treat the fixtures as binary
+# — checked out verbatim, identical on every platform.
+tests/data/** -text

gmat_czml-0.1.0/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+# Default reviewer for everything in this repo.
+*   @djankov

gmat_czml-0.1.0/.github/ISSUE_TEMPLATE/bug.yml

@@ -0,0 +1,59 @@
+name: Bug
+description: Report a defect in gmat-czml.
+title: "<short summary>"
+labels: ["type:bug"]
+body:
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: Observed behavior. Include error messages and tracebacks verbatim.
+    validations:
+      required: true
+  - type: textarea
+    id: what_expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Minimal reproduction
+      description: >-
+        Smallest snippet that triggers the bug — the Python (or CLI) call and, if a
+        trajectory fails to convert, the smallest input that reproduces it.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: gmat_czml_version
+    attributes:
+      label: gmat-czml version
+      placeholder: "e.g. 0.1.0, or git sha"
+    validations:
+      required: true
+  - type: input
+    id: python_version
+    attributes:
+      label: Python version
+      placeholder: "e.g. 3.12.3"
+    validations:
+      required: true
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - Windows
+        - macOS
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs
+      description: Relevant output — tracebacks, warnings, pytest output.
+      render: shell

gmat_czml-0.1.0/.github/ISSUE_TEMPLATE/chore.yml

@@ -0,0 +1,25 @@
+name: Chore
+description: Tooling, infra, hygiene, or other non-feature work.
+title: "<short summary>"
+labels: ["type:chore"]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What
+      description: What needs to happen.
+    validations:
+      required: true
+  - type: textarea
+    id: why
+    attributes:
+      label: Why
+      description: Why now. What's blocked or painful without it.
+    validations:
+      required: true
+  - type: textarea
+    id: done
+    attributes:
+      label: Definition of done
+      value: |
+        - [ ]

gmat_czml-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/orgs/astro-tools/discussions
+    about: Open a discussion for usage questions, ideas, or general chat.

gmat_czml-0.1.0/.github/ISSUE_TEMPLATE/convert-failure.yml

@@ -0,0 +1,51 @@
+name: My trajectory does not convert
+description: A trajectory that should convert to CZML fails or renders wrong.
+title: "<short summary>"
+labels: ["type:bug"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        gmat-czml consumes the canonical state-series schema. Most conversion failures come down to
+        the input DataFrame's columns or `attrs`, so please share its shape below.
+  - type: textarea
+    id: what_happened
+    attributes:
+      label: What happened
+      description: The error, the wrong rendering, or the missing entity. Include tracebacks verbatim.
+    validations:
+      required: true
+  - type: textarea
+    id: dataframe_schema
+    attributes:
+      label: Input DataFrame schema
+      description: >-
+        The columns and the `attrs` of the DataFrame you passed — ideally the output of
+        `print(df.columns.tolist()); print(df.attrs); print(df.head())`.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: producer
+    attributes:
+      label: Where the trajectory came from
+      description: >-
+        How the trajectory was produced or read (a GMAT run, a TLE propagation, a read ephemeris
+        file, …) and which file format if any.
+    validations:
+      required: true
+  - type: textarea
+    id: call
+    attributes:
+      label: The call you made
+      description: The `to_czml(...)` or `gmat-czml convert` invocation.
+      render: python
+    validations:
+      required: true
+  - type: input
+    id: gmat_czml_version
+    attributes:
+      label: gmat-czml version
+      placeholder: "e.g. 0.1.0, or git sha"
+    validations:
+      required: true

gmat_czml-0.1.0/.github/ISSUE_TEMPLATE/feature.yml

@@ -0,0 +1,41 @@
+name: Feature
+description: Propose a new capability or a non-trivial change.
+title: "<short summary>"
+labels: ["type:feature"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One or two sentences describing what this feature is.
+    validations:
+      required: true
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: Why this matters. What can't users do today that they should be able to do?
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: >-
+        Concrete, testable checkboxes. An outside reviewer should be able to read these
+        and tell whether the feature is done.
+      value: |
+        - [ ]
+        - [ ]
+    validations:
+      required: true
+  - type: textarea
+    id: out_of_scope
+    attributes:
+      label: Out of scope / non-goals
+      description: What this issue deliberately does not cover. Helps keep scope honest.
+  - type: textarea
+    id: notes
+    attributes:
+      label: Notes
+      description: Design notes, links to the design decisions, references to prior art, open questions.

gmat_czml-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,35 @@
+<!--
+Thanks for contributing to gmat-czml. Keep PRs small and scoped to one issue.
+-->
+
+## Summary
+
+<!-- One or two sentences: what this PR changes and why. -->
+
+Closes #
+
+## Changes
+
+<!-- Short bullet list of the substantive changes. Omit trivia (formatting, imports). -->
+
+-
+
+## Tested with
+
+<!-- Tick what you ran locally. CI will re-run on Ubuntu, Windows, and macOS. -->
+
+- [ ] `pytest -m "not browser"`
+- [ ] `pytest -m browser` (headless CesiumJS)
+- [ ] `ruff check`
+- [ ] `ruff format --check`
+- [ ] `mypy`
+
+## Breaking changes
+
+<!-- "None" if none. Otherwise: what breaks, who is affected, migration notes. -->
+
+None.
+
+## Notes for reviewers
+
+<!-- Optional. Things to look at first, known rough edges, questions for the reviewer. -->

gmat_czml-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,138 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test:
+    name: test (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      # 3 OSes × 3 Python minors. gmat-czml is pure Python, so the matrix is the
+      # platform / interpreter spread. The browser and czml-validation jobs run once
+      # on Ubuntu (their output is platform-independent), so they are excluded here.
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ['3.10', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - name: Install project
+        run: uv sync --all-groups
+      - name: Run pytest
+        run: uv run pytest -m "not browser and not czml" --cov --cov-report=term-missing
+
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run ruff check
+      - run: uv run ruff format --check
+
+  typecheck:
+    name: typecheck
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run mypy
+
+  # Smoke-check that `pip install gmat-czml` (no dev group) imports cleanly. Catches a
+  # dev-only dependency leaking into the default install path.
+  minimal-install:
+    name: minimal install smoke
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install .
+      - run: python -c "import gmat_czml; print(gmat_czml.__version__)"
+
+  # Validate the emitted CZML against the official CZML JSON schema (vendored under
+  # tests/data/czml-schema/) and byte-diff it against the committed golden corpus, on the real
+  # GMAT and TLE producer fixtures.
+  czml-validate:
+    name: CZML validation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run pytest -m czml -v
+
+  # Load the emitted CZML in a real headless CesiumJS client (Playwright + chromium) to catch
+  # valid-but-unrenderable output the schema check alone misses, and assert a correct, animated
+  # orbit path on the real GMAT and TLE producer fixtures.
+  cesium-parse:
+    name: headless CesiumJS parse
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run playwright install --with-deps chromium
+      - run: uv run pytest -m browser -v
+
+  # Validate CITATION.cff against the Citation File Format v1.2.0 schema.
+  citation:
+    name: citation file (cffconvert)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install cffconvert==2.0.0
+      - run: cffconvert --validate -i CITATION.cff

gmat_czml-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,57 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    name: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - run: uv run mkdocs build --strict
+
+  deploy:
+    name: deploy
+    needs: build
+    if: |
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) ||
+      github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv sync --all-groups
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - run: uv run mkdocs gh-deploy --force --no-history

gmat_czml-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build sdist + wheel
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/gmat-czml
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true
+
+  github-release:
+    name: github release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" \
+            --repo "${GITHUB_REPOSITORY}" \
+            --title "${GITHUB_REF_NAME}" \
+            --generate-notes \
+            dist/*

gmat_czml-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+.eggs/
+build/
+dist/
+wheels/
+*.whl
+
+# Environments
+.venv/
+venv/
+env/
+.env
+
+# uv
+.uv-cache/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+
+# Playwright
+test-results/
+playwright-report/
+
+# Docs build
+site/
+.cache/
+
+# Example gallery output (regenerate with the scripts under examples/)
+examples/output/
+
+# IDE / editor
+.vscode/
+.idea/
+*.swp
+.DS_Store

gmat_czml-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

gmat_czml-0.1.0/CHANGELOG.md

@@ -0,0 +1,53 @@
+# Changelog
+
+All notable changes to gmat-czml are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html). Entries are aggregated at release-cut
+time, not per pull request.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-04
+
+First release. gmat-czml takes an already-computed trajectory — a state history in the canonical
+state-series form produced by a headless GMAT run or read by the org's format-I/O library — and
+turns it into a CZML document a Cesium client can animate. It does not propagate, integrate, or
+render: the producer is the source of geometric truth, and Cesium is the renderer.
+
+### Added
+
+- **`to_czml`, the single entry point**, and the `CzmlDocument` it returns. The call accepts 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 any of these for a multi-object
+  scene. The document saves to a `.czml` file (`save`) or comes back in memory (`to_json` /
+  `to_dict`) — no file needed.
+- **The canonical input boundary.** One row per sample (`Epoch`, `X` `Y` `Z` required;
+  `VX` `VY` `VZ` optional) plus `DataFrame.attrs` metadata, with the reference frame and time
+  scale required and never guessed. A malformed input raises a typed `GmatCzmlError` subclass that
+  names exactly what is wrong, rather than failing deep in assembly.
+- **Orbit path.** Each object becomes a Cesium entity carrying four properties — a sampled
+  `position` in metres, a `path`, a `point`, and a `label`. The source's interpolation method and
+  degree pass through to the CZML `interpolationAlgorithm` / `interpolationDegree`
+  (`LAGRANGE` / `HERMITE` / `LINEAR`, defaulting to Lagrange degree 5), and the recognised frame
+  maps to CZML `INERTIAL` or `FIXED`.
+- **Tolerance-bounded decimation.** A cross-track Douglas–Peucker pass drops samples that stay
+  within tolerance of the kept polyline — a `degree + 1` support floor preserves the interpolation
+  curve — so a dense, high-rate ephemeris ships a compact document without visible path error.
+  Epochs travel as one reference epoch plus per-sample second offsets.
+- **Ground track** (opt-in via `ground_track=True`). The sub-satellite point becomes a geodetic
+  polyline that floats at the satellite's own height over the correct ground position, with
+  antimeridian crossings split at an interpolated seam on the dateline. The inertial → Earth-fixed
+  rotation and the WGS84 geodetic projection are delegated to orbit-formats — Earth-only, and a
+  trajectory declared about another central body is rejected rather than mis-projected.
+- **Clock synthesis.** A document clock is synthesized from the trajectory's own epoch span, with
+  the declared time scale converted to the UTC Cesium expects.
+- **Multi-object / multi-segment scenes.** An iterable of trajectories becomes one document, one
+  entity per object, on a single shared clock.
+- **Styling.** A single baked-in `sat-default` style covers every object's point, label, path, and
+  ground track; the `Style` handle is the stable seam later customization plugs into.
+- **`gmat-czml convert` CLI.** A thin driver over `to_czml` — `convert INPUT -o OUTPUT` with
+  `--ground-track`, `--playback-seconds`, and `--style` — whose output is byte-for-byte the
+  document the API produces.
+- **Documentation.** A published docs site — getting started, the schema reference, per-entity
+  conversion, styling, the CLI, an example gallery with rendered output, and the API reference —
+  with the design rationale recorded under `docs/design/`.

gmat_czml-0.1.0/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+message: "If you use gmat-czml in academic work, please cite it using the metadata below."
+title: gmat-czml
+abstract: >-
+  gmat-czml is a permissively-licensed Python library that converts an already-computed
+  trajectory — in the canonical state-series form produced by a headless GMAT run or read by the
+  org's format-I/O library — into CZML for browser-based 3D visualization in Cesium. It maps state
+  ephemerides to an orbit path, renders a ground track, synthesizes a clock,
+  and emits an in-memory or on-disk document; it does not propagate or render.
+type: software
+authors:
+  - given-names: Dimitrije
+    family-names: Jankovic
+version: 0.1.0
+license: MIT
+repository-code: "https://github.com/astro-tools/gmat-czml"
+url: "https://github.com/astro-tools/gmat-czml"
+keywords:
+  - astrodynamics
+  - orbital-mechanics
+  - cesium
+  - czml
+  - visualization
+  - space