Frame Graph¶

use brahe as bh;
use brahe::ccsds::OEM;
use brahe::frames::{CelestialFrame, ReferenceFrame};
use nalgebra::Vector6;

fn main() {
    bh::clear_object_registry();

    // OEM::register_for is a one-liner: it converts the ephemeris segment to
    // a trajectory, wraps it as a state provider, and registers it under a
    // name.
    let oem = OEM::from_file("test_assets/ccsds/oem/OEMExample5.txt").unwrap();
    oem.register_for("ISS").unwrap();
    println!("Registered objects: {:?}", bh::registered_objects());

    // The registered object anchors ReferenceFrame::RTN("ISS"): its origin is the
    // object's GCRF position, interpolated from the OEM ephemeris.
    let epc = oem.segments[0].metadata.start_time + 300.0;
    let x_rtn_origin = bh::state_frame_to_frame(
        ReferenceFrame::RTN("ISS"),
        CelestialFrame::GCRF,
        epc,
        Vector6::zeros(),
    )
    .unwrap();
    let p = x_rtn_origin.fixed_rows::<3>(0).into_owned() / 1e3;
    println!("\nISS position at {}: {:.3?} km", epc, p.as_slice());

    bh::clear_object_registry();
    println!("\nExample validated successfully!");
}

use brahe as bh;
use brahe::attitude::{EulerAxis, Quaternion, ToAttitude};
use brahe::constants::AngleFormat;
use brahe::frames::{BodyFrame, CelestialFrame, ReferenceFrame};
use brahe::time::{Epoch, TimeSystem};
use brahe::utils::BraheError;
use brahe::utils::state_providers::SStateProvider;
use nalgebra::{SVector, Vector6};

/// A state provider returning a fixed state at every epoch, for registering
/// a spacecraft as an object.
struct ConstantProvider(Vector6<f64>);
impl SStateProvider for ConstantProvider {
    fn state(&self, _epoch: Epoch) -> Result<Vector6<f64>, BraheError> {
        Ok(self.0)
    }
}

fn main() {
    bh::clear_frame_registry();
    bh::clear_object_registry();

    // A body or orbit-relative frame that carries no object name is only a
    // label: it describes a set of axes and nothing more. Binding it to a
    // named object makes it resolvable against that object's registered data.
    // A celestial frame such as CelestialFrame::GCRF is resolvable on its own.
    // The family constructors (ReferenceFrame::RTN, ReferenceFrame::SC_BODY,
    // ReferenceFrame::CSS, ...) bind an object directly, while an unbound
    // label converts from a bare BodyFrame or OrbitRelativeFrame.
    let rtn = ReferenceFrame::RTN("SC");
    let unbound: ReferenceFrame = BodyFrame::SCBody(None).into();
    println!(
        "{}: bound={}, object={:?}",
        rtn,
        rtn.is_bound(),
        rtn.object()
    );
    println!(
        "{}: bound={}, object={:?}",
        unbound,
        unbound.is_bound(),
        unbound.object()
    );

    // Register "SC" as an object: any SStateProvider, in GCRF. An OEM's
    // `register_for` one-liner (see the CCSDS OEM docs) registers the same
    // way.
    let oe = SVector::<f64, 6>::new(
        bh::constants::R_EARTH + 500e3,
        0.001,
        97.8,
        15.0,
        30.0,
        45.0,
    );
    let x_sc = bh::state_koe_to_eci(oe, AngleFormat::Degrees);
    bh::register_object("SC", ConstantProvider(x_sc), CelestialFrame::GCRF).unwrap();

    // Register SC's body frame and a coarse sun sensor mounted on it. The
    // BodyFrame families (SCBody, CSS, RW, ...) are the values of the SANA
    // spacecraft body reference frame registry:
    // https://sanaregistry.org/r/spacecraft_body_reference_frames/
    // A constant attitude (Quaternion, RotationMatrix, EulerAngle, EulerAxis)
    // registers directly; orientation chains driven by an attitude ephemeris
    // ship in a later release.
    let q_body = Quaternion::new(1.0, 0.0, 0.0, 0.0);
    let q_css = EulerAxis::new(
        nalgebra::Vector3::new(0.0, 1.0, 0.0),
        0.7,
        AngleFormat::Radians,
    )
    .to_quaternion();
    bh::register_frame(ReferenceFrame::SC_BODY("SC"), CelestialFrame::GCRF.into(), q_body).unwrap();
    bh::register_frame(ReferenceFrame::CSS("SC", "1"), ReferenceFrame::SC_BODY("SC"), q_css).unwrap();

    // Route the Sun's GCRF position through GCRF -> SC_BODY -> CSS_1.
    let epc = Epoch::from_date(2024, 3, 1, TimeSystem::UTC);
    let sun_gcrf = bh::sun_position(epc);
    let sun_css =
        bh::position_frame_to_frame(CelestialFrame::GCRF, ReferenceFrame::CSS("SC", "1"), epc, sun_gcrf)
            .unwrap();
    println!("\nSun direction in CSS_1: {:.3?}", sun_css.as_slice());

    // Body frames share their object's origin exactly: routing SC's own
    // position into CSS_1 lands at the origin, with no lever arm applied.
    let sc_pos = x_sc.fixed_rows::<3>(0).into_owned();
    let sc_in_css =
        bh::position_frame_to_frame(CelestialFrame::GCRF, ReferenceFrame::CSS("SC", "1"), epc, sc_pos)
            .unwrap();
    println!(
        "SC origin in CSS_1 (zero lever arm): {:.3?}",
        sc_in_css.as_slice()
    );
    assert!(sc_in_css.norm() < 1e-6);

    // Querying an unregistered link errors with a fix: which frame is
    // missing and the register_frame call that would supply it.
    let err =
        bh::rotation_frame_to_frame(CelestialFrame::GCRF, ReferenceFrame::CSS("SC", "2"), epc).unwrap_err();
    println!("\nMissing-link error: {}", err);

    bh::clear_frame_registry();
    bh::clear_object_registry();
    println!("\nExample validated successfully!");
}

use brahe as bh;
use brahe::frames::{CallbackOrientation, CelestialFrame, OrientationProvider, ReferenceFrame};
use brahe::math::SMatrix3;
use brahe::time::{Epoch, TimeSystem};
use brahe::utils::BraheError;
use brahe::utils::state_providers::SStateProvider;
use nalgebra::Vector6;

/// A state provider returning a fixed state at every epoch, for registering
/// a spacecraft as an object.
struct ConstantProvider(Vector6<f64>);
impl SStateProvider for ConstantProvider {
    fn state(&self, _epoch: Epoch) -> Result<Vector6<f64>, BraheError> {
        Ok(self.0)
    }
}

fn main() {
    bh::clear_frame_registry();
    bh::clear_object_registry();

    let t0 = Epoch::from_date(2024, 3, 1, TimeSystem::UTC);
    let rate = 1.0e-3; // spin rate (rad/s)
    let rotation = move |epc: Epoch| {
        let dt = epc - t0;
        let (s, c) = (rate * dt).sin_cos();
        Ok(SMatrix3::new(c, s, 0.0, -s, c, 0.0, 0.0, 0.0, 1.0))
    };

    // A rotation-only callback carries no angular velocity, so a state
    // transform through it fails: the velocity transport term is otherwise
    // undefined.
    bh::register_frame(
        ReferenceFrame::SC_BODY("SC"),
        CelestialFrame::GCRF.into(),
        CallbackOrientation::new(rotation, None),
    )
    .unwrap();
    bh::register_object(
        "SC",
        ConstantProvider(Vector6::zeros()),
        CelestialFrame::GCRF,
    )
    .unwrap();

    let epc = t0 + 100.0;
    let x_gcrf = Vector6::new(1.0e3, 2.0e3, 3.0e3, 0.0, 0.0, 0.0);
    let err = bh::state_frame_to_frame(CelestialFrame::GCRF, ReferenceFrame::SC_BODY("SC"), epc, x_gcrf)
        .unwrap_err();
    println!("Rates rule error: {}", err);

    // Re-registering with `with_numerical_rates` wraps the same callback so
    // a missing angular velocity is derived by central differencing the
    // rotation over +/- step/2 seconds; a provider that already returns
    // rates is used unchanged. The state transform then succeeds.
    bh::unregister_frame(&ReferenceFrame::SC_BODY("SC"));
    bh::register_frame(
        ReferenceFrame::SC_BODY("SC"),
        CelestialFrame::GCRF.into(),
        CallbackOrientation::new(rotation, None)
            .with_numerical_rates(1.0)
            .unwrap(),
    )
    .unwrap();
    let x_body =
        bh::state_frame_to_frame(CelestialFrame::GCRF, ReferenceFrame::SC_BODY("SC"), epc, x_gcrf).unwrap();
    println!(
        "\nBody-frame state with numerical rates: {:.6?}",
        x_body.as_slice()
    );

    // Compare against a hand-differenced velocity: with_numerical_rates
    // recovers the transport term from the same central-difference recipe.
    let delta = 0.5;
    let p = x_gcrf.fixed_rows::<3>(0).into_owned();
    let r_plus = rotation(epc + delta).unwrap() * p;
    let r_minus = rotation(epc - delta).unwrap() * p;
    let v_numerical = (r_plus - r_minus) / (2.0 * delta);
    let v_body = x_body.fixed_rows::<3>(3).into_owned();
    assert!((v_body - v_numerical).norm() < 1e-6);

    bh::clear_frame_registry();
    bh::clear_object_registry();
    println!("\nExample validated successfully!");
}