brahe 1.4.0

Brahe is a modern satellite dynamics library for research and engineering applications designed to be easy-to-learn, high-performance, and quick-to-deploy. The north-star of the development is enabling users to solve meaningful problems and answer questions quickly, easily, and correctly.
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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

/*!
 * Core trait and utilities for tessellation algorithms
 *
 * Defines the [`Tessellator`] trait that all tessellation implementations must
 * satisfy, plus helper functions for reading tile metadata properties.
 */

use std::collections::HashMap;

use serde_json::Value as JsonValue;

use crate::access::location::{AccessibleLocation, PolygonLocation};
use crate::utils::errors::BraheError;

/// Core trait for tessellation algorithms.
///
/// Implementations divide geographic locations into rectangular tiles
/// suitable for satellite imaging collection. Each tile is returned as a
/// [`PolygonLocation`] with metadata properties describing the tile geometry.
pub trait Tessellator: Send + Sync {
    /// Tessellate a location into rectangular tiles.
    ///
    /// # Arguments
    /// * `location` - The target location to tessellate
    ///
    /// # Returns
    /// Vector of [`PolygonLocation`] tiles with metadata properties
    fn tessellate(
        &self,
        location: &dyn AccessibleLocation,
    ) -> Result<Vec<PolygonLocation>, BraheError>;

    /// Tessellate multiple locations.
    ///
    /// Default implementation iterates and tessellates each location individually.
    ///
    /// # Arguments
    /// * `locations` - Slice of locations to tessellate
    ///
    /// # Returns
    /// Vector of tile vectors, one per input location
    fn tessellate_batch(
        &self,
        locations: &[&dyn AccessibleLocation],
    ) -> Result<Vec<Vec<PolygonLocation>>, BraheError> {
        locations.iter().map(|l| self.tessellate(*l)).collect()
    }

    /// Human-readable name of the tessellation algorithm.
    fn name(&self) -> &str;
}

/// Extract a tile property as f64 from a PolygonLocation's properties.
pub(crate) fn get_tile_property_f64(props: &HashMap<String, JsonValue>, key: &str) -> Option<f64> {
    props.get(key).and_then(|v| v.as_f64())
}

/// Extract a tile property as a 3-element array from a PolygonLocation's properties.
pub(crate) fn get_tile_property_vec3(
    props: &HashMap<String, JsonValue>,
    key: &str,
) -> Option<[f64; 3]> {
    props.get(key).and_then(|v| {
        v.as_array().and_then(|arr| {
            if arr.len() == 3 {
                Some([arr[0].as_f64()?, arr[1].as_f64()?, arr[2].as_f64()?])
            } else {
                None
            }
        })
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use nalgebra::Vector3;

    use crate::access::location::PointLocation;

    /// Mock tessellator for testing the trait interface
    struct MockTessellator;

    impl Tessellator for MockTessellator {
        fn tessellate(
            &self,
            _location: &dyn AccessibleLocation,
        ) -> Result<Vec<PolygonLocation>, BraheError> {
            let vertices = vec![
                Vector3::new(10.0, 50.0, 0.0),
                Vector3::new(11.0, 50.0, 0.0),
                Vector3::new(11.0, 51.0, 0.0),
                Vector3::new(10.0, 51.0, 0.0),
            ];
            let tile = PolygonLocation::new(vertices)?;
            Ok(vec![tile])
        }

        fn name(&self) -> &str {
            "MockTessellator"
        }
    }

    #[test]
    fn test_mock_tessellator() {
        let tess = MockTessellator;
        let point = PointLocation::new(10.5, 50.5, 0.0);
        let tiles = tess.tessellate(&point).unwrap();
        assert_eq!(tiles.len(), 1);
        assert_eq!(tess.name(), "MockTessellator");
    }

    #[test]
    fn test_tessellate_batch_default() {
        let tess = MockTessellator;
        let p1 = PointLocation::new(10.5, 50.5, 0.0);
        let p2 = PointLocation::new(20.0, 40.0, 0.0);
        let locations: Vec<&dyn AccessibleLocation> = vec![&p1, &p2];
        let results = tess.tessellate_batch(&locations).unwrap();
        assert_eq!(results.len(), 2);
        assert_eq!(results[0].len(), 1);
        assert_eq!(results[1].len(), 1);
    }

    #[test]
    fn test_tessellate_with_point_and_polygon() {
        let tess = MockTessellator;

        let point = PointLocation::new(10.0, 50.0, 0.0);
        let tiles = tess.tessellate(&point).unwrap();
        assert_eq!(tiles.len(), 1);

        let vertices = vec![
            Vector3::new(10.0, 50.0, 0.0),
            Vector3::new(11.0, 50.0, 0.0),
            Vector3::new(11.0, 51.0, 0.0),
            Vector3::new(10.0, 51.0, 0.0),
        ];
        let polygon = PolygonLocation::new(vertices).unwrap();
        let tiles = tess.tessellate(&polygon).unwrap();
        assert_eq!(tiles.len(), 1);
    }
}