Skip to main content

vibe/capability_schema/
geo_geodesy_entries.rs

1//! Geodesy and ephemeris capability schemas (GEO-S1 / R1-V).
2//!
3//! Provides machine schema definitions for all 17 `Geodesy.*` host capability
4//! invocations and unit suffix validation for geodetic, hydrological, and
5//! cartographic quantities.
6
7use super::{EffectClass, HonestyLabel, SchemaArg, SchemaEntry};
8
9/// Canonical sequence of all 17 Geodesy capability invoke IDs.
10pub const GEODESY_INVOKE_IDS: &[&str] = &[
11    "Geodesy.wgs84_inverse",
12    "Geodesy.wgs84_direct",
13    "Geodesy.wgs84_intermediate",
14    "Geodesy.polygon_area_m2",
15    "Geodesy.geodetic_to_ecef",
16    "Geodesy.ecef_to_geodetic",
17    "Geodesy.enu_basis",
18    "Geodesy.parse_coord",
19    "Geodesy.format_mgrs",
20    "Geodesy.crs_transform",
21    "Geodesy.ausgeoid_undulation",
22    "Geodesy.lonlat_to_a5",
23    "Geodesy.a5_to_lonlat",
24    "Geodesy.rtree_query_bbox",
25    "Geodesy.sun_ephemeris",
26    "Geodesy.topographic_insolation",
27    "Geodesy.orbit_propagate",
28];
29
30/// Registered geodetic, hydrological, and cartographic unit tokens.
31pub const GEODESY_UNIT_SUFFIXES: &[&str] = &[
32    "mm", "cm", "m", "km", "nmi", "deg", "rad", "arcmin", "arcsec", "mrad", "m2", "ha", "km2",
33    "m3_s", "mm_hr", "kg_m2_s", "W_m2", "Wh_m2", "pt", "dpi",
34];
35
36/// Returns `true` if `unit` matches any registered geodetic, hydrological, or cartographic unit token.
37pub fn is_geodesy_unit_suffix(unit: &str) -> bool {
38    matches!(
39        unit,
40        "mm" | "cm"
41            | "m"
42            | "km"
43            | "nmi"
44            | "deg"
45            | "rad"
46            | "arcmin"
47            | "arcsec"
48            | "mrad"
49            | "m2"
50            | "ha"
51            | "km2"
52            | "m3_s"
53            | "mm_hr"
54            | "kg_m2_s"
55            | "W_m2"
56            | "Wh_m2"
57            | "pt"
58            | "dpi"
59    )
60}
61
62/// Returns the 17 `Geodesy.*` host capability schema entries.
63pub fn entries() -> Vec<SchemaEntry> {
64    vec![
65        SchemaEntry::new(
66            "Geodesy.wgs84_inverse",
67            EffectClass::Pure,
68            HonestyLabel::Always,
69            "Record",
70        )
71        .with_arg(SchemaArg::new("lat1_deg", "f64", true))
72        .with_arg(SchemaArg::new("lon1_deg", "f64", true))
73        .with_arg(SchemaArg::new("lat2_deg", "f64", true))
74        .with_arg(SchemaArg::new("lon2_deg", "f64", true))
75        .with_description("Solves the inverse geodesic problem on WGS-84 (distance, azimuth, reverse azimuth)."),
76
77        SchemaEntry::new(
78            "Geodesy.wgs84_direct",
79            EffectClass::Pure,
80            HonestyLabel::Always,
81            "Record",
82        )
83        .with_arg(SchemaArg::new("lat1_deg", "f64", true))
84        .with_arg(SchemaArg::new("lon1_deg", "f64", true))
85        .with_arg(SchemaArg::new("bearing_deg", "f64", true))
86        .with_arg(SchemaArg::new("distance_m", "f64", true))
87        .with_description("Solves the direct geodesic problem on WGS-84 given start point, bearing, and distance."),
88
89        SchemaEntry::new(
90            "Geodesy.wgs84_intermediate",
91            EffectClass::Pure,
92            HonestyLabel::Always,
93            "Record",
94        )
95        .with_arg(SchemaArg::new("lat1_deg", "f64", true))
96        .with_arg(SchemaArg::new("lon1_deg", "f64", true))
97        .with_arg(SchemaArg::new("lat2_deg", "f64", true))
98        .with_arg(SchemaArg::new("lon2_deg", "f64", true))
99        .with_arg(SchemaArg::new("fraction", "f64", true))
100        .with_description("Interpolates an intermediate point along the WGS-84 geodesic arc."),
101
102        SchemaEntry::new(
103            "Geodesy.polygon_area_m2",
104            EffectClass::Pure,
105            HonestyLabel::Always,
106            "f64",
107        )
108        .with_arg(SchemaArg::new("points", "List<Record>", true))
109        .with_description("Computes the ellipsoidal surface area in square meters for a closed geodesic polygon."),
110
111        SchemaEntry::new(
112            "Geodesy.geodetic_to_ecef",
113            EffectClass::Pure,
114            HonestyLabel::Always,
115            "Record",
116        )
117        .with_arg(SchemaArg::new("lat_deg", "f64", true))
118        .with_arg(SchemaArg::new("lon_deg", "f64", true))
119        .with_arg(SchemaArg::new("alt_m", "f64", true))
120        .with_description("Converts geodetic coordinates to Earth-Centered Earth-Fixed (ECEF) Cartesian XYZ."),
121
122        SchemaEntry::new(
123            "Geodesy.ecef_to_geodetic",
124            EffectClass::Pure,
125            HonestyLabel::Always,
126            "Record",
127        )
128        .with_arg(SchemaArg::new("x", "f64", true))
129        .with_arg(SchemaArg::new("y", "f64", true))
130        .with_arg(SchemaArg::new("z", "f64", true))
131        .with_description("Converts ECEF Cartesian XYZ to geodetic latitude, longitude, and ellipsoidal altitude."),
132
133        SchemaEntry::new(
134            "Geodesy.enu_basis",
135            EffectClass::Pure,
136            HonestyLabel::Always,
137            "Record",
138        )
139        .with_arg(SchemaArg::new("lat_deg", "f64", true))
140        .with_arg(SchemaArg::new("lon_deg", "f64", true))
141        .with_description("Calculates the local East-North-Up (ENU) tangent basis orthonormal matrix."),
142
143        SchemaEntry::new(
144            "Geodesy.parse_coord",
145            EffectClass::Pure,
146            HonestyLabel::Always,
147            "Record",
148        )
149        .with_arg(SchemaArg::new("text", "string", true))
150        .with_description("Parses coordinate text in DMS, decimal degrees, UTM, or MGRS format into lat/lon record."),
151
152        SchemaEntry::new(
153            "Geodesy.format_mgrs",
154            EffectClass::Pure,
155            HonestyLabel::Always,
156            "string",
157        )
158        .with_arg(SchemaArg::new("lat_deg", "f64", true))
159        .with_arg(SchemaArg::new("lon_deg", "f64", true))
160        .with_arg(SchemaArg::new("precision", "u64", true))
161        .with_description("Formats geodetic coordinates into a Military Grid Reference System (MGRS) string."),
162
163        SchemaEntry::new(
164            "Geodesy.crs_transform",
165            EffectClass::Pure,
166            HonestyLabel::Always,
167            "Record",
168        )
169        .with_arg(SchemaArg::new("src_epsg", "u64", true))
170        .with_arg(SchemaArg::new("dst_epsg", "u64", true))
171        .with_arg(SchemaArg::new("x", "f64", true))
172        .with_arg(SchemaArg::new("y", "f64", true))
173        .with_description("Transforms 2D coordinates between EPSG Coordinate Reference Systems."),
174
175        SchemaEntry::new(
176            "Geodesy.ausgeoid_undulation",
177            EffectClass::Pure,
178            HonestyLabel::Always,
179            "f64",
180        )
181        .with_arg(SchemaArg::new("lat_deg", "f64", true))
182        .with_arg(SchemaArg::new("lon_deg", "f64", true))
183        .with_description("Evaluates AUSGeoid2020 gravimetric geoid undulation (N value) for Australian height datum."),
184
185        SchemaEntry::new(
186            "Geodesy.lonlat_to_a5",
187            EffectClass::Pure,
188            HonestyLabel::Always,
189            "u64",
190        )
191        .with_arg(SchemaArg::new("lon_deg", "f64", true))
192        .with_arg(SchemaArg::new("lat_deg", "f64", true))
193        .with_arg(SchemaArg::new("resolution", "u64", true))
194        .with_description("Encodes longitude and latitude into an A5 Discrete Global Grid System (DGGS) cell ID."),
195
196        SchemaEntry::new(
197            "Geodesy.a5_to_lonlat",
198            EffectClass::Pure,
199            HonestyLabel::Always,
200            "Record",
201        )
202        .with_arg(SchemaArg::new("cell", "u64", true))
203        .with_description("Decodes an A5 Discrete Global Grid System cell ID to its centroid longitude and latitude."),
204
205        SchemaEntry::new(
206            "Geodesy.rtree_query_bbox",
207            EffectClass::Read,
208            HonestyLabel::Always,
209            "List<u64>",
210        )
211        .with_arg(SchemaArg::new("entries", "List<Record>", true))
212        .with_arg(SchemaArg::new("bbox", "Record", true))
213        .with_description("Queries an in-memory spatial R-tree bounding box index for intersecting candidate IDs."),
214
215        SchemaEntry::new(
216            "Geodesy.sun_ephemeris",
217            EffectClass::Pure,
218            HonestyLabel::Always,
219            "Record",
220        )
221        .with_arg(SchemaArg::new("unix_secs", "f64", true))
222        .with_arg(SchemaArg::new("lat_deg", "f64", true))
223        .with_arg(SchemaArg::new("lon_deg", "f64", true))
224        .with_description("Computes solar ephemeris: elevation, azimuth, distance, and declination for an epoch and location."),
225
226        SchemaEntry::new(
227            "Geodesy.topographic_insolation",
228            EffectClass::Pure,
229            HonestyLabel::Always,
230            "Record",
231        )
232        .with_arg(SchemaArg::new("unix_secs", "f64", true))
233        .with_arg(SchemaArg::new("lat_deg", "f64", true))
234        .with_arg(SchemaArg::new("lon_deg", "f64", true))
235        .with_arg(SchemaArg::new("alt_m", "f64", true))
236        .with_arg(SchemaArg::new("slope_deg", "f64", true))
237        .with_arg(SchemaArg::new("aspect_deg", "f64", true))
238        .with_description("Calculates direct, diffuse, and reflected solar irradiance on an inclined topographic surface."),
239
240        SchemaEntry::new(
241            "Geodesy.orbit_propagate",
242            EffectClass::Pure,
243            HonestyLabel::Always,
244            "Record",
245        )
246        .with_arg(SchemaArg::new("elements", "Record", true))
247        .with_arg(SchemaArg::new("target_unix_secs", "f64", true))
248        .with_description("Propagates Keplerian or SGP4 orbital elements to target epoch, returning ECEF/ECI state."),
249    ]
250}
251
252#[cfg(test)]
253mod tests {
254    use super::*;
255
256    #[test]
257    fn test_geodesy_invoke_ids_uniqueness_and_order() {
258        assert_eq!(GEODESY_INVOKE_IDS.len(), 17);
259        let mut ids = GEODESY_INVOKE_IDS.to_vec();
260        ids.sort();
261        ids.dedup();
262        assert_eq!(ids.len(), 17, "GEODESY_INVOKE_IDS must contain unique entries");
263    }
264
265    #[test]
266    fn test_entries_count_and_matches_ids() {
267        let all_entries = entries();
268        assert_eq!(all_entries.len(), 17);
269        for (i, entry) in all_entries.iter().enumerate() {
270            assert_eq!(entry.id, GEODESY_INVOKE_IDS[i]);
271            assert_eq!(entry.honesty, HonestyLabel::Always);
272            assert!(
273                entry.effect == EffectClass::Pure || entry.effect == EffectClass::Read,
274                "Expected Pure or Read effect class, got {:?}",
275                entry.effect
276            );
277            assert!(!entry.returns.is_empty());
278        }
279    }
280
281    #[test]
282    fn test_is_geodesy_unit_suffix() {
283        assert_eq!(GEODESY_UNIT_SUFFIXES.len(), 20);
284        for unit in GEODESY_UNIT_SUFFIXES {
285            assert!(
286                is_geodesy_unit_suffix(unit),
287                "Expected unit '{unit}' to be recognized as geodesy unit suffix"
288            );
289        }
290        assert!(!is_geodesy_unit_suffix(""));
291        assert!(!is_geodesy_unit_suffix("foo"));
292        assert!(!is_geodesy_unit_suffix("meter"));
293        assert!(!is_geodesy_unit_suffix("sec"));
294    }
295}