supernovas 0.3.0

Safe Rust wrapper around the SuperNOVAS astrometry library
Documentation

SuperNOVAS (Rust)

CI crates.io docs.rs License

Safe Rust bindings to the SuperNOVAS astrometry C library.

SuperNOVAS is a high-precision astrometry library based on NOVAS (Naval Observatory Vector Astrometry Software). This workspace provides two crates:

Crate Description
supernovas-ffi Raw FFI bindings (auto-generated via bindgen)
supernovas Safe, idiomatic Rust wrapper

Features

  • ICRS catalog source → apparent position in any reference frame (ReferenceSystem: ICRS, GCRS, CIRS, equinox-of-date) via CatalogEntry::apparent_in
  • Apparent → horizontal (az/el) projection with Refraction correction
  • Spherical coordinate types: Horizontal, Equatorial, Ecliptic, Galactic
  • Dimensioned scalar types: Angle, TimeAngle, Coordinate, Interval, Pressure, Temperature, ScalarVelocity
  • 3-D vector types: Position, Velocity, with cross-type arithmetic
  • Time from UTC/TT Julian dates and Unix epoch; optional hifitime feature for nanosecond-precision Epoch interop
  • Geodetic and geocentric Observer; Site + Weather
  • CatalogEntry with proper motion, parallax, and radial velocity
  • Full and reduced accuracy modes — full accuracy requires a planetary ephemeris (see below)
  • Planetary ephemeris backends: CalcephEphemeris (calceph feature) and AniseEphemeris (anise feature); or implement PlanetProvider for a custom backend without writing unsafe code
  • no_std + alloc-free by default; opt-in std feature available
  • Optional vendored feature: bundles SuperNOVAS v1.6.0 statically (no system library required)

Quick start

Add the wrapper crate to your Cargo.toml. Enable the vendored feature to build the bundled SuperNOVAS v1.6.0 statically — no system library required:

[dependencies]
supernovas = { version = "0.3", features = ["vendored"] }

If you already have SuperNOVAS ≥ 1.6.0 installed system-wide (e.g. via Nix or a distro package), omit the feature and it will be found via pkg-config:

[dependencies]
supernovas = "0.3"

Example — ICRS to horizontal

Compute the az/el of Vega as seen from Owens Valley Radio Observatory:

use supernovas::{Accuracy, CatalogEntry, Frame, Observer, Site, Time, Weather};

fn main() -> Result<(), Box<dyn core::error::Error>> {
    let vega = CatalogEntry::icrs("Vega", "18:36:56.336".parse()?, "+38:47:01.28".parse()?)?;

    let site = Site::from_degrees(37.234, -118.282, 1222.0)?.with_weather(Weather::standard());
    let observer = Observer::Geodetic(site);

    // JD 2461236.75 UTC, 37 leap seconds
    let time = Time::from_utc_jd(2_461_236.75, 37, 0.0)?;

    let frame = Frame::new(Accuracy::Reduced, &observer, &time)?;
    let horizontal = frame.observe(&vega)?;
    println!("{horizontal}");
    Ok(())
}

Run the bundled example:

cargo run --example icrs_to_horizontal

Building

Requires a C compiler and CMake (for the vendored build). With Nix and direnv, the dev environment is provided automatically via flake.nix.

cargo build
cargo test

Workspace layout

supernovas-ffi/       # -sys crate (bindgen + optional cmake build)
  vendor/supernovas/  # git submodule: upstream SuperNOVAS C source
  build.rs
  wrapper.h
supernovas/           # safe wrapper crate
  src/
  examples/

Remaining work

These are known gaps that will be addressed in future releases:

  • Observer variants: airborne and near-Earth (satellite) observers are not yet wrapped.
  • Solar-system body sources: planets and other ephemeris-driven source types are not yet exposed as first-class Source objects (though a raw PlanetProvider can be installed and Accuracy::Full works end-to-end for stellar sources).
  • Interval timescale: Interval::from_seconds takes a raw novas_timescale FFI enum directly; this will be replaced by a safe Timescale newtype.

Note on AI Usage

Generative AI was used in the production of some portions of this crate, mainly in the generation of unit tests and getting build.rs correct for the ffi layer. All code in this crate was at the very least validated manually by the author, if not written by them.

Upstream attribution

This project wraps SuperNOVAS, a C astrometry library authored by Attila Kovács (@sigmyne), itself derived from the original NOVAS library by the U.S. Naval Observatory.

SuperNOVAS is released into the public domain under The Unlicense. The vendored copy in supernovas-ffi/vendor/supernovas is pinned to upstream v1.6.0 and its full license text is in supernovas-ffi/vendor/supernovas/LICENSE.

License

The Rust source code in this repository (supernovas-ffi and supernovas crates, excluding the vendored C library) is licensed under either of

at your option.