Skip to main content

spacelab_frames/
lib.rs

1//! Reference frames, in the type system.
2//!
3//! Every existing implementation of this — SOFA, ERFA, `sofars`, and the rest —
4//! hands you a bare 3×3 matrix and trusts you to remember what it connects. The
5//! two most expensive bug classes in the field follow directly: composing a chain
6//! in the wrong order, and applying a transform to the wrong frame's vector.
7//!
8//! Both are compile-time preventable, and here they are prevented:
9//!
10//! ```compile_fail
11//! # use spacelab_frames::{Rotation, Gcrf, Itrf, Teme};
12//! # fn get<A: spacelab_frames::Frame, B: spacelab_frames::Frame>() -> Rotation<A, B> { unimplemented!() }
13//! let a: Rotation<Teme, Itrf> = get();
14//! let b: Rotation<Gcrf, Itrf> = get();
15//! let _ = a * b; // the chain does not join: Itrf is not Gcrf
16//! ```
17//!
18//! All of it erases at monomorphization. A [`Rotation`] is a `Mat3` and nothing
19//! more.
20//!
21//! # Velocity is not a vector you rotate
22//!
23//! A [`Rotation`] applies to a [`Position`]. Only a [`Transform`] applies to a
24//! [`StateVector`], because moving a velocity between rotating frames requires the
25//! `ω × r` term. Forgetting it costs 465 m/s at the equator, looks plausible, and
26//! is among the most repeated mistakes in the field. Here the type system will not
27//! let you forget: there is no `Mul<StateVector<A>> for Rotation<A, B>`.
28//!
29//! # Batch shape
30//!
31//! Precession, nutation, Earth rotation and polar motion are functions of the epoch
32//! alone — not of the satellite. Over 10⁴ satellites and 10⁵ epochs the frame chain
33//! is evaluated 10⁵ times, not 10⁹, provided it is hoisted. [`teme_to_itrf_into`]
34//! writes into a caller-provided slice for exactly that reason: the four orders of
35//! magnitude are won by a `Vec`, before any thread or lane is considered.
36
37#![cfg_attr(not(any(test, feature = "std")), no_std)]
38
39mod cio;
40#[cfg(any(feature = "std", test))]
41mod cio_fast;
42mod polar_motion;
43mod rotation;
44mod teme;
45
46pub use cio::{cirs_to_tirs, gcrf_to_cirs, gcrf_to_itrf, gcrf_to_itrf_into, tirs_to_itrf};
47#[cfg(any(feature = "std", test))]
48pub use cio_fast::CioInterpolator;
49pub use polar_motion::{pef_to_itrf, tio_locator};
50pub use rotation::{
51    Cirs, Frame, Gcrf, Itrf, Pef, Position, Rotation, StateVector, Teme, Tirs, Transform, Velocity,
52};
53pub use teme::{EARTH_ROTATION_RATE, Orientation, teme_to_itrf, teme_to_itrf_into, teme_to_pef};