Exporting a flight
Save a flight as CSV, JSON or Parquet tables for a spreadsheet, and as GeoJSON or KML maps of its path and landing.
This page shows how to save a flight as files other programs read. A table of numbers over time, for a spreadsheet or a plotting tool, comes as CSV, JSON or Parquet. A map of the flight path and the landing comes as GeoJSON or KML, which Google Earth, QGIS and most web maps open. It flies the rocket of Getting started again and writes all five files. It needs the first page’s setup, and a little Rust.
Without writing Rust, hpr sim --export writes the same five formats for a .ork or HPR design
file. It puts every quantity HPR Sim tracks in each
(The command line). Its maps mark the landing when a parachute
or streamer opened, as a .ork file’s do, and no landing otherwise
(the landing).
Run it
cargo run --example export_flight -p fusionspace-hpr-sim --features parquet -- my-flight
This runs
crates/hpr-sim/examples/export_flight.rs,
which writes five files into the folder my-flight and prints what it wrote. Without a folder, it
writes them into fusionspace-hpr-export in the system’s temporary folder.
Parquet is an optional feature of
fusionspace-hpr-sim, named parquet, so the command turns it on. Without it, cargo says the
example needs it. The feature adds no other library. I made it optional so that a program with no
use for a binary file format leaves it out. In your own program, turn it on in Cargo.toml with
fusionspace-hpr-sim = { ..., features = ["parquet"] } (the crate your code calls hpr_sim).
wrote 67 rows of 5 columns, a path of 67 points
flight.csv
flight.json
flight.parquet, 3228 bytes
flight.geojson
flight.kml
landed at 32.99000° N, 106.96904° W, 90 m from the pad, at 58.9 s
CI runs it on macOS, Windows and Linux and fails if it prints anything else. The files hold every number to its last digit, which may differ in the last place between operating systems. So the program prints a rounded summary instead of the files.
The five files
| file | what it holds | opens in |
|---|---|---|
flight.csv | a header giving each column in words with its unit in brackets (time [s], cg east [m], …), then one line per recorded moment, lines ending in CRLF as RFC 4180 says | a spreadsheet, pandas, any plotting tool |
flight.json | the same table as {"tool": {...}, "columns": [...], "rows": [[...], ...]}, each column’s unit in its name (time_s, cg_east_m) | any programming language |
flight.parquet | the same table in Apache Parquet, a binary format that stores it column by column: one column of 64-bit numbers per recorded column, named as in the JSON (time_s), not as in the CSV’s header (time [s]), and the program that wrote it, the motor catalog’s date and how far to trust the numbers in the file’s key-value metadata | pandas with pyarrow (Apache Arrow’s Python library), DuckDB |
flight.geojson | the flight path as a line, and a point for each landing: the rocket’s and any separated body’s; a tool object naming the program that wrote it; and the motor catalog’s date and how far to trust the numbers | QGIS, geojson.io, web maps |
flight.kml | the same path and landing | Google Earth |
Which program wrote a file
Each file but the CSV carries its provenance, where it came from. Like a drawing’s title block, the provenance names the tool that made the file. That’s the program, its version and its designation in the FusionSpace product system. It also carries the motor catalog’s date and how far to trust it, which come further below. The tool is named this way:
- In JSON and GeoJSON, it’s a
toolobject at the top,{"name": "FusionSpace HPR", "version": "0.1.0", "designation": "FS-ACHERNAR \u00b7 SW \u00b7 TOOL 001"}. The text is ASCII, so the designation’s middle dot·is written as its escape\u00b7. Every JSON reader reads that back as the dot. In GeoJSON the object is a foreign member, a key the standard doesn’t define. RFC 7946 (section 6.1) allows it, and map programs pass over it. - In KML, it’s a comment on the second line,
<!-- FusionSpace HPR 0.1.0 · FS-ACHERNAR · SW · TOOL 001 -->. - In Parquet, it’s the first three entries of the file’s key-value metadata:
tool(FusionSpace HPR),tool_versionanddesignation. pyarrow shows them withpyarrow.parquet.read_metadata(path).metadata.
The CSV holds only the header and the rows, so a spreadsheet opens it cleanly. Its header gives
each column in words with its unit in brackets, as the FusionSpace product system writes one.
For example, it gives time [s] for the column the other formats call time_s,
velocity east [m/s] for velocity_east_m_s, acceleration up [m/s^2] for
acceleration_up_m_s2 and dynamic pressure [Pa] for dynamic_pressure_pa. A column with no unit, such as mach, is its words alone. The
library’s export::csv_header gives one from the other.
hpr sim writes the title block beside the CSV instead: flight.meta.json for flight.csv. It
holds the same tool object, the CSV’s file name, the design and configuration flown, the number
of rows, and:
catalog_as_of: the day the bundled motor catalog’s curve files were downloaded, such as2026-10-28, which a build fixes. Whether a motor came from the catalog is inhpr sim --json’smotors. Each motor’ssourceis{"kind": "catalog", "as_of": "2026-10-28"}for one that did. Andhpr sim’s motor line saysfrom the bundled catalog, as of 2026-10-28. The day of the run itself is left out, so the same run writes the same bytes.kindandtrust: what the numbers are, and the accuracy notehpr simends with, word for word. The kind issimulatedfor a flight, andhpr motors showsayscopiedof a catalog motor’s figures.
A JSON recording from hpr sim carries the same three, with design and configuration, between
tool and columns. So a saved flight keeps its note. hpr mc --export’s sidecar carries them
too, with hpr mc’s own note. GeoJSON, KML and Parquet carry them as well. So a map or a table
copied away from the rest still says how old its motor data is and how far to trust it:
- In GeoJSON, they’re
design,configuration,catalog_as_of,kindandtrust, as foreign members betweentoolandfeatures, as in the JSON recording. - KML uses the
Document’sdescription:Motor catalog as of 2026-10-28.followed by the note. The design and configuration are already in itsname. KML has no field forkind. The note says the numbers are simulated. - In Parquet, they’re five more entries of the key-value metadata after the program’s three, under
the same names. Each value is text (
kindissimulated). The keys and values come out of pyarrow as bytes:pyarrow.parquet.read_metadata(path).metadata[b"trust"].decode()is the note.
Each gives the bundled catalog’s date whether or not the flight’s motor came from the catalog. A
motor from your own .eng or .rse file is as old as that file. hpr sim --json’s motors
says where each motor came from.
The --plot figure gives the catalog’s date too, in its title block, and its data file has a
sidecar of its own (Plotting the flight). The library’s export::csv
writes the CSV alone. export::json, export::geojson, export::kml and export::parquet carry
no more than the program’s name, version and designation. export::json_with,
export::geojson_with, export::kml_with and export::parquet_with add a program’s own fields.
To look at the Parquet file from Python, install pandas and pyarrow (pip install pandas pyarrow;
pandas can’t read Parquet on its own), then:
python -c "import pandas; print(pandas.read_parquet('my-flight/flight.parquet'))"
or, with DuckDB’s command-line program, duckdb -c "SELECT * FROM 'my-flight/flight.parquet'".
The tables hold whatever channels the
recorder kept, one row per recorded moment. The maps need the recorder to keep the time and the
center of gravity’s position (Channel::Time and Channel::CgPosition). They place each recorded
position on the Earth, with the same conversion as the landing point in
Flight metrics.
A map line in KML looks like this, one longitude,latitude,height per recorded moment (the digits
here are cut short):
<LineString>
<altitudeMode>absolute</altitudeMode>
<coordinates>
-106.97,32.99,1400.93591...
-106.97,32.98999...,1403.85869...
Heights: two datums
A height needs something to count from, a datum. The two map formats use different ones, because their standards say so:
- GeoJSON heights are above the WGS 84 ellipsoid, the smooth shape GPS uses (ellipsoidal height; RFC 7946, section 4).
- KML heights with
altitudeModeabsoluteare above sea level, which KML takes from the EGM96 geoid (height above sea level; OGC KML 2.2, 07-147r2).
Sea level sits above or below the ellipsoid by the
geoid undulation , up to about 100 m (328 ft). The
simulator has no model of it. So it uses the value the flight was given
(Environment::with_geoid_undulation_m, zero unless set), the same for every point of the flight.
The geoid’s slope is about 5 cm (2.0 in) per kilometer, and up to some 30 cm (12 in) in mountains.
Over a rocket’s few kilometers, that slope moves the undulation by centimeters to decimeters.
For example, take a site where sea level is 25 m (82 ft) below the ellipsoid (). There a point 1,500 m (4,921 ft) above the ellipsoid is written as 1,500 m (4,921 ft) in GeoJSON. In KML it’s written as 1,525 m (5,003 ft).
The first flight leaves at zero, so its two files agree. At the real site, sea level is some tens of meters below the ellipsoid. So give for heights you mean to trust.
How the files are checked
-
Each number is written in the shortest form that reads back to the same number. The tests read every file back and compare it with the recording exactly, not within a tolerance. A value that isn’t a finite number is refused with an error rather than written as
NaNornull, which different programs read differently. -
GeoJSON is checked against the published GeoJSON schema (geojson.org/schema), with longitude before latitude as the standard requires. A test also shows the check rejects a broken file.
-
KML is parsed by a strict XML parser, and checked for the KML 2.2 namespace, the height mode and every coordinate.
-
HPR Sim writes the Parquet file itself, from the format’s specification. The tests read it back with an independent reader, Apache’s own Parquet library for Rust, and compare every number bit for bit. One test uses a recording of every channel (30 columns today) long enough to fill at least three data pages per column. Another compares a small file with bytes worked out by hand from the specification.
Once, by hand, when this was written, pyarrow 25.0.1 and DuckDB 1.5.5 each read the example’s file and a 30-column, 3,005-row file. Each got the same numbers as the matching CSV. CI doesn’t repeat that check.
The tests are in
crates/hpr-sim/src/export.rs
and
crates/hpr-sim/src/export/parquet.rs.
What it leaves out
-
The Parquet file isn’t compressed and carries no per-page minimum and maximum. It takes 8 bytes per number, plus a header of about 20 bytes per page of up to 1,024 numbers. A short index of the columns at the end of the file adds to that. The example’s file is 3,228 bytes, and its CSV about 5.6 kB.
Without the minimums and maximums, a tool such as DuckDB can’t skip parts of the file when filtering (say
WHERE time_s > 10). So it reads it all, which for one flight takes no noticeable time. -
A path over the antimeridian (±180° longitude) isn’t cut in two as RFC 7946 asks. So a map would draw it the long way round the globe.
-
A landing is a point on the ground, without a height.
-
There’s no summary file: the flight’s peaks and margins (Flight metrics) aren’t in these files. A
FlightSummaryconverts to JSON on its own withserde_json::to_string. But that path writes a value that isn’t finite asnullrather than refusing it.
The choices are recorded in two decisions: exports as text built in the core and Parquet written in-house, read back by Apache’s library.
The program
This is the whole program, line for line the file CI runs. Everything above the recorder is the first flight’s setup, which Getting started explains step by step.
//! A flight written out for other programs: the flight of `first_flight.rs`, recorded every 1 s
//! and at every event, saved as CSV, JSON and Parquet tables and as a GeoJSON and a KML map of its
//! path and landing.
//!
//! Run it from anywhere in the repository, naming the folder to write the five files to. Parquet
//! is an optional feature of the library, so the command turns it on:
//!
//! ```text
//! cargo run --example export_flight -p fusionspace-hpr-sim --features parquet -- my-flight
//! ```
//!
//! Without a folder it writes them to `fusionspace-hpr-export` in the system's temporary folder. The
//! documentation site's *Exporting a flight* page (`docs/exporting-a-flight.md`) walks through it.
//! What it prints is kept next to it in `export_flight.output.txt`, and CI checks that the two
//! still agree (`cargo xtask examples --check`).
#![allow(
clippy::print_stdout,
reason = "the project's lints forbid printing in library code, and this program exists to print"
)]
#![allow(
clippy::disallowed_methods,
reason = "the library builds each file's text without I/O; this program writes the files"
)]
use std::error::Error;
use std::path::PathBuf;
use hpr_atmos::ConstantWind;
use hpr_core::geodesy::Geodetic;
use hpr_design::Rocket;
use hpr_sim::{
CanopyType, Channel, Device, DeviceDrag, Environment, FlightMetrics, FlightSettings, Rail,
Recorder, Simulation, Termination, Trigger, export,
};
fn main() -> Result<(), Box<dyn Error>> {
// The first flight: Valetudo on a K400C, from a 3 m vertical rail in New Mexico, in 5 m/s of
// wind from the west, with a drogue at apogee and a main at 150 m.
let rocket: Rocket = serde_json::from_str(include_str!(
"../../../validation/designs/rocketpy-valetudo.json"
))?;
let site = Geodetic::from_degrees(32.99, -106.97, 1400.0)?;
let environment =
Environment::standard(site)?.with_wind(ConstantWind::new(5.0, 270_f64.to_radians())?);
let simulation = Simulation::new(
&rocket,
"example",
environment,
Rail::vertical(3.0),
FlightSettings::default(),
)?
.with_recovery(vec![
Device::new(
"drogue",
DeviceDrag::canopy(CanopyType::FlatCircular, 0.6),
Trigger::Apogee,
)
.with_lag_s(0.5),
Device::new(
"main",
DeviceDrag::canopy(CanopyType::FlatCircular, 2.4),
Trigger::Altitude {
height_above_ground_m: 150.0,
},
)
.with_lag_s(1.0),
])?;
// Two watchers on one flight: the metrics, for the landing, and a recorder of the time, the
// height above the pad and the center of gravity's position, which a map needs.
let recorder = Recorder::new(
vec![
Channel::Time,
Channel::HeightAboveGround,
Channel::CgPosition,
],
Some(1.0),
)?;
let mut watchers = (FlightMetrics::new(), recorder);
let flight = simulation.run(&mut watchers)?;
if flight.termination != Termination::GroundHit {
return Err(format!("the flight ended with {:?}", flight.termination).into());
}
let (metrics, recorder) = watchers;
let summary = metrics.summary(&flight, simulation.environment())?;
// The path on the Earth, then the five files. Each function returns the file's contents:
// text, or bytes for Parquet, which is a binary format.
let track = export::track(&recorder, simulation.environment())?;
let files = [
("flight.csv", export::csv(&recorder)?.into_bytes()),
("flight.json", export::json(&recorder)?.into_bytes()),
("flight.parquet", export::parquet(&recorder)?),
(
"flight.geojson",
export::geojson(&track, &summary)?.into_bytes(),
),
(
"flight.kml",
export::kml(&track, &summary, "Valetudo, K400C")?.into_bytes(),
),
];
let folder = match std::env::args_os().nth(1) {
Some(folder) => PathBuf::from(folder),
None => std::env::temp_dir().join("fusionspace-hpr-export"),
};
std::fs::create_dir_all(&folder)?;
for (name, contents) in &files {
std::fs::write(folder.join(name), contents)?;
}
// What was written, and where it landed, to five decimal places of a degree (about a meter).
// The site is west of Greenwich, so the longitude is printed as degrees west.
println!(
"wrote {} rows of {} columns, a path of {} points",
recorder.rows().len(),
recorder.columns().len(),
track.len()
);
for (name, contents) in &files {
// The Parquet file's size is the same on every system: its numbers take 8 bytes each,
// however many digits they have.
if name.ends_with(".parquet") {
println!(" {name}, {} bytes", contents.len());
} else {
println!(" {name}");
}
}
if let Some(landing) = summary.landing {
println!(
"landed at {:.5}° N, {:.5}° W, {:.0} m from the pad, at {:.1} s",
landing.latitude_deg, -landing.longitude_deg, landing.distance_m, landing.time_s
);
}
Ok(())
}