mako-sgp4 0.3.0

Theory-based SGP4 propagator for TLEs and OMMs
Documentation

mako-sgp4

Build status Crates.io Documentation License: MIT

A Rust crate to parse and propagate General Perturbation Element Sets (GPs) using Simplified Perturbations Models (SGP4 / SDP4). Both Two-Line Elements (TLEs) and Orbit Mean-Elements Messages (OMMs) are supported. This code is implemented using the theory and equations found in History of Analytical Orbit Modeling in the U.S. Space Surveillance System by Hoots et al. Practical implementation adjustments were made based on Revisiting Spacetrack Report #3: Rev 3 by Vallado et al.

The name mako-sgp4 pays tribute to the Shortfin Mako Shark, the fastest shark species. The speed and efficiency of the SGP4 propagator make this an apt name.

Accuracy

The SGP4 propagator is a mean orbital elements propagator. At any point in time, its accuracy to the true position of an orbiting body is typically on the order of hundreds of meters to kilometers. Thus, it is not intended for high-precision operations.

mako-sgp4 is verified against the standard Vallado test cases and additional test cases generated with python-sgp4 (found in test/). In all propagation cases, mako-sgp4 agrees with both reference implementations to within 1 millimeter in position and 1 millimeter per second in velocity, per component. This is agreement with the reference SGP4 implementations, not with the true orbit.

Documentation

The full API is on docs.rs. The crate requires Rust 1.85 or newer (edition = "2024"). The math specification documents every equation the crate implements, with references to the source code, and the style guide covers contribution conventions.

# Unit tests, doctests, and default features (XML / JSON / CSV)
cargo test

# TLE and OMM KVN only
cargo test --no-default-features

# Rustdoc
cargo doc --no-deps --open

Usage

Add mako-sgp4 to your projects:

cargo add mako-sgp4

Propagate a TLE to its epoch with this example:

use mako_sgp4::{from_tle_string, sgp4_prop_delta};

fn main() {
    // Define the TLE string
    let tle_string = "\
    ISS (ZARYA)
    1 25544U 98067A   08264.51782528 -.00002182 -00100-2 -11606-4 0  2921
    2 25544  51.6416 247.4627 0006703 130.5360 325.0288 15.72125391563537
    ";

    // Parse the TLE string into an SGP4 propagator. Returns a vector of SGP4 propagators
    let tle_sgp4s = from_tle_string(tle_string).unwrap();

    // Propagate the TLE propagator to the epoch time. Returns a StateVector struct.
    let state = sgp4_prop_delta(&tle_sgp4s[0], 0.0).unwrap();

    // Print the result in TEME coordinates.
    println!(
        "{}\nr_TEME = [{:.3}, {:.3}, {:.3}] km\nv_TEME = [{:.3}, {:.3}, {:.3}] km/s",
        tle_sgp4s[0].gp.common_name,
        state.r_x,
        state.r_y,
        state.r_z,
        state.v_x,
        state.v_y,
        state.v_z
    );
}

SGP4 propagation is accomplished with one of the following functions:

  • sgp4_prop_delta - Propagates delta_t minutes from epoch
  • sgp4_prop_datetime - Propagates to a specified UTC datetime

Example code lives in examples/ and can be run with:

cargo run --example propagate_tle

Features

TLE and OMM KVN parsing are always available. XML, JSON, and CSV OMM support are optional Cargo features but on by default.

Feature Formats
(none / core) TLE, OMM KVN
xml OMM XML
json OMM JSON
csv OMM CSV 
cargo add mako-sgp4                                           # TLE, KVN, XML, JSON, CSV
cargo add mako-sgp4 --no-default-features                     # TLE and KVN only, no 3rd party dependencies
cargo add mako-sgp4 --no-default-features --features json,csv # Exclude XML

WebAssembly

mako-sgp4 compiles to WebAssembly so it can run in a web browser. The wasm/ directory contains JavaScript bindings for TLE and OMM KVN parsing, propagation, and ground tracks. Build them with wasm-pack:

cd wasm
wasm-pack build --target web --profile wasm-release

import init, { Satellite } from './mako_sgp4_wasm.js';
await init();

const sat = new Satellite(tleText);
const state = sat.propagate(60);               // [x, y, z, vx, vy, vz] 60 min after epoch, TEME [km, km/s]
const track = sat.trackGeodetic(0, 1440, 1);   // [lat, lon, alt, ...] for one day [deg, deg, km]

See the wasm README for setup and the full API.

Future Work

  • Fit state data to GP
  • Python wrapper

References