Crate skymath

Expand description

§skymath

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

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

Feature	Type	Default	Effect
`serde`	Cargo feature	off	Derives `Serialize`/`Deserialize` on all public types.

§License

Licensed under the Apache License, Version 2.0.

Modules§

angle: Angle primitives and sexagesimal parsing/formatting.
constellation: Constellation identification from the IAU constellation boundaries.
coords: Equatorial coordinates, spherical geometry, and precession.
error: Error type for skymath.
frames: Sky frame conversions: equatorial ↔ galactic and equatorial ↔ ecliptic.
guide: Guide
moon: Lunar position, separation, illumination, rise/set, and moon-avoidance.
observer: Observer-local quantities: site location, hour angle, alt-azimuth, airmass, refraction, parallactic angle, and transit/altitude crossings.
sun: Solar position and twilight times.
time: Time scales: Julian dates, FITS DATE-OBS strings, Julian epochs, and sidereal time.

Structs§

Angle: A unit-aware angle, stored internally in radians.
Ecliptic: An ecliptic-frame position (mean ecliptic and equinox of date).
Equatorial: An equatorial sky position (right ascension, declination) tagged with an Epoch. After construction, ra ∈ [0, 360)° and dec ∈ [-90, 90]°.
Galactic: A galactic-frame position (IAU J2000 definition).
Horizontal: A horizontal (alt-azimuth) position. Azimuth is measured from North through East (N = 0°, E = 90°), normalized to [0°, 360°).
Location: An observing site: latitude, east-positive longitude, and elevation.
SexaStyle: Formatting control for sexagesimal output.
TangentOffset: A sky-tangent offset decomposed into East and North components.

Enums§

Constellation: One of the 88 IAU constellations.
CrossingOutcome: Outcome of an altitude-threshold crossing query for a fixed target over the day around a transit.
Epoch: The reference epoch of a sky position.
Error: Everything that can go wrong constructing or parsing skymath values.
ParseMode: How permissive sexagesimal parsing is.
Separator: Separator used in formatted sexagesimal output.
Twilight: A twilight definition: how far below the geometric horizon the Sun must sit for the sky to count as dark.
TwilightOutcome: Outcome of a twilight query for one night.

Constants§

ARCSEC_PER_RADIAN: Exact number of arcseconds in one radian.

Functions§

airmass: Relative airmass for an apparent altitude — Kasten & Young (1989), accurate to ~1% above 5° and well-behaved to the horizon. ≈1.0 at zenith, ≈38 at the horizon.
alt_az: Horizontal position of target for an observer, ported from astro-math’s spherical-triangle formulation (geometric altitude — no refraction). The target is precessed to the epoch of at internally.
altitude_crossings: When target rises above and sets below threshold altitude, around the transit nearest night_of — the analytic solution cos H₀ = (sin h₀ − sin φ sin δ) / (cos φ cos δ) (geometric altitude, no refraction; apply refraction_true_to_apparent’s inverse to the threshold first if apparent-altitude semantics are wanted).
apply_offset: Apply an East/North offset to a position: travel the great circle whose initial bearing is the offset’s position angle for the offset’s arc length (spherical destination-point formula). Inverse of tangent_offset.
constellation: The constellation containing an equatorial coordinate.
datetime_to_mjd: Modified Julian Date of a timezone-naive instant (taken as UTC). Inverse of mjd_to_datetime.
format_date_obs: Format a date/time back to the FITS civil form (YYYY-MM-DDThh:mm:ss[.fff]), dropping a zero sub-second part. Inverse of parse_date_obs.
format_dec: Format an angle as signed sexagesimal degrees (declination/latitude), e.g. +41:16:09.00. The sign is always present; -0° keeps its minus sign.
format_ra: Format an angle as sexagesimal right ascension (hours), wrapped to [0h, 24h), e.g. 06:30:00.00.
from_ecliptic: Equatorial (J2000) position of mean-ecliptic-of-date coordinates at instant at. Inverse of to_ecliptic.
from_galactic: Equatorial (J2000) position of galactic coordinates. Inverse of to_galactic.
gmst: Greenwich Mean Sidereal Time, normalized to [0h, 24h). Feeds lst at an observer’s longitude.
hour_angle: Hour angle of target (LST − of-date RA), normalized to (-180°, +180°]; positive west of the meridian. The target is precessed to the epoch of at first, so J2000 coordinates are compared against of-date sidereal time correctly.
jd_to_mjd: Convert a Julian Date to a Modified Julian Date. Inverse of mjd_to_jd.
julian_date: Julian Date of an instant; the offset is folded in (UTC internally).
julian_epoch_of: The Julian epoch of an instant, e.g. Epoch::OfDate(2026.52…) for mid-July 2026. Feeds precess when moving an Equatorial position to “tonight”.
lst: Local Sidereal Time at an east-positive longitude, normalized to [0h, 24h). lst(at, lon) == gmst(at) + lon (wrapped).
lunar_separation: Great-circle separation between the topocentric Moon and target at an instant. The target is precessed to the epoch of date internally, matching the observer-module semantics.
mjd_to_datetime: Timezone-naive UTC instant of a Modified Julian Date. Inverse of datetime_to_mjd.
mjd_to_jd: Convert a Modified Julian Date to a Julian Date. Inverse of jd_to_mjd.
moon_avoidance_lorentzian: The classic moon-avoidance Lorentzian (ACP/Berry): the required minimum target–Moon separation at at, largest at full Moon and relaxing with lunar age:
moon_crossings: When the topocentric Moon rises above and sets below threshold altitude, around the lunar transit nearest night_of (moving-body iteration of the analytic solver; the Moon moves ~13°/day). Matches astroplan within ±3 min.
moon_distance_km: Moon–Earth centre distance in kilometres.
moon_illumination: Illuminated fraction of the Moon’s disk, k = (1 + cos i) / 2 ∈ [0, 1], derived from moon_phase_angle.
moon_phase_angle: The Moon’s phase angle i (Sun–Moon–Earth angle, Meeus ch. 48 exact form): 0° at full Moon, 180° at new. Feeds moon_illumination and moon_avoidance_lorentzian.
moon_position: Geocentric lunar position (equatorial, epoch of date).
moon_position_topocentric: Topocentric lunar position for an observer (equatorial, epoch of date) — Meeus ch. 40 parallax correction with WGS-84-flattened site coordinates. The shift from moon_position (geocentric) can reach ~61′ (the Moon’s horizontal parallax).
parallactic_angle: Parallactic angle q = atan2(sin H, tan φ cos δ − sin δ cos H) in (-180°, +180°]: 0 at transit (for δ < φ), negative east of the meridian, positive west — the position angle of the zenith measured at the target. The target is precessed to the epoch of at internally.
parse_date_obs: Parse a FITS civil date/time (YYYY-MM-DD[Thh:mm:ss[.fff]]), timezone-naive; a date-only value means midnight. Quoted card values and surrounding whitespace are tolerated. FITS strings carry no offset — bridge to OffsetDateTime with parse_date_obs(s)?.assume_utc(). Inverse of format_date_obs.
parse_dec: Parse a declination (or latitude/longitude) string into an Angle.
parse_ra: Parse a right ascension string into an Angle.
position_angle: Position angle from from to to, measured East of North, in [0, 360)°.
precess: Precess a position to another epoch using IAU 1976 precession.
refraction_apparent_to_true: True (geometric) altitude from an apparent one — Bennett (1982), standard conditions (1010 hPa, 10 °C), accurate to ~0.1′. Approximate inverse of refraction_true_to_apparent.
refraction_true_to_apparent: Apparent altitude from a true (geometric) one — Sæmundsson (1986), the standard inverse companion to refraction_apparent_to_true, same standard conditions.
separation: Great-circle angular separation between two positions (haversine form).
sun_position: Apparent geocentric solar position (equatorial, epoch of date). Feeds twilight and crate::moon_phase_angle internally.
tangent_offset: Decompose the great-circle arc from from to to into East/North components via separation and position angle (robust polar form — never divides by the cosine of the separation). Inverse of apply_offset.
to_ecliptic: Ecliptic coordinates (mean ecliptic of date) of an equatorial position at instant at. The position is precessed to the epoch of date first. Inverse of from_ecliptic.
to_galactic: Galactic coordinates of an equatorial position. Positions at another epoch are precessed to J2000 first (the rotation constants are J2000). Inverse of from_galactic.
transit: The meridian transit of target nearest to near (upper culmination, hour angle 0), found analytically from the sidereal rate.
twilight: Dusk and dawn instants for the night whose solar lower culmination is nearest night_of, at the darkness level kind.

Type Aliases§

Result: Convenience alias for Result<T, Error>.

Crate skymath

Crate skymath Copy item path

§skymath

§Install

§Usage

§Configuration

§License

Modules§

Structs§

Enums§

Constants§

Functions§

Type Aliases§

Crate skymath