lox-space 0.1.0-alpha.48

The Lox toolbox for space mission analysis and design
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

// SPDX-FileCopyrightText: 2025 Helge Eichhorn <git@helgeeichhorn.de>
//
// SPDX-License-Identifier: MPL-2.0

use crate::frames::{
    dynamic::{DynFrame, UnknownFrameError},
    traits::ReferenceFrame,
};
use lox_frames::rotations::DynRotationError;
use pyo3::{
    PyErr, PyResult, create_exception,
    exceptions::{PyException, PyValueError},
    prelude::*,
    pyclass, pymethods,
};

/// PyO3 error wrapper for [`lox_frames::dynamic::UnknownFrameError`].
pub struct PyUnknownFrameError(pub UnknownFrameError);

impl From<PyUnknownFrameError> for PyErr {
    fn from(err: PyUnknownFrameError) -> Self {
        PyValueError::new_err(err.0.to_string())
    }
}

create_exception!(
    lox_space,
    FrameTransformationError,
    PyException,
    "Python exception raised when a frame transformation cannot be performed."
);

/// PyO3 error wrapper for [`lox_frames::rotations::DynRotationError`].
pub struct PyDynRotationError(pub DynRotationError);

impl From<PyDynRotationError> for PyErr {
    fn from(err: PyDynRotationError) -> Self {
        FrameTransformationError::new_err(err.0.to_string())
    }
}

/// Represents a reference frame for positioning and transformations.
///
/// Reference frames define coordinate systems for expressing positions and
/// velocities. Lox supports both inertial (non-rotating) and rotating frames.
///
/// Supported frames:
///
/// - **ICRF**: International Celestial Reference Frame (inertial)
/// - **J2000** / **EME2000**: J2000 Mean Equator and Equinox (inertial)
/// - **CIRF**: Celestial Intermediate Reference Frame
/// - **TIRF**: Terrestrial Intermediate Reference Frame
/// - **ITRF**: International Terrestrial Reference Frame (Earth-fixed)
/// - **MOD**, **TOD**, **PEF**: Equinox-based frames (default: IERS1996,
///   e.g., ``MOD(IERS2003)``, ``TOD(IERS2010)``)
/// - **TEME**: True Equator Mean Equinox (SGP4/TLE)
/// - **Body-fixed frames**: IAU_EARTH, IAU_MOON, IAU_MARS, etc.
///
/// Args:
///     abbreviation: Frame abbreviation (e.g., "ICRF", "ITRF", "IAU_MOON").
///
/// Raises:
///     ValueError: If the frame abbreviation is not recognized.
#[pyclass(name = "Frame", module = "lox_space", frozen, from_py_object)]
#[pyo3(eq)]
#[derive(Debug, Clone, Default, Eq, PartialEq)]
pub struct PyFrame(pub DynFrame);

#[pymethods]
impl PyFrame {
    #[new]
    fn new(abbreviation: &str) -> PyResult<Self> {
        Ok(Self(abbreviation.parse().map_err(PyUnknownFrameError)?))
    }

    fn __getnewargs__(&self) -> (String,) {
        (self.abbreviation(),)
    }

    /// Return the full name of this reference frame.
    ///
    /// Returns:
    ///     The descriptive name (e.g., "International Celestial Reference Frame").
    fn name(&self) -> String {
        self.0.name()
    }

    /// Return the abbreviation of this reference frame.
    ///
    /// Returns:
    ///     The short abbreviation (e.g., "ICRF", "ITRF").
    fn abbreviation(&self) -> String {
        self.0.abbreviation()
    }

    /// Return the string representation of this frame.
    pub fn __repr__(&self) -> String {
        format!("Frame(\"{}\")", self.0.abbreviation())
    }
}

impl TryFrom<&Bound<'_, PyAny>> for PyFrame {
    type Error = PyErr;

    fn try_from(value: &Bound<'_, PyAny>) -> Result<Self, Self::Error> {
        if let Ok(frame) = value.extract::<PyFrame>() {
            return Ok(frame);
        }
        if let Ok(name) = value.extract::<&str>() {
            return Ok(Self(name.parse().map_err(PyUnknownFrameError)?));
        }
        Err(PyValueError::new_err(
            "'frame' argument must be a string or a 'Frame' instance",
        ))
    }
}