Skip to main content

hpr_sim/
export.rs

1//! Writing a flight out: a [`Recorder`]'s rows as CSV or JSON (or Parquet, with the `parquet`
2//! feature), and the center of mass's path with the landings as GeoJSON or KML for a map.
3//!
4//! Every function builds the file's contents (text, or bytes for Parquet) and returns them; none
5//! writes a file (the core crates do no I/O). Text numbers are written in Rust's shortest
6//! round-trip form and Parquet stores each `f64`'s own 8 bytes, so each reads back as the exact
7//! value recorded. A value that isn't finite is refused rather than written as something a reader
8//! would misread (`NaN`, or JSON's `null`).
9//!
10//! The two map formats put heights on different datums, as their specifications require:
11//!
12//! - **GeoJSON** (RFC 7946, section 4): longitude, latitude and height in meters above the WGS 84
13//!   ellipsoid.
14//! - **KML** (OGC 07-147r2, `altitudeMode` `absolute`): longitude, latitude and height above mean
15//!   sea level (KML's geoid is EGM96), which is the ellipsoidal height less the site's geoid
16//!   undulation ([`Environment::geoid_undulation_m`]). The undulation is taken as constant over the
17//!   flight; the geoid's slope, about 5 cm/km and up to some 30 cm/km in mountains, moves it by
18//!   centimeters to decimeters over a rocket's few kilometers.
19//!
20//! Neither cuts a path that crosses the antimeridian (±180° longitude), which RFC 7946 section 3.1.9
21//! asks for; a flight there draws a line the long way round the globe.
22//!
23//! Each file names the program that wrote it, its version and its designation in the FusionSpace
24//! product system ([`hpr_core::tool`]), as a drawing's title block names the tool that made it:
25//! JSON and GeoJSON in a top-level `tool` object, `{"name", "version", "designation"}` (in
26//! GeoJSON a foreign member, which RFC 7946 section 6.1 allows); KML in an XML comment after the
27//! declaration; Parquet in its key-value metadata. CSV is left as bare rows, so it opens cleanly
28//! in a spreadsheet: a program writing one keeps the stamp beside it.
29//!
30//! The two text formats follow the FusionSpace product system's `data.md` (*Files and exports*,
31//! *Copying and typing numbers*): a CSV's header gives each column in words with its unit in
32//! brackets, `time [s]` ([`csv_header`]), where JSON and Parquet keep the unit in the name,
33//! `time_s`; and JSON and GeoJSON text is ASCII, any other character written as a `\u` escape
34//! ([`ascii`]), so the designation's middle dot reads back as itself.
35
36use hpr_core::DVec3;
37use serde_json::{Value, json};
38
39use crate::environment::Environment;
40use crate::error::SimError;
41use crate::metrics::{FlightSummary, Landing};
42use crate::recorder::Recorder;
43
44#[cfg(feature = "parquet")]
45mod parquet;
46#[cfg(feature = "parquet")]
47pub use parquet::{PARQUET_PAGE_ROWS, parquet, parquet_with};
48
49/// The `tool` object a JSON or GeoJSON export opens with: the program's name, version and
50/// designation, from [`hpr_core::tool`].
51#[derive(serde::Serialize)]
52struct Tool {
53    name: &'static str,
54    version: &'static str,
55    designation: &'static str,
56}
57
58const TOOL: Tool = Tool {
59    name: hpr_core::tool::NAME,
60    version: hpr_core::tool::VERSION,
61    designation: hpr_core::tool::DESIGNATION,
62};
63
64/// A JSON export of the recorded rows, its keys in this order: the caller's own fields come
65/// between the program and the rows.
66#[derive(serde::Serialize)]
67struct Rows<'a, T: serde::Serialize> {
68    tool: Tool,
69    #[serde(flatten)]
70    about: &'a T,
71    columns: &'a [String],
72    rows: &'a [Vec<f64>],
73}
74
75/// A GeoJSON `FeatureCollection`, its keys in this order: `tool` is a foreign member.
76#[derive(serde::Serialize)]
77struct FeatureCollection<'a, T: serde::Serialize> {
78    #[serde(rename = "type")]
79    kind: &'static str,
80    tool: Tool,
81    #[serde(flatten)]
82    about: &'a T,
83    features: Vec<Value>,
84}
85
86/// `value` as compact JSON text, in ASCII ([`ascii`]).
87fn to_text(value: &impl serde::Serialize) -> Result<String, SimError> {
88    // Every key is a string, and every number the export computed is finite (checked before),
89    // the things `serde_json` refuses; a caller's own fields beside the rows or the map
90    // (`json_with`, `geojson_with`) are written as `serde_json` writes them, a NaN as `null`. The
91    // error is mapped rather than unwrapped all the same.
92    serde_json::to_string(value)
93        .map(|text| ascii(&text))
94        .map_err(|_| SimError::Unsupported {
95            what: "a value JSON can't hold",
96        })
97}
98
99/// JSON text in ASCII: every character outside it written as its `\u` escape, a character past
100/// U+FFFF as its UTF-16 surrogate pair (RFC 8259, section 7), so `·` (U+00B7) becomes `\u00b7`.
101/// The product system's `data.md` asks JSON to be ASCII (*Copying and typing numbers*). A reader
102/// gets back the same strings: outside a string JSON text is ASCII already, and inside one an
103/// escape stands for its character.
104#[must_use]
105pub fn ascii(json: &str) -> String {
106    let mut out = String::with_capacity(json.len());
107    for c in json.chars() {
108        if c.is_ascii() {
109            out.push(c);
110        } else {
111            let mut units = [0_u16; 2];
112            for unit in c.encode_utf16(&mut units) {
113                out.push_str(&format!("\\u{unit:04x}"));
114            }
115        }
116    }
117    out
118}
119
120/// The units a column's name can end in, as its last one or two `_`-separated words, and how a
121/// CSV header writes each, in ASCII: two-word units first, so `m_s` is meters per second and not
122/// seconds.
123const UNITS: [(&[&str], &str); 12] = [
124    (&["m", "s2"], "m/s^2"),
125    (&["m", "s"], "m/s"),
126    (&["rad", "s"], "rad/s"),
127    (&["m2"], "m^2"),
128    (&["pa"], "Pa"),
129    (&["kg"], "kg"),
130    (&["n"], "N"),
131    (&["m"], "m"),
132    (&["s"], "s"),
133    (&["rad"], "rad"),
134    (&["deg"], "deg"),
135    (&["cal"], "cal"),
136];
137
138/// A column's name as a CSV header writes it: the name's words with spaces, then its unit in
139/// brackets, as the product system's `data.md` writes a header (`time [s]`). The unit is the
140/// name's last word or two, read from a table of twelve units: `time_s` is `time [s]`,
141/// `velocity_east_m_s` is `velocity east [m/s]`, `max_acceleration_m_s2` is
142/// `max acceleration [m/s^2]` and `dynamic_pressure_pa` is `dynamic pressure [Pa]`; a name with
143/// no unit, such as `mach` or `drag_scale`, is its words alone. JSON and Parquet keep the name.
144#[must_use]
145pub fn csv_header(column: &str) -> String {
146    let words: Vec<&str> = column.split('_').collect();
147    for (unit, written) in UNITS {
148        if words.len() > unit.len() && words.ends_with(unit) {
149            let name = words[..words.len() - unit.len()].join(" ");
150            return format!("{name} [{written}]");
151        }
152    }
153    words.join(" ")
154}
155
156/// One point of the center of mass's path, placed on the Earth.
157#[derive(Debug, Clone, Copy, PartialEq, serde::Serialize, serde::Deserialize)]
158pub struct TrackPoint {
159    /// Time since launch, s.
160    pub time_s: f64,
161    /// Geodetic latitude, degrees north (WGS 84).
162    pub latitude_deg: f64,
163    /// Longitude, degrees east.
164    pub longitude_deg: f64,
165    /// Height above the WGS 84 ellipsoid, m.
166    pub height_above_ellipsoid_m: f64,
167    /// Height above mean sea level, m: the ellipsoidal height less the site's geoid undulation.
168    pub height_above_sea_level_m: f64,
169}
170
171fn finite(what: &'static str, value: f64) -> Result<f64, SimError> {
172    if value.is_finite() {
173        Ok(value)
174    } else {
175        Err(SimError::Domain { what, value })
176    }
177}
178
179/// The recorded rows as CSV (RFC 4180): a header of the columns in words with their units in
180/// brackets ([`csv_header`]: `time [s]` for the column `time_s`), then one line per row, lines
181/// ending in CRLF.
182///
183/// # Errors
184///
185/// [`SimError::Domain`] for a value that isn't finite.
186pub fn csv(recorder: &Recorder) -> Result<String, SimError> {
187    let header: Vec<String> = recorder.columns().iter().map(|c| csv_header(c)).collect();
188    let mut out = header.join(",");
189    out.push_str("\r\n");
190    for row in recorder.rows() {
191        let mut cells = Vec::with_capacity(row.len());
192        for &value in row {
193            cells.push(format!("{:?}", finite("recorded value", value)?));
194        }
195        out.push_str(&cells.join(","));
196        out.push_str("\r\n");
197    }
198    Ok(out)
199}
200
201/// The recorded rows as JSON: `{"tool": {...}, "columns": [names], "rows": [[values], ...]}`,
202/// each row in the columns' order. `tool` names the program that wrote the file:
203/// `{"name": "FusionSpace HPR", "version": "0.1.0", "designation": "FS-ACHERNAR \u00b7 SW \u00b7
204/// TOOL 001"}`, the text in ASCII ([`ascii`]). A [`FlightSummary`] is serializable on its own
205/// (`serde_json::to_string`).
206///
207/// # Errors
208///
209/// [`SimError::Domain`] for a value that isn't finite.
210pub fn json(recorder: &Recorder) -> Result<String, SimError> {
211    json_with(recorder, &serde_json::Map::new())
212}
213
214/// The recorded rows as [`json()`] writes them, with `about`'s fields, in its order, between
215/// `tool` and `columns`: what the caller knows of the flight that the recorder doesn't, such as
216/// the design flown or how far to trust it. A struct or a [`serde_json::Map`] keeps the order
217/// from one run to the next; a `HashMap` doesn't, so the same flight could write other bytes.
218///
219/// # Errors
220///
221/// [`SimError::Domain`] for a value that isn't finite; [`SimError::Unsupported`] for an `about`
222/// that isn't a JSON object, or has a field named `tool`, `columns` or `rows`, which would write a
223/// key twice.
224pub fn json_with<T: serde::Serialize>(recorder: &Recorder, about: &T) -> Result<String, SimError> {
225    let Ok(Value::Object(fields)) = serde_json::to_value(about) else {
226        return Err(SimError::Unsupported {
227            what: "fields beside the recording that aren't a JSON object",
228        });
229    };
230    if ["tool", "columns", "rows"]
231        .iter()
232        .any(|key| fields.contains_key(*key))
233    {
234        return Err(SimError::Unsupported {
235            what: "a field named tool, columns or rows beside the recording's own",
236        });
237    }
238    for row in recorder.rows() {
239        for &value in row {
240            finite("recorded value", value)?;
241        }
242    }
243    to_text(&Rows {
244        tool: TOOL,
245        about,
246        columns: &recorder.columns(),
247        rows: recorder.rows(),
248    })
249}
250
251/// The center of mass's path from a recorder that kept [`crate::Channel::Time`] and
252/// [`crate::Channel::CgPosition`], placed on `environment`'s ellipsoid.
253///
254/// # Errors
255///
256/// [`SimError::Unsupported`] if the recorder lacks either channel; [`SimError::Core`] if a
257/// position has no geodetic coordinates.
258pub fn track(recorder: &Recorder, environment: &Environment) -> Result<Vec<TrackPoint>, SimError> {
259    let columns = recorder.columns();
260    let index = |name: &str| columns.iter().position(|c| c == name);
261    let (Some(t), Some(e), Some(n), Some(u)) = (
262        index("time_s"),
263        index("cg_east_m"),
264        index("cg_north_m"),
265        index("cg_up_m"),
266    ) else {
267        return Err(SimError::Unsupported {
268            what: "a track from a recorder without the time and CG position channels",
269        });
270    };
271    let frame = environment.earth.frame();
272    recorder
273        .rows()
274        .iter()
275        .map(|row| {
276            let place = frame.geodetic_from_enu(DVec3::new(row[e], row[n], row[u]))?;
277            Ok(TrackPoint {
278                time_s: row[t],
279                latitude_deg: place.latitude_rad.to_degrees(),
280                longitude_deg: place.longitude_rad.to_degrees(),
281                height_above_ellipsoid_m: place.height_m,
282                height_above_sea_level_m: place.height_m - environment.geoid_undulation_m,
283            })
284        })
285        .collect()
286}
287
288/// The flight's landing, then each separated body's, as `(label, landing)`.
289fn landings(summary: &FlightSummary) -> Vec<(String, &Landing)> {
290    let flight = summary.landing.iter().map(|l| ("landing".to_owned(), l));
291    let bodies = summary.body_landings.iter().map(|l| {
292        let label = match l.body {
293            Some(body) => format!("body {body} landing"),
294            None => "landing".to_owned(),
295        };
296        (label, l)
297    });
298    flight.chain(bodies).collect()
299}
300
301fn too_short(track: &[TrackPoint]) -> Result<(), SimError> {
302    if track.len() < 2 {
303        return Err(SimError::Unsupported {
304            what: "a path of fewer than two points (a line needs two)",
305        });
306    }
307    Ok(())
308}
309
310/// The path and the landings as a GeoJSON `FeatureCollection` (RFC 7946): a `LineString` of
311/// `[longitude, latitude, height above the ellipsoid]` whose `properties.time_s` lists each
312/// point's time, and a `Point` per landing of `summary` with its time, body, distance and descent
313/// rate. A top-level `tool` object names the program that wrote it, as [`json()`]'s does: a
314/// foreign member, which RFC 7946 section 6.1 allows and readers pass over.
315///
316/// # Errors
317///
318/// [`SimError::Unsupported`] for a track of fewer than two points (a `LineString` needs two);
319/// [`SimError::Domain`] for a coordinate that isn't finite.
320pub fn geojson(track: &[TrackPoint], summary: &FlightSummary) -> Result<String, SimError> {
321    geojson_with(track, summary, &serde_json::Map::new())
322}
323
324/// The path and the landings as [`geojson()`] writes them, with `about`'s fields, in its order,
325/// between `tool` and `features`: more foreign members (RFC 7946 section 6.1), such as the motor
326/// catalog's date or how far to trust the landing point, as [`json_with`] carries them. A struct
327/// or a [`serde_json::Map`] keeps the order from one run to the next.
328///
329/// # Errors
330///
331/// As [`geojson()`]; also [`SimError::Unsupported`] for an `about` that isn't a JSON object, or
332/// has a field named `type`, `tool` or `features`, which would write a key twice, one RFC 7946
333/// section 7.1 keeps from a `FeatureCollection` (`geometry`, `properties`, `coordinates`,
334/// `geometries`), or one a reader gives a meaning: `bbox` (section 5) or the older format's `crs`,
335/// which GDAL and QGIS still read.
336pub fn geojson_with<T: serde::Serialize>(
337    track: &[TrackPoint],
338    summary: &FlightSummary,
339    about: &T,
340) -> Result<String, SimError> {
341    let Ok(Value::Object(fields)) = serde_json::to_value(about) else {
342        return Err(SimError::Unsupported {
343            what: "fields beside the map that aren't a JSON object",
344        });
345    };
346    if [
347        "type",
348        "tool",
349        "features",
350        "geometry",
351        "properties",
352        "coordinates",
353        "geometries",
354        "bbox",
355        "crs",
356    ]
357    .iter()
358    .any(|key| fields.contains_key(*key))
359    {
360        return Err(SimError::Unsupported {
361            what: "a field beside the map named as a GeoJSON member",
362        });
363    }
364    too_short(track)?;
365    let mut coordinates = Vec::with_capacity(track.len());
366    let mut times = Vec::with_capacity(track.len());
367    for p in track {
368        coordinates.push(json!([
369            finite("longitude", p.longitude_deg)?,
370            finite("latitude", p.latitude_deg)?,
371            finite("height", p.height_above_ellipsoid_m)?,
372        ]));
373        times.push(finite("time", p.time_s)?);
374    }
375    let mut features = vec![json!({
376        "type": "Feature",
377        "geometry": {"type": "LineString", "coordinates": coordinates},
378        "properties": {"name": "flight path", "time_s": times},
379    })];
380    for (label, l) in landings(summary) {
381        features.push(json!({
382            "type": "Feature",
383            "geometry": {"type": "Point", "coordinates": [
384                finite("longitude", l.longitude_deg)?,
385                finite("latitude", l.latitude_deg)?,
386            ]},
387            "properties": {
388                "name": label,
389                "body": l.body,
390                "time_s": finite("time", l.time_s)?,
391                "distance_m": finite("distance", l.distance_m)?,
392                "descent_rate_m_s": finite("descent rate", l.descent_rate_m_s)?,
393            },
394        }));
395    }
396    to_text(&FeatureCollection {
397        kind: "FeatureCollection",
398        tool: TOOL,
399        about,
400        features,
401    })
402}
403
404/// `text` with XML's five special characters escaped.
405///
406/// # Errors
407///
408/// [`SimError::Unsupported`] for a control character XML 1.0 forbids (all below U+0020 but tab,
409/// line feed and carriage return; U+FFFE and U+FFFF).
410fn escape(text: &str) -> Result<String, SimError> {
411    let forbidden = |c: char| {
412        (c < ' ' && !matches!(c, '\t' | '\n' | '\r')) || matches!(c, '\u{FFFE}' | '\u{FFFF}')
413    };
414    if text.chars().any(forbidden) {
415        return Err(SimError::Unsupported {
416            what: "KML text, a name or a description, with a control character XML 1.0 forbids",
417        });
418    }
419    let mut out = String::with_capacity(text.len());
420    for c in text.chars() {
421        match c {
422            '&' => out.push_str("&amp;"),
423            '<' => out.push_str("&lt;"),
424            '>' => out.push_str("&gt;"),
425            '"' => out.push_str("&quot;"),
426            '\'' => out.push_str("&apos;"),
427            _ => out.push(c),
428        }
429    }
430    Ok(out)
431}
432
433/// The path and the landings as a KML 2.2 document (OGC 07-147r2) named `name`: a `LineString`
434/// of `longitude,latitude,height above mean sea level` with `altitudeMode` `absolute`, and a
435/// ground-clamped `Point` per landing of `summary`. An XML comment after the declaration names
436/// the program that wrote it, `<!-- FusionSpace HPR 0.1.0 · FS-ACHERNAR · SW · TOOL 001 -->`
437/// ([`hpr_core::tool::stamp`]).
438///
439/// # Errors
440///
441/// [`SimError::Unsupported`] for a track of fewer than two points or a name with a control
442/// character XML forbids; [`SimError::Domain`] for a coordinate that isn't finite.
443pub fn kml(track: &[TrackPoint], summary: &FlightSummary, name: &str) -> Result<String, SimError> {
444    kml_with(track, summary, name, "")
445}
446
447/// The path and the landings as [`kml()`] writes them, with `description` as the `Document`'s
448/// `description` (OGC 07-147r2 section 9.1.3.6, after its `name`), such as the motor catalog's
449/// date and how far to trust the path: a map shows it when the file is opened. It is escaped as
450/// XML text, but map programs such as Google Earth show a description as HTML, so text from
451/// someone else should not be passed through unchecked. An empty `description` writes none, as
452/// [`kml()`] does.
453///
454/// # Errors
455///
456/// As [`kml()`]; also [`SimError::Unsupported`] for a description with a control character XML
457/// forbids.
458pub fn kml_with(
459    track: &[TrackPoint],
460    summary: &FlightSummary,
461    name: &str,
462    description: &str,
463) -> Result<String, SimError> {
464    too_short(track)?;
465    let mut path = Vec::with_capacity(track.len());
466    for p in track {
467        path.push(format!(
468            "{:?},{:?},{:?}",
469            finite("longitude", p.longitude_deg)?,
470            finite("latitude", p.latitude_deg)?,
471            finite("height", p.height_above_sea_level_m)?,
472        ));
473    }
474    let mut out = String::from("<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n");
475    // The stamp holds no `--` and doesn't end in `-`, which an XML comment can't (XML 1.0 §2.5).
476    out.push_str(&format!("<!-- {} -->\n", hpr_core::tool::stamp()));
477    out.push_str("<kml xmlns=\"http://www.opengis.net/kml/2.2\">\n<Document>\n");
478    out.push_str(&format!("<name>{}</name>\n", escape(name)?));
479    if !description.is_empty() {
480        out.push_str(&format!(
481            "<description>{}</description>\n",
482            escape(description)?
483        ));
484    }
485    out.push_str("<Placemark>\n<name>flight path</name>\n<LineString>\n");
486    out.push_str("<altitudeMode>absolute</altitudeMode>\n<coordinates>\n");
487    out.push_str(&path.join("\n"));
488    out.push_str("\n</coordinates>\n</LineString>\n</Placemark>\n");
489    for (label, l) in landings(summary) {
490        out.push_str(&format!(
491            "<Placemark>\n<name>{}</name>\n<description>t = {:?} s</description>\n<Point>\n\
492             <coordinates>{:?},{:?}</coordinates>\n</Point>\n</Placemark>\n",
493            escape(&label)?,
494            finite("time", l.time_s)?,
495            finite("longitude", l.longitude_deg)?,
496            finite("latitude", l.latitude_deg)?,
497        ));
498    }
499    out.push_str("</Document>\n</kml>\n");
500    Ok(out)
501}
502
503#[cfg(test)]
504mod tests {
505    use hpr_atmos::ConstantWind;
506
507    use super::*;
508    use crate::flight::{FlightSettings, Simulation};
509    use crate::metrics::FlightMetrics;
510    use crate::rail::Rail;
511    use crate::recorder::Channel;
512    use crate::recovery::{Device, DeviceDrag, Trigger};
513    use crate::testing::{design, windy_environment};
514
515    /// Valetudo under a canopy from apogee, carried east by a 6 m/s west wind: its recording at
516    /// 1 s, its path and its summary.
517    pub(super) fn flown() -> (Recorder, Vec<TrackPoint>, FlightSummary, Environment) {
518        let wind = ConstantWind::new(6.0, 1.5 * std::f64::consts::PI).unwrap();
519        let canopy = Device::new(
520            "main",
521            DeviceDrag::DragArea { cd_s_m2: 0.5 },
522            Trigger::Apogee,
523        );
524        let sim = Simulation::new(
525            &design("rocketpy-valetudo"),
526            "example",
527            windy_environment(wind).with_geoid_undulation_m(-25.0),
528            Rail::vertical(3.0),
529            FlightSettings {
530                max_time_s: 600.0,
531                ..FlightSettings::default()
532            },
533        )
534        .unwrap()
535        .with_recovery(vec![canopy])
536        .unwrap();
537        let recorder = Recorder::new(
538            vec![Channel::Time, Channel::CgPosition, Channel::Mach],
539            Some(1.0),
540        )
541        .unwrap();
542        let mut watchers = (FlightMetrics::new(), recorder);
543        let result = sim.run(&mut watchers).unwrap();
544        let (metrics, recorder) = watchers;
545        let summary = metrics.summary(&result, sim.environment()).unwrap();
546        let track = track(&recorder, sim.environment()).unwrap();
547        (recorder, track, summary, sim.environment().clone())
548    }
549
550    #[test]
551    fn csv_and_json_hold_every_recorded_value_exactly() {
552        let (recorder, ..) = flown();
553        assert!(recorder.rows().len() > 20);
554        let text = csv(&recorder).unwrap();
555        let mut lines = text.split("\r\n");
556        let header: Vec<&str> = lines.next().unwrap().split(',').collect();
557        let columns: Vec<String> = recorder.columns().iter().map(|c| csv_header(c)).collect();
558        assert_eq!(header, columns);
559        let rows: Vec<Vec<f64>> = lines
560            .filter(|l| !l.is_empty())
561            .map(|l| l.split(',').map(|c| c.parse().unwrap()).collect())
562            .collect();
563        assert_eq!(rows, recorder.rows());
564        assert!(text.ends_with("\r\n"));
565
566        let value: Value = serde_json::from_str(&json(&recorder).unwrap()).unwrap();
567        let columns: Vec<String> = serde_json::from_value(value["columns"].clone()).unwrap();
568        let rows: Vec<Vec<f64>> = serde_json::from_value(value["rows"].clone()).unwrap();
569        assert_eq!(columns, recorder.columns());
570        assert_eq!(rows, recorder.rows());
571    }
572
573    /// The object every JSON export carries: name, version and designation.
574    fn assert_names_the_tool(value: &Value) {
575        assert_eq!(
576            value["tool"],
577            json!({
578                "name": "FusionSpace HPR",
579                "version": env!("CARGO_PKG_VERSION"),
580                "designation": "FS-ACHERNAR · SW · TOOL 001",
581            })
582        );
583    }
584
585    /// Each export but CSV names the program that wrote it, its version and its designation, as
586    /// a title block does: JSON and GeoJSON in a `tool` object written first and second, after
587    /// GeoJSON's `type`, and KML in a comment after the declaration. CSV stays bare rows, so a
588    /// spreadsheet opens it with the header first.
589    #[test]
590    fn every_export_but_csv_names_the_program_version_and_designation() {
591        let (recorder, track, summary, _) = flown();
592        let version = env!("CARGO_PKG_VERSION");
593        // The designation's middle dots as escapes: JSON text is ASCII.
594        let object = format!(
595            "\"tool\":{{\"name\":\"FusionSpace HPR\",\"version\":\"{version}\",\
596             \"designation\":\"FS-ACHERNAR \\u00b7 SW \\u00b7 TOOL 001\"}}"
597        );
598
599        let text = json(&recorder).unwrap();
600        assert!(
601            text.starts_with(&format!("{{{object},\"columns\":")),
602            "{text:.200}"
603        );
604        let value: Value = serde_json::from_str(&text).unwrap();
605        assert_names_the_tool(&value);
606        assert_eq!(value.as_object().unwrap().len(), 3);
607
608        let text = geojson(&track, &summary).unwrap();
609        assert!(
610            text.starts_with(&format!(
611                "{{\"type\":\"FeatureCollection\",{object},\"features\":"
612            )),
613            "{text:.200}"
614        );
615        let value: Value = serde_json::from_str(&text).unwrap();
616        assert_names_the_tool(&value);
617        assert!(geojson_validator().is_valid(&value));
618
619        let text = kml(&track, &summary, "x").unwrap();
620        let stamp = format!("<!-- FusionSpace HPR {version} · FS-ACHERNAR · SW · TOOL 001 -->");
621        assert_eq!(stamp, format!("<!-- {} -->", hpr_core::tool::stamp()));
622        assert!(
623            text.starts_with(&format!(
624                "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n{stamp}\n<kml "
625            )),
626            "{text:.200}"
627        );
628        let document = roxmltree::Document::parse(&text).unwrap();
629        let comments: Vec<&str> = document
630            .root()
631            .children()
632            .filter(roxmltree::Node::is_comment)
633            .filter_map(|n| n.text())
634            .collect();
635        assert_eq!(comments, [format!(" {} ", hpr_core::tool::stamp())]);
636
637        let text = csv(&recorder).unwrap();
638        assert!(text.starts_with("time [s],"), "{text:.200}");
639        assert!(
640            !text.contains("FusionSpace") && !text.contains("hpr-sim") && !text.contains("TOOL")
641        );
642    }
643
644    /// Every column a recorder can keep, as a CSV header writes it: words, then the unit in
645    /// brackets in ASCII, as the product system's `data.md` asks (`time [s]`), and the words alone
646    /// for a column with no unit. Written out by hand, so a unit read wrongly from a name (`m_s` as
647    /// seconds, `m_s2` as meters per second) fails.
648    #[test]
649    fn a_csv_header_gives_each_columns_unit_in_brackets() {
650        let headers: Vec<String> = Channel::ALL
651            .iter()
652            .flat_map(|c| c.columns())
653            .map(|c| csv_header(&c))
654            .collect();
655        assert_eq!(
656            headers.join(","),
657            "time [s],position east [m],position north [m],position up [m],\
658             velocity east [m/s],velocity north [m/s],velocity up [m/s],\
659             attitude w,attitude x,attitude y,attitude z,\
660             body rate x [rad/s],body rate y [rad/s],body rate z [rad/s],\
661             cg east [m],cg north [m],cg up [m],height above ground [m],vertical speed [m/s],\
662             acceleration east [m/s^2],acceleration north [m/s^2],acceleration up [m/s^2],\
663             airspeed [m/s],mach,angle of attack [rad],dynamic pressure [Pa],axial coefficient,\
664             thrust [N],mass [kg],recovery drag area [m^2]"
665        );
666        assert!(headers.iter().all(|h| h.is_ascii()));
667        // A unit alone is a name, not a unit with no name.
668        assert_eq!(csv_header("s"), "s");
669        assert_eq!(csv_header("m_s"), "m [s]");
670        assert_eq!(csv_header("latitude_deg"), "latitude [deg]");
671        assert_eq!(
672            csv_header("min_static_margin_cal"),
673            "min static margin [cal]"
674        );
675    }
676
677    /// JSON text is ASCII: a character outside it becomes its escape, one past U+FFFF a surrogate
678    /// pair, and the text reads back to the same string.
679    #[test]
680    fn json_text_is_ascii_and_reads_back_the_same() {
681        let value = json!({"name": "Mjölnir · 🚀", "plain": "a\"b\\c"});
682        let text = ascii(&serde_json::to_string(&value).unwrap());
683        assert_eq!(
684            text,
685            r#"{"name":"Mj\u00f6lnir \u00b7 \ud83d\ude80","plain":"a\"b\\c"}"#
686        );
687        assert!(text.is_ascii());
688        assert_eq!(serde_json::from_str::<Value>(&text).unwrap(), value);
689    }
690
691    /// `json_with` puts the caller's fields between `tool` and `columns`, and refuses one that
692    /// would write a key twice.
693    #[test]
694    fn json_with_adds_the_callers_fields_after_the_tool() {
695        let (recorder, ..) = flown();
696        #[derive(serde::Serialize)]
697        struct About {
698            kind: &'static str,
699            design: &'static str,
700        }
701        let text = json_with(
702            &recorder,
703            &About {
704                kind: "simulated",
705                design: "r · 1.ork",
706            },
707        )
708        .unwrap();
709        assert!(text.is_ascii());
710        let at = |key: &str| text.find(&format!("\"{key}\":")).unwrap();
711        assert!(
712            at("tool") < at("kind") && at("kind") < at("design") && at("design") < at("columns")
713        );
714        let value: Value = serde_json::from_str(&text).unwrap();
715        assert_eq!(value["design"], "r · 1.ork");
716        assert_eq!(value.as_object().unwrap().len(), 5);
717        assert!(matches!(
718            json_with(&recorder, &1),
719            Err(SimError::Unsupported { what }) if what.contains("aren't a JSON object")
720        ));
721        for key in ["tool", "columns", "rows"] {
722            let mut twice = serde_json::Map::new();
723            twice.insert(key.to_owned(), json!(1));
724            assert!(
725                matches!(
726                    json_with(&recorder, &twice),
727                    Err(SimError::Unsupported { what }) if what.contains("tool, columns or rows")
728                ),
729                "{key}"
730            );
731        }
732    }
733
734    #[test]
735    fn a_value_that_is_not_finite_is_refused() {
736        let point = TrackPoint {
737            time_s: 0.0,
738            latitude_deg: 32.0,
739            longitude_deg: f64::NAN,
740            height_above_ellipsoid_m: 0.0,
741            height_above_sea_level_m: 0.0,
742        };
743        let (.., summary, _) = flown();
744        let track = [
745            point,
746            TrackPoint {
747                time_s: 1.0,
748                ..point
749            },
750        ];
751        for result in [geojson(&track, &summary), kml(&track, &summary, "x")] {
752            assert!(matches!(
753                result,
754                Err(SimError::Domain { what: "longitude", value }) if value.is_nan()
755            ));
756        }
757        for result in [
758            geojson(&track[..1], &summary),
759            kml(&track[..1], &summary, "x"),
760        ] {
761            assert!(matches!(
762                result,
763                Err(SimError::Unsupported { what }) if what.contains("fewer than two")
764            ));
765        }
766        let fine = [
767            TrackPoint {
768                longitude_deg: -106.97,
769                ..point
770            },
771            TrackPoint {
772                time_s: 1.0,
773                longitude_deg: -106.97,
774                ..point
775            },
776        ];
777        assert!(matches!(
778            kml(&fine, &summary, "a\u{1}b"),
779            Err(SimError::Unsupported { what }) if what.contains("control character")
780        ));
781        assert!(kml(&fine, &summary, "tab\tok").is_ok());
782
783        let recorder = Recorder::with_rows(vec![Channel::Time], vec![vec![0.0], vec![f64::NAN]]);
784        for result in [csv(&recorder), json(&recorder)] {
785            assert!(matches!(
786                result,
787                Err(SimError::Domain { what: "recorded value", value }) if value.is_nan()
788            ));
789        }
790    }
791
792    #[test]
793    fn track_places_each_row_on_the_ellipsoid_and_the_geoid() {
794        let (recorder, track, summary, environment) = flown();
795        assert_eq!(track.len(), recorder.rows().len());
796        let frame = environment.earth.frame();
797        for (point, row) in track.iter().zip(recorder.rows()) {
798            let place = frame
799                .geodetic_from_enu(DVec3::new(row[1], row[2], row[3]))
800                .unwrap();
801            assert_eq!(point.time_s, row[0]);
802            assert_eq!(point.latitude_deg, place.latitude_rad.to_degrees());
803            assert_eq!(point.longitude_deg, place.longitude_rad.to_degrees());
804            assert_eq!(point.height_above_ellipsoid_m, place.height_m);
805            // h = H + N with N = −25 m: sea-level heights are 25 m above ellipsoidal ones.
806            assert!((point.height_above_sea_level_m - place.height_m - 25.0).abs() < 1e-9);
807        }
808        // The wind carries it east of the site, and it lands where the summary says.
809        let last = track.last().unwrap();
810        let landing = summary.landing.unwrap();
811        assert!(last.longitude_deg > track[0].longitude_deg);
812        assert!(landing.east_m > 100.0);
813
814        let without = Recorder::new(vec![Channel::Time], None).unwrap();
815        assert!(matches!(
816            super::track(&without, &environment),
817            Err(SimError::Unsupported { .. })
818        ));
819    }
820
821    /// The published GeoJSON `FeatureCollection` schema (geojson/schema, MIT, commit 268ba0a).
822    fn geojson_validator() -> jsonschema::Validator {
823        let schema: Value = serde_json::from_str(include_str!(
824            "../tests/data/geojson-feature-collection.schema.json"
825        ))
826        .unwrap();
827        jsonschema::draft7::new(&schema).unwrap()
828    }
829
830    #[test]
831    fn geojson_passes_the_published_schema_in_longitude_latitude_order() {
832        let (_, track, summary, _) = flown();
833        let validator = geojson_validator();
834        let value: Value = serde_json::from_str(&geojson(&track, &summary).unwrap()).unwrap();
835        let errors: Vec<String> = validator
836            .iter_errors(&value)
837            .map(|e| e.to_string())
838            .collect();
839        assert!(errors.is_empty(), "{errors:?}");
840
841        let features = value["features"].as_array().unwrap();
842        assert_eq!(features.len(), 2);
843        let path = features[0]["geometry"]["coordinates"].as_array().unwrap();
844        assert_eq!(path.len(), track.len());
845        for (position, point) in path.iter().zip(&track) {
846            let p: [f64; 3] = serde_json::from_value(position.clone()).unwrap();
847            assert_eq!(
848                p,
849                [
850                    point.longitude_deg,
851                    point.latitude_deg,
852                    point.height_above_ellipsoid_m
853                ]
854            );
855        }
856        let landing = summary.landing.unwrap();
857        let spot: [f64; 2] =
858            serde_json::from_value(features[1]["geometry"]["coordinates"].clone()).unwrap();
859        assert_eq!(spot, [landing.longitude_deg, landing.latitude_deg]);
860
861        // The validator does reject a broken document: a one-number position.
862        let mut broken = value.clone();
863        broken["features"][1]["geometry"]["coordinates"] = json!([landing.longitude_deg]);
864        assert!(!validator.is_valid(&broken));
865    }
866
867    #[test]
868    fn geojson_with_writes_the_fields_between_tool_and_features_and_stays_valid() {
869        let (_, track, summary, _) = flown();
870        let about = json!({"catalog_as_of": "2026-01-02", "trust": "Rough & <ready>"});
871        let text = geojson_with(&track, &summary, &about).unwrap();
872        let value: Value = serde_json::from_str(&text).unwrap();
873        let errors: Vec<String> = geojson_validator()
874            .iter_errors(&value)
875            .map(|e| e.to_string())
876            .collect();
877        assert!(errors.is_empty(), "{errors:?}");
878        let at = |key: &str| text.find(&format!("\"{key}\":")).unwrap();
879        assert!(
880            at("type") < at("tool")
881                && at("tool") < at("catalog_as_of")
882                && at("catalog_as_of") < at("trust")
883                && at("trust") < at("features"),
884            "{text:.200}"
885        );
886        assert_eq!(value["trust"], "Rough & <ready>");
887        // Without fields, the bytes are geojson()'s.
888        assert_eq!(
889            geojson_with(&track, &summary, &serde_json::Map::new()).unwrap(),
890            geojson(&track, &summary).unwrap()
891        );
892        for key in [
893            "type",
894            "tool",
895            "features",
896            "geometry",
897            "properties",
898            "coordinates",
899            "geometries",
900            "bbox",
901            "crs",
902        ] {
903            let clash = json!({ key: 1 });
904            assert!(
905                matches!(
906                    geojson_with(&track, &summary, &clash),
907                    Err(SimError::Unsupported {
908                        what: "a field beside the map named as a GeoJSON member"
909                    })
910                ),
911                "{key}"
912            );
913        }
914        assert!(matches!(
915            geojson_with(&track, &summary, &1),
916            Err(SimError::Unsupported {
917                what: "fields beside the map that aren't a JSON object"
918            })
919        ));
920    }
921
922    #[test]
923    fn kml_with_describes_the_document_and_kml_writes_no_description() {
924        let (_, track, summary, _) = flown();
925        let text = kml_with(&track, &summary, "Flight", "As of 2026-01-02 & <rough>").unwrap();
926        let document = roxmltree::Document::parse(&text).unwrap();
927        let top = document
928            .descendants()
929            .find(|n| n.tag_name().name() == "Document")
930            .unwrap();
931        let children: Vec<&str> = top
932            .children()
933            .filter(|n| n.is_element())
934            .map(|n| n.tag_name().name())
935            .take(2)
936            .collect();
937        assert_eq!(children, ["name", "description"]);
938        let description = top
939            .children()
940            .find(|n| n.tag_name().name() == "description")
941            .unwrap();
942        assert_eq!(description.text(), Some("As of 2026-01-02 & <rough>"));
943        assert_eq!(
944            kml_with(&track, &summary, "Flight", "").unwrap(),
945            kml(&track, &summary, "Flight").unwrap()
946        );
947        assert!(matches!(
948            kml_with(&track, &summary, "Flight", "a\u{1}b"),
949            Err(SimError::Unsupported { what })
950                if what.starts_with("KML text, a name or a description, with a control character")
951        ));
952        assert!(
953            !kml(&track, &summary, "Flight")
954                .unwrap()
955                .contains("<Document>\n<name>Flight</name>\n<description>")
956        );
957    }
958
959    #[test]
960    fn kml_parses_as_kml_2_2_with_every_position() {
961        let (_, track, summary, _) = flown();
962        let text = kml(&track, &summary, "Valetudo & <friends>").unwrap();
963        let document = roxmltree::Document::parse(&text).unwrap();
964        let root = document.root_element();
965        assert_eq!(root.tag_name().name(), "kml");
966        assert_eq!(
967            root.tag_name().namespace(),
968            Some("http://www.opengis.net/kml/2.2")
969        );
970        let named = |tag: &'static str| {
971            let found: Vec<roxmltree::Node<'_, '_>> = document
972                .descendants()
973                .filter(|n| n.tag_name().name() == tag)
974                .collect();
975            found.into_iter()
976        };
977        let name = named("name").next().unwrap().text();
978        assert_eq!(name, Some("Valetudo & <friends>"));
979        assert_eq!(
980            named("altitudeMode").next().unwrap().text(),
981            Some("absolute")
982        );
983        let lists: Vec<&str> = named("coordinates").map(|n| n.text().unwrap()).collect();
984        assert_eq!(lists.len(), 2);
985        let path: Vec<Vec<f64>> = lists[0]
986            .split_whitespace()
987            .map(|t| t.split(',').map(|c| c.parse().unwrap()).collect())
988            .collect();
989        assert_eq!(path.len(), track.len());
990        for (position, point) in path.iter().zip(&track) {
991            assert_eq!(
992                position,
993                &[
994                    point.longitude_deg,
995                    point.latitude_deg,
996                    point.height_above_sea_level_m
997                ]
998            );
999        }
1000        let landing = summary.landing.unwrap();
1001        let spot: Vec<f64> = lists[1]
1002            .trim()
1003            .split(',')
1004            .map(|c| c.parse().unwrap())
1005            .collect();
1006        assert_eq!(spot, [landing.longitude_deg, landing.latitude_deg]);
1007    }
1008}