🥮 mooncakes.io
    Sign in

    moonsatkit

    Pure MoonBit toolkit for satellite orbit data, pass prediction, and visualization

    satellite
    orbit
    tle
    sgp4
    geodesy
    visualization
    Download zip
    Version
    0.1.0
    License
    Apache-2.0
    Repository
    Last updated
    2 months ago
    Downloads
    20

    No dependencies

    #MoonSatKit

    MoonSatKit is a pure MoonBit toolkit for satellite orbit data, TLE parsing, time handling, near-earth SGP4 propagation, ground-station observation, and pass prediction.

    Project status: near-earth propagation phase. The package now includes a pure MoonBit near-earth SGP4 implementation validated against the Vallado 00005 reference state, plus SGP4-based ground-station pass prediction. Deep-space SDP4, full official vector coverage, and export formats remain planned work.

    #Current scope

    • TLE parsing with raw field preservation
    • TLE checksum validation
    • SGP4 input metadata decoding: mean-motion derivatives and BSTAR
    • Pure MoonBit near-earth SGP4 propagation with WGS-72 constants and drag terms
    • Explicit Sgp4Elements initialization boundary with deep-space rejection
    • UTC civil timestamp parsing, formatting, Julian day conversion, and elapsed seconds
    • Leap-year and month-length helpers
    • TLE orbital-element decoding with structured numeric errors
    • Two-body Kepler preview propagation with ECI-style position and velocity output
    • GMST, ECI/ECEF position and state transforms with Earth rotation correction
    • WGS-84 geodetic and ground-station coordinate conversion
    • Ground-station ENU observation with azimuth, elevation, range, range rate, and horizon status
    • Two-body preview pass prediction with AOS, TCA, LOS, and maximum elevation
    • SGP4 pass prediction with one-second event refinement and ordered visibility windows
    • JSON serialization for orbit states and pass windows
    • Low-precision geocentric Sun position and right-ascension/declination output
    • Geometric sunlit, penumbra, and umbra classification for propagated states
    • CSV pass-window export and GeoJSON SGP4 ground-track export
    • Named two-line/three-line TLE catalog parsing and multi-satellite pass prediction
    • Pass duration reporting and browser catalog-pass JSON API
    • Vector, station, observation, and pass data types
    • CLI entry points for TLE validation and timestamp parsing

    #Quick start

    Parse a timestamp:

    moon run cmd/main -- time parse 2026-08-11T12:00:00

    Validate a TLE:

    moon run cmd/main -- tle validate "1 25544U 98067A   26224.50000000  .00001234  00000-0  12345-4 0  9991" "2 25544  51.6416  21.0000 0001234 123.4567 234.5678 15.50000000"

    Propagate a TLE at a UTC instant:

    moon run cmd/main -- propagate "<line1>" "<line2>" --at 2026-08-23T12:00:00

    Predict SGP4 passes for a ground station:

    moon run cmd/main -- passes "<line1>" "<line2>" --station 31.2304,121.4737,10 --from 2026-08-23T12:00:00 --hours 24 --min-elevation 10 --format json

    Export a GeoJSON ground track:

    moon run cmd/main -- track "<line1>" "<line2>" --from 2026-08-23T12:00:00 --seconds 86400 --step 60

    Classify satellite illumination and print a machine-readable report:

    moon run cmd/main -- eclipse "<line1>" "<line2>" --at 2026-08-23T12:00:00

    Predict pass windows from a validated TLE:

    let tle = @moonsatkit.validate_tle(line1, line2).unwrap()
let station : @moonsatkit.GroundStation = {
  latitude_deg: 31.2304,
  longitude_deg: 121.4737,
  altitude_m: 10.0,
}
let passes = @moonsatkit.predict_passes_sgp4(
  tle,
  station,
  from=start,
  duration_hours=24,
  minimum_elevation_deg=10.0,
).unwrap()

    predict_passes remains the transparent two-body compatibility API.

    Parse a named TLE catalog and predict all satellite passes:

    let catalog = @moonsatkit.parse_tle_catalog(catalog_text).unwrap()
let catalog_passes = @moonsatkit.predict_catalog_passes_sgp4(
  catalog, station, from=start, duration_hours=24, minimum_elevation_deg=10.0,
).unwrap()
let json = @moonsatkit.catalog_pass_windows_to_json(catalog_passes)
    predict_passes_sgp4 uses the near-earth SGP4 propagator and returns integer-second AOS, TCA, and LOS timestamps plus the maximum elevation. Deep-space TLEs currently return UnsupportedOrbit until SDP4 is added.

    Export results:

    let json = @moonsatkit.pass_windows_to_json(passes)
let csv = @moonsatkit.pass_windows_to_csv(passes)
let track = @moonsatkit.track_geojson_sgp4(tle, start, 86400, 60).unwrap()

    #Acceptance scope

    The current acceptance baseline covers TLE checksum validation, near-earth SGP4 propagation, WGS-84 coordinate conversion, ground-station observation, one-second-refined pass windows, JSON/CSV/GeoJSON export, and geometric illumination classification. The reproducible checklist is in docs/ACCEPTANCE.md.

    #Roadmap

    • Deep-space SDP4 propagation and broader official SGP4 vector coverage
    • Higher-fidelity TEME, Earth orientation, and time-scale refinements
    • Multi-satellite catalogs, Doppler estimates, and constellation coverage

    #Development

    moon info
moon fmt
moon test -p oilleelssq-wq/moonsatkit --target all --deny-warn

    #License

    MoonSatKit is licensed under the Apache License 2.0.

    #Browser preview

    The repository includes a lightweight browser console at web/index.html. It renders a real MoonSatKit-generated GeoJSON track and SGP4 pass-window sample for Vallado catalog object 00005, with a timeline scrubber, TLE checksum validation, station marker, pass-elevation filter, GeoJSON import, and track download.

    Start a local preview from the repository root:

    cd web
python -m http.server 4173

    Then open http://127.0.0.1:4173/. The page loads the self-contained MoonBit JS adapter at web/moonsatkit.js, which exposes TLE validation, SGP4 GeoJSON track generation, single-satellite pass-window prediction, and named catalog pass prediction through moon_sat_catalog_passes_json. Edit the TLE, station, start time, duration, or sample step and press 计算轨迹 to run the real near-earth SGP4 implementation in the browser. The bundled Vallado 00005 data remains available as the initial view and fallback demonstration when the adapter cannot be loaded. Rebuild the adapter after MoonBit changes with ./web/build.ps1 (or run moon build web/wasm --target js --release and copy _build/js/release/build/web/wasm/wasm.js to web/moonsatkit.js).

    CatalogPassWindow

    source
    pub(all) struct CatalogPassWindow {
      name : String
      catalog_number : Int
      window : PassWindow
    } derive(Eq, 
    Debug    )

    A pass window associated with one entry in a TLE catalog.

    EcefState

    source
    pub(all) struct EcefState {
      epoch : UtcDateTime
      position_km : Vector3
      velocity_km_s : Vector3
    }

    A state expressed in the Earth-fixed frame, in kilometres and kilometres per second.

    EclipseState

    source
    pub(all) enum EclipseState {
      Sunlit
      Penumbra
      Umbra
    } derive(Eq, 
    Debug    )

    A geometric illumination classification for a satellite state.

    Penumbra means the satellite is inside the Earth's partial shadow. The model is intentionally geometric and is suitable for visibility analysis, not for spacecraft power or mission-safety decisions.

    EclipseState::to_string

    source
    fn EclipseState::to_string(self : EclipseState) -> String

    GeodeticPosition

    source
    pub(all) struct GeodeticPosition {
      latitude_deg : Double
      longitude_deg : Double
      altitude_km : Double
    }

    A WGS-84 geodetic position. Longitude is positive east and altitude is in kilometres.

    GroundStation

    source
    pub(all) struct GroundStation {
      latitude_deg : Double
      longitude_deg : Double
      altitude_m : Double
    } derive(Eq, 
    Debug    )

    Observation

    source
    pub(all) struct Observation {
      azimuth_deg : Double
      elevation_deg : Double
      range_km : Double
      range_rate_km_s : Double
      above_horizon : Bool
    } derive(Eq, 
    Debug    )

    OrbitElements

    source
    pub(all) struct OrbitElements {
      catalog_number : Int
      epoch : UtcDateTime
      epoch_julian_day : Double
      inclination_deg : Double
      right_ascension_deg : Double
      eccentricity : Double
      argument_of_perigee_deg : Double
      mean_anomaly_deg : Double
      mean_motion_rev_per_day : Double
      mean_motion_rad_per_min : Double
    }

    Numerical orbital elements decoded from a TLE.

    The elements retain the TLE epoch and angular fields in conventional units. They are suitable for the two-body preview propagator and form the input boundary for the future SGP4 implementation.

    OrbitState

    source
    pub(all) struct OrbitState {
      epoch : UtcDateTime
      position_km : Vector3
      velocity_km_s : Vector3
    }

    An inertial state expressed in kilometres and kilometres per second.

    PassWindow

    source
    pub(all) struct PassWindow {
      aos : UtcDateTime
      tca : UtcDateTime
      los : UtcDateTime
      maximum_elevation_deg : Double
    } derive(Eq, 
    Debug    )

    PassWindow::duration_seconds

    source
    fn PassWindow::duration_seconds(self : PassWindow) -> Int

    Return the visible duration of a pass in integral seconds.

    SatError

    source
    pub(all) struct SatError {
      kind : SatErrorKind
      line : Int
      fragment : String
      message : String
    } derive(Eq, 
    Debug    )

    SatError::new

    source
    fn SatError::new(kind : SatErrorKind, message : String, fragment? : String, line? : Int) -> SatError

    SatError::to_string

    source
    fn SatError::to_string(self : SatError) -> String

    SatErrorKind

    source
    pub(all) enum SatErrorKind {
      EmptyInput
      InvalidFormat
      InvalidChecksum
      InvalidCatalogNumber
      MismatchedCatalogNumber
      InvalidTleNumber
      UnsupportedOrbit
      PropagationError
      InvalidDateTime
      OutOfRange
    } derive(Eq, 
    Debug    )

    Sgp4Elements

    source
    pub(all) struct Sgp4Elements {
      catalog_number : Int
      epoch : UtcDateTime
      epoch_julian_day : Double
      inclination_rad : Double
      right_ascension_rad : Double
      eccentricity : Double
      argument_of_perigee_rad : Double
      mean_anomaly_rad : Double
      mean_motion_rad_per_min : Double
      mean_motion_first_derivative_rev_per_day2 : Double
      mean_motion_second_derivative_div2_rev_per_day3 : Double
      bstar : Double
    }

    Numerical TLE fields required to initialize an SGP4 propagator.

    Angles are stored in radians. The derivative fields retain the TLE conventions: revolutions per day squared and the second derivative divided by two in revolutions per day cubed. BSTAR is dimensionless.

    SunPosition

    source
    pub(all) struct SunPosition {
      position_km : Vector3
      distance_km : Double
      distance_au : Double
      right_ascension_deg : Double
      declination_deg : Double
    } derive(Eq, 
    Debug    )

    Low-precision geocentric Sun position for visibility and eclipse analysis.

    The position is expressed in the same J2000-style inertial frame used by the library's ECI helpers. Distance is in kilometres, right ascension and declination are in degrees, and distance_au is retained for diagnostics.

    Tle

    source
    pub(all) struct Tle {
      line1 : String
      line2 : String
      catalog_number : Int
      epoch : String
      inclination : String
      right_ascension : String
      eccentricity : String
      argument_of_perigee : String
      mean_anomaly : String
      mean_motion : String
      mean_motion_first_derivative : String
      mean_motion_second_derivative : String
      bstar : String
      checksum_line1_ok : Bool
      checksum_line2_ok : Bool
    } derive(Eq, 
    Debug    )

    TleCatalogEntry

    source
    pub(all) struct TleCatalogEntry {
      name : String
      tle : Tle
    } derive(Eq, 
    Debug    )

    A named TLE entry loaded from a two-line or three-line catalog.

    UtcDateTime

    source
    pub(all) struct UtcDateTime {
      year : Int
      month : Int
      day : Int
      hour : Int
      minute : Int
      second : Int
    } derive(Compare, Eq, 
    Debug    )

    UtcDateTime::add_seconds

    source
    fn UtcDateTime::add_seconds(self : UtcDateTime, seconds : Int) -> UtcDateTime

    Add an integral number of seconds to a UTC civil timestamp.

    This helper is intentionally calendar-based, so pass-search event times remain integer-second UTC values without relying on a platform date API.

    UtcDateTime::next_second

    source
    fn UtcDateTime::next_second(self : UtcDateTime) -> UtcDateTime

    UtcDateTime::to_string

    source
    fn UtcDateTime::to_string(self : UtcDateTime) -> String

    Vector3

    source
    pub(all) struct Vector3 {
      x : Double
      y : Double
      z : Double
    } derive(Eq, 
    Debug    )

    Vector3::add

    source
    fn Vector3::add(self : Vector3, other : Vector3) -> Vector3

    Vector3::dot

    source
    fn Vector3::dot(self : Vector3, other : Vector3) -> Double

    Vector3::scale

    source
    fn Vector3::scale(self : Vector3, factor : Double) -> Vector3

    Vector3::sub

    source
    fn Vector3::sub(self : Vector3, other : Vector3) -> Vector3

    Vector3::to_string

    source
    fn Vector3::to_string(self : Vector3) -> String

    Vector3::zero

    source
    fn Vector3::zero() -> Vector3

    catalog_pass_windows_to_csv

    source
    fn catalog_pass_windows_to_csv(passes : Array[CatalogPassWindow]) -> String

    Serialize catalog pass windows as CSV.

    catalog_pass_windows_to_json

    source
    fn catalog_pass_windows_to_json(passes : Array[CatalogPassWindow]) -> String

    Serialize catalog pass windows with the satellite name and NORAD number.

    days_in_month

    source
    fn days_in_month(year : Int, month : Int) -> Int

    ecef_to_eci

    source
    fn ecef_to_eci(position : Vector3, instant : UtcDateTime) -> Vector3

    Rotate an Earth-fixed position into the inertial frame at the given instant.

    ecef_to_eci_state

    source
    fn ecef_to_eci_state(state : EcefState) -> OrbitState

    Convert an Earth-fixed state to an inertial state, including Earth rotation.

    ecef_to_geodetic

    source
    fn ecef_to_geodetic(position : Vector3) -> GeodeticPosition

    Convert Earth-fixed Cartesian coordinates to WGS-84 geodetic coordinates.

    eci_to_ecef

    source
    fn eci_to_ecef(position : Vector3, instant : UtcDateTime) -> Vector3

    Rotate an ECI position into the Earth-fixed frame at the given instant.

    eci_to_ecef_state

    source
    fn eci_to_ecef_state(state : OrbitState) -> EcefState

    Convert an inertial state to an Earth-fixed state, including Earth rotation.

    eclipse_report_to_json

    source
    fn eclipse_report_to_json(tle : Tle, instant : UtcDateTime) -> Result[String, SatError]

    Serialize a propagated state together with its illumination status.

    eclipse_state

    source
    fn eclipse_state(state : OrbitState) -> EclipseState

    Classify whether a satellite is sunlit, in the penumbra, or in the umbra.

    The Earth is modelled as a sphere with WGS-84's equatorial radius. The solar umbra and penumbra are treated as cones whose apexes are determined by the apparent Sun and Earth radii.

    eclipse_state_sgp4

    source
    fn eclipse_state_sgp4(tle : Tle, instant : UtcDateTime) -> Result[EclipseState, SatError]

    Propagate a TLE and classify its illumination at the requested instant.

    geodetic_to_ecef

    source
    fn geodetic_to_ecef(value : GeodeticPosition) -> Vector3

    Convert a WGS-84 geodetic position to Earth-fixed Cartesian coordinates.

    gmst_angle

    source
    fn gmst_angle(julian_day_value : Double) -> Double

    Compute Greenwich mean sidereal time from an astronomical Julian Day.

    The result is a normalized angle in radians in the range [0, 2*pi).

    greenwich_mean_sidereal_time

    source
    fn greenwich_mean_sidereal_time(value : UtcDateTime) -> Double

    Compute Greenwich mean sidereal time for a UTC timestamp.

    ground_station_to_ecef

    source
    fn ground_station_to_ecef(station : GroundStation) -> Vector3

    Convert a ground station height in metres to Earth-fixed Cartesian coordinates.

    is_leap_year

    source
    fn is_leap_year(year : Int) -> Bool

    julian_day

    source
    fn julian_day(value : UtcDateTime) -> Double

    Convert a UTC civil timestamp to the astronomical Julian Day.

    The result follows the standard convention where 2000-01-01 12:00:00 UTC is 2451545.0. This helper uses the proleptic Gregorian calendar.

    observe

    source
    fn observe(state : OrbitState, station : GroundStation) -> Observation

    Compute an observation from an inertial state by applying the ECI/ECEF transformation at the state's epoch first.

    observe_ecef

    source
    fn observe_ecef(state : EcefState, station : GroundStation) -> Observation

    Compute the local ENU observation of an Earth-fixed satellite state.

    Azimuth is measured clockwise from north in degrees. Elevation is measured above the local horizon. Range and range rate use kilometres and kilometres per second, respectively.

    orbit_elements

    source
    fn orbit_elements(tle : Tle) -> Result[OrbitElements, SatError]

    Decode the numerical orbital elements represented by a parsed TLE.

    orbit_state_geodetic

    source
    fn orbit_state_geodetic(state : OrbitState) -> GeodeticPosition

    Convert an inertial state position to WGS-84 geodetic coordinates.

    orbit_state_to_json

    source
    fn orbit_state_to_json(state : OrbitState) -> String

    Serialize an inertial orbit state as a small JSON object.

    parse_tle

    source
    fn parse_tle(line1 : String, line2 : String) -> Result[Tle, SatError]

    Parse a two-line element set and preserve the raw orbital fields.

    parse_tle_catalog

    source
    fn parse_tle_catalog(text : String) -> Result[Array[TleCatalogEntry], SatError]

    Parse a catalog containing either repeated two-line TLE records or the common three-line format with a satellite name before each pair.

    Blank lines are ignored. Named records keep their display name; unnamed records receive a NORAD name.

    parse_utc_datetime

    source
    fn parse_utc_datetime(text : String) -> Result[UtcDateTime, SatError]

    pass_windows_to_csv

    source
    fn pass_windows_to_csv(passes : Array[PassWindow]) -> String

    Serialize pass windows as a UTF-8 CSV document with a header row.

    pass_windows_to_json

    source
    fn pass_windows_to_json(passes : Array[PassWindow]) -> String

    Serialize pass windows as a JSON array.

    predict_catalog_passes_sgp4

    source
    fn predict_catalog_passes_sgp4(entries : Array[TleCatalogEntry], station : GroundStation, from : UtcDateTime, duration_hours : Int, minimum_elevation_deg : Double) -> Result[Array[CatalogPassWindow], SatError]

    Predict SGP4 pass windows for every entry in a named TLE catalog.

    predict_passes

    source
    fn predict_passes(tle : Tle, station : GroundStation, from : UtcDateTime, duration_hours : Int, minimum_elevation_deg : Double) -> Result[Array[PassWindow], SatError]

    Predict visibility windows using the current two-body preview propagator.

    The returned event times have one-second resolution. AOS and LOS are refined by elevation-threshold bisection, while TCA is selected by a one-second search around the sampled elevation maximum.

    predict_passes_from_elements

    source
    fn predict_passes_from_elements(elements : OrbitElements, station : GroundStation, from : UtcDateTime, duration_hours : Int, minimum_elevation_deg : Double) -> Result[Array[PassWindow], SatError]

    Predict visibility windows from already-decoded orbital elements.

    predict_passes_sgp4

    source
    fn predict_passes_sgp4(tle : Tle, station : GroundStation, from : UtcDateTime, duration_hours : Int, minimum_elevation_deg : Double) -> Result[Array[PassWindow], SatError]

    Predict visibility windows with the near-earth SGP4 propagator.

    This API is the high-fidelity counterpart to predict_passes, which keeps its transparent two-body preview behavior for compatibility. A deep-space TLE returns UnsupportedOrbit because SDP4 is not implemented yet.

    propagate_sgp4

    source
    fn propagate_sgp4(tle : Tle, instant : UtcDateTime) -> Result[OrbitState, SatError]

    Propagate a near-earth TLE with the Vallado SGP4 model.

    The returned state uses kilometres and kilometres per second. Deep-space orbits return UnsupportedOrbit until SDP4 is added.

    propagate_two_body

    source
    fn propagate_two_body(elements : OrbitElements, instant : UtcDateTime) -> Result[OrbitState, SatError]

    Propagate an orbit with a two-body Kepler approximation.

    This is an intentionally transparent preview model. It does not include the perturbations and Earth orientation terms required for SGP4 accuracy.

    seconds_between

    source
    fn seconds_between(start : UtcDateTime, end : UtcDateTime) -> Double

    Return the elapsed seconds from start to end.

    sgp4_elements

    source
    fn sgp4_elements(tle : Tle) -> Result[Sgp4Elements, SatError]

    Decode the complete numerical TLE input boundary for a future SGP4 propagator. This function does not propagate a state.

    sun_position_eci

    source
    fn sun_position_eci(instant : UtcDateTime) -> SunPosition

    Compute a low-precision geocentric Sun position.

    This follows the compact NOAA-style solar position equations. It is accurate enough for eclipse classification and educational visualisation; high-precision ephemerides remain outside the current scope.

    track_geojson_sgp4

    source
    fn track_geojson_sgp4(tle : Tle, from : UtcDateTime, duration_seconds : Int, step_seconds : Int) -> Result[String, SatError]

    Export a near-earth SGP4 ground track as a GeoJSON LineString.

    Coordinates use the GeoJSON order [longitude, latitude, altitude_km]. The interval is sampled inclusively, so a zero-duration track contains one coordinate. Deep-space TLEs return UnsupportedOrbit.

    validate_tle

    source
    fn validate_tle(line1 : String, line2 : String) -> Result[Tle, SatError]

    Parse and require both TLE checksum digits to be valid.

    vallado_00005_line1

    source
    let vallado_00005_line1 : String

    Public SGP4 verification sample distributed with Vallado's CelesTrak test material. MoonSatKit currently uses it for TLE parsing and checksum tests; propagation checks can reuse the same fixture once SGP4 state vectors land.

    vallado_00005_line2

    source
    let vallado_00005_line2 : String

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io