skymath

Rust library of planning-grade astronomy math for astrophotography tooling.

docs.rs · Guide

• Angles — typed Angle (degrees, radians, hours, arcminutes, arcseconds), normalization helpers, exact conversion constants.
• Equatorial coordinates — validated RA/Dec (Equatorial) with epoch (J2000 or of-date); sexagesimal parsing (parse_ra, parse_dec) in strict and lenient modes, and sexagesimal formatting (format_ra, format_dec).
• Spherical geometry — great-circle separation, position_angle, tangent-plane offsets (tangent_offset) and their inverse (apply_offset).
• Precession — IAU-1976 conversion between J2000 and equinox-of-date via precess.
• Coordinate frames — equatorial ↔ galactic (to_galactic, from_galactic) and equatorial ↔ ecliptic (to_ecliptic, from_ecliptic).
• Time — MJD/JD ↔ calendar conversions (datetime_to_mjd, mjd_to_datetime), MJD ↔ JD (jd_to_mjd, mjd_to_jd), FITS DATE-OBS parsing and formatting (parse_date_obs, format_date_obs), Julian epoch from a date (julian_epoch_of), Greenwich and local sidereal time (gmst, lst).
• Observer-local quantities — observer Location (with sexagesimal parsing via Location::parse), hour_angle, alt-azimuth transforms, airmass, atmospheric refraction (refraction_apparent_to_true, refraction_true_to_apparent), parallactic_angle, and transit / altitude-crossing times.
• Sun & Moon — solar (sun_position) and lunar positions (moon_position, geocentric and topocentric; moon_distance_km), twilight times (civil / nautical / astronomical, with typed polar-night and midnight-sun outcomes in TwilightOutcome), moonrise/set, lunar separation from a target, Moon illumination and phase angle, and the moon-avoidance Lorentzian criterion.
• Constellations — which of the 88 IAU Constellations contains a coordinate (Roman 1987 boundary table at B1875.0), as a typed value with official abbreviations ("UMi") and Latin names ("Ursa Minor", "Boötes").

Precision is planning-grade (≈1 arcminute) throughout: suitable for framing, scheduling, and session planning, not for telescope pointing or astrometry. Apparent-place corrections (nutation, aberration, proper motion) are out of scope by design.

Install

cargo add skymath time

The time crate supplies the OffsetDateTime instants every ephemeris function takes.

Usage

use skymath::{alt_az, altitude_crossings, separation, Angle, CrossingOutcome,
              Equatorial, Location, ParseMode};
use time::OffsetDateTime;

fn main() -> skymath::Result<()> {
    let site = Location::parse("+52 05 32", "+004 18 27", 6.0)?;
    let m31 = Equatorial::parse_j2000("00:42:44.3", "+41:16:09", ParseMode::Strict)?;

    let now = OffsetDateTime::now_utc();
    let h = alt_az(m31, now, &site);
    println!("M31: alt {:.1}°, az {:.1}°", h.altitude.degrees(), h.azimuth.degrees());

    match altitude_crossings(m31, Angle::from_degrees(30.0), now, &site) {
        CrossingOutcome::Crosses { rise, set } => println!("above 30°: {rise} → {set}"),
        outcome => println!("{outcome:?}"),
    }
    Ok(())
}

cargo run --example plan_night walks the full planning flow (site + target parsing, constellation lookup, precession to tonight, sidereal time, airmass, parallactic angle, transit and window, twilight, and Moon separation and illumination). See the guide for a task-by-task walkthrough, or docs.rs for the full API reference.

Instants are time crate types; functions taking an OffsetDateTime fold the offset in internally, so passing local civil time cannot skew results.

Configuration

License

Licensed under the Apache License, Version 2.0.