Interoperability exports and imports

A run writes a result document, a chart and a report. --export also writes the scenario's geometry, or its synthesised signal, in the formats other tools already read: a globe viewer, a desktop map, a geographic information system (GIS), a mission-analysis package or a software-defined-radio (SDR) tool. Nothing here reads a clock or the network, and no export carries a generation timestamp, so the same scenario gives byte-identical files on every run.

kshana scenarios/jamming-demo.toml --export czml            # one format
kshana scenarios/jamming-demo.toml --export kml --export geojson
kshana scenarios/jamming-demo.toml --export all             # every format that applies
kshana scenarios/jamming-demo.toml --export list            # which apply, and why not, without running
kshana scenarios/terrain-nav.toml --import-route route.geojson --export geojson

Files are written next to the scenario, named like the result document: jamming-demo.czml, jamming-demo.kml, jamming-demo.geojson, one jamming-demo.<object>.e per moving object (or jamming-demo.e when there is one), and the pair l-band-waterfall-jamming.sigmf-meta / .sigmf-data. With --study-name they take the study's name instead, as the other outputs do.

A format named explicitly that does not apply to the scenario is an error that prints the reason; under all the reason is printed and the format skipped. The library entry points are kshana::interop::export(src, format), kshana::interop::plan(src) and kshana::interop::geojson::apply_route(src, geojson); they take the scenario text and return bytes, touching no file, so they run in the WebAssembly build too. The Model Context Protocol (MCP) server serves the same three as the tools export_interop, list_export_formats and import_route (see mcp/kshana-mcp/README.md).

Code: src/interop/ (scene.rs builds one geometric description of the scenario, czml.rs, kml.rs, geojson.rs and stk.rs write it), src/sigmf.rs and src/spectrum.rs for the signal. Tests: tests/interop_formats.rs.

Formats#

What each file holds#

Every geospatial format is written from the same scene, so they cannot disagree about where anything is. A scene has up to four kinds of object:

• Moving objects — satellites, and a user platform when it moves — sampled on the scenario's own time grid with the propagators the kind's run uses.
• Fixed sites — a receiver, a ground station, a jammer, or the origin of a local navigation frame.
• Untimed tracks — the waypoints a terrain, gravity or combined alternative positioning, navigation and timing (PNT) kind flies. These kinds have no time axis, so the tracks carry none.
• Jammer footprints — for the jamming kind, two circles about the jammer: the ground range inside which a satellite at the zenith (the strongest) falls below the tracking threshold, so every satellite is lost, and the range inside which a satellite at the elevation mask (the weakest) does, so tracking starts to fail. Both come from the kind's own link equations (Kaplan and Hegarty, Understanding GPS/GNSS (Global Positioning System / Global Navigation Satellite Systems), 3rd ed., §9.4) with the jammer at the receiver's horizon and free-space loss, and the test suite checks that the effective carrier-to-noise density ratio at each radius equals the threshold to 1e-6 dB. The circle is drawn on a sphere of the Earth's mean radius.

CZML#

The first packet is the document packet ("id": "document", "version": "1.0") with a clock spanning the time grid. Each moving object is a packet whose position has an ISO 8601 (International Organization for Standardization date and time format) UTC (Coordinated Universal Time) epoch, referenceFrame "INERTIAL", and cartesian samples [t, x, y, z, ...]: seconds after the epoch, metres in the Geocentric Celestial Reference System (GCRS). CesiumJS takes INERTIAL as the International Celestial Reference Frame (ICRF), whose axes the GCRS shares. Fixed sites and footprint centres are constant Earth-fixed cartesian positions with referenceFrame "FIXED". A footprint is an ellipse with both semi-axes equal to its radius; an untimed track a ground-clamped polyline. Each packet's description states the frame again in words.

KML#

One <Document> with a <Folder> per object class. A moving object is a <Placemark> holding a <gx:Track>: one <when> per sample (ISO 8601 UTC), then one <gx:coord> per sample (longitude, latitude, height). Sites are <Point>s, footprints <Polygon>s whose ring is closed and counter-clockwise, untimed tracks <LineString>s. Coordinates are World Geodetic System 1984 (WGS 84) longitude and latitude in decimal degrees and height in metres above the WGS 84 ellipsoid, written with altitudeMode absolute. KML reads absolute as height above mean sea level; the difference, the geoid undulation, is within about ±110 m and is not applied. The document's description says so.

GeoJSON#

One FeatureCollection. Positions are [longitude, latitude] or [longitude, latitude, height] — longitude first, as RFC 7946 requires — in WGS 84 degrees, with height in metres above the ellipsoid. A moving object is a LineString with a times_utc property holding one ISO 8601 time per position; a track that crosses the 180° meridian is written as a MultiLineString cut there, as RFC 7946 §3.1.9 asks (the crossing point is interpolated, and times_utc then lists the original samples only). Sites are Points, footprints Polygons with a closed counter-clockwise exterior ring (§3.1.6), untimed tracks LineStrings. Every feature has a units property naming the unit of each numeric member.

STK .e#

One file per moving object, since an STK ephemeris describes one vehicle. The header gives NumberOfEphemerisPoints (equal to the number of data rows), ScenarioEpoch (UTC, d Mon yyyy hh:mm:ss.ssssss), InterpolationMethod Lagrange with InterpolationSamplesM1 5, CentralBody Earth, CoordinateSystem ICRF and DistanceUnit Meters; the rows under EphemerisTimePosVel are seconds after the epoch, position in metres and velocity in metres per second, in the GCRS. A scene with only fixed sites or untimed tracks writes no .e file: a fixed point is an STK Facility, not an ephemeris. An id that is not a plain file-name part (a constellation shell and a satellite, Pulsar inclined/S1-0163) is written with every other character as -, numbered if two ids then coincide.

The leo-pass kind and the leo-pnt-chain kind (through its [pass] stage) export every low Earth orbit (LEO) satellite and the user from the kind's own propagators and time grid. The kind works in ECI0, the Earth-centred inertial frame aligned with the Earth-fixed frame at the epoch; each sample is turned into the Earth-fixed frame at its own time by the kind's Earth rotation and from there into the GCRS through the true equator, mean equinox (TEME) frame that the Simplified General Perturbations 4 (SGP4) propagator outputs in, at that instant, with UT1 (Universal Time, the Earth-rotation angle) taken equal to UTC and polar motion neglected, as for the other exports. The other LEO kinds state why a format does not apply (the table below).

Campaigns#

A campaign exports each member scenario that has geometry as its own file set, the member's label inserted before the format suffix: every phase run (<phase>, or <phase>-<k> when the phase has several runs), the sweep's base scenario (sweep), the Monte Carlo scenario (monte-carlo) and each composed member (its label, with the shared values it binds written in). campaign-shared-jammer-sea-road.toml --export kml writes campaign-shared-jammer-sea-road.ship-strait.kml and campaign-shared-jammer-sea-road.car-coast-road.kml. A member identical to an earlier one is written once, and values a campaign applies at run time (hand-offs, sweep values, seeds) are not in the exported member. A format applies to a campaign when it applies to any member; otherwise the reason is note 4 of the table below. See CAMPAIGNS.md.

SigMF#

The spectrum kind's [iq] snapshot — the modelled L band drawn as complex samples at one instant — as a .sigmf-meta / .sigmf-data pair, in the data type [iq] names (cf32_le or ci16_le). It is the same recording the run writes and reads back for its own consistency check: the exported metadata equals the iq.sigmf.meta block of the result document, and the data file has the iq.sigmf.data_bytes length. The writer is src/sigmf.rs, the module the spectrum kind already used; nothing is duplicated.

Frames and time#

• The engine propagates in TEME (true equator, mean equinox of date), its native frame. Moving objects are rotated to the GCRS by the nutation::teme_to_gcrs reduction (IAU 2006 precession and IAU 2000B nutation, where IAU is the International Astronomical Union), which reproduces Vallado's published TEME-to-GCRF (Geocentric Celestial Reference Frame) example to 0.11 m, for CZML and STK, and to the Earth-fixed frame by frames::teme_to_ecef for KML and GeoJSON. The Earth-fixed rotation is the Greenwich mean sidereal angle with UT1 taken equal to UTC and polar motion not applied — the same reduction the SP3 (Standard Product 3) export uses. At a GPS orbit radius the neglected UT1−UTC of up to 0.9 s moves a satellite's longitude by up to about 1.7 km; ground sites are unaffected, since they are given in latitude and longitude.
• The ephemeris kind is the exception: its engine output already carries GCRS and Earth-fixed positions (with the scenario's UT1−UTC and polar motion, or a real International Earth Rotation and Reference Systems Service (IERS) series), and those are written unchanged.
• Every time is UTC. Leap seconds are not modelled: an offset across a leap second is counted as if every day had 86 400 s, as the engine's time grids count.
• The epoch of t = 0 is the one the kind's run uses, and each file names it: the orbit kind's epoch; when it is absent, the earliest epoch the satellites' own data carry (a two-line element set (TLE) epoch, a broadcast ephemeris's reference time, an SP3 file's start), and 2000-01-01T00:00:00Z only when no satellite carries one (Keplerian elements). The SP3 and OEM (Orbit Ephemeris Message) exports keep 2000-01-01T00:00:00Z for a scenario without an epoch, so for such a scenario their dates differ from these files'. With no scenario epoch, each satellite that carries its own epoch is rotated into the GCRS and Earth-fixed frames at its own instant (its epoch plus t), since that is the date its TEME position belongs to; where the satellites' epochs differ, the shared time tags follow the engine's premise that every satellite starts at t = 0, and the file says by how many hours they differ. The SGP4 element epoch of the jamming and gnss-sim kinds' Walker constellations (2018-06-12T00:00:00Z), which their runs also use for the Earth rotation; the passes kind's epoch; the ephemeris kind's epoch or TLE epoch. The integrity kind has no calendar epoch; its export dates t = 0 as for an orbit scenario without one.
• Satellites keep the positional identifiers G01, G02, ... the SP3 and OEM exports give them, because the propagators do not carry the TLE name lines.

Imports#

• GeoJSON route. --import-route <file> (library: interop::geojson::apply_route) reads the first LineString of a GeoJSON document — a bare geometry, a Feature, or a FeatureCollection — and writes it into the track inputs of terrain-nav, terrain-slam, gravity-map and combined-altpnt (start_lat_deg, start_lon_deg, step_lat_deg, step_lon_deg, waypoints) before the run. Those kinds fly start + i·step, so a route is accepted when it is exactly that: its two ends (the scenario's waypoints count is kept), or three or more positions evenly spaced on a straight line in latitude and longitude, to within 1e-7 degree (about 1 cm). Any other route is refused and the error names the position furthest off the line. A route for a kind with no trajectory input is refused with that reason. Longitude and latitude are range-checked, which catches a latitude-first file.
• SigMF recording. The spectrum kind's [recording] block reads a .sigmf-meta / .sigmf-data pair through src/sigmf.rs and plots its Welch estimate beside the model (see SPECTRUM.md). Reading files is a native-build feature; the WebAssembly build takes the bytes through kshana::sigmf::read.

How the exports are checked#

tests/interop_formats.rs parses every export with a validator written from the format's specification, not with the writer's own code:

• CZML: a JSON array whose first packet is the document packet with a version; unique packet identifiers; every position states referenceFrame FIXED or INERTIAL; sampled positions are [t, x, y, z, ...] with an ISO 8601 epoch and increasing times.
• KML: a well-formed XML (Extensible Markup Language) document in the OGC KML 2.2 namespace with one root feature; the schema's element order inside a Placemark; at most one geometry per Placemark; closed linear rings of four or more positions; lon,lat[,alt] tuples in range; valid altitudeMode values; styleUrls that resolve; a gx:Track with as many <when> as <gx:coord>, and the extension namespace declared.
• GeoJSON: longitude first and in range, latitude in range, two or three numbers per position, line strings of two or more positions, closed counter-clockwise exterior rings, no segment across the 180° meridian, no crs member, a units property on every feature.
• STK: the stk.v. version line, a BEGIN Ephemeris / END Ephemeris block with the required keywords, DistanceUnit Meters, NumberOfEphemerisPoints equal to the number of data rows, seven numbers per row, increasing times.
• SigMF: core:datatype and core:version in global, captures and annotations arrays, core:sample_start on every capture, and a data file of whole samples.

Beyond structure, a satellite exported to CZML and to STK is compared with the engine's own state after the same frame reduction, and agrees to 1 mm in position (the files carry 0.1 mm): against the ephemeris kind's own GCRS output, and against an independent TEME-to-GCRS propagation of the orbit-sgp4-gps constellation, each satellite dated by its own TLE epoch read from the scenario text. Two checks go outside the engine: the first orbit-sgp4-gps satellite's CZML positions agree to 0.1 m (measured 2.3 cm) with the same TLE propagated by the sgp4 Python package and reduced to the GCRS by ERFA (Essential Routines for Fundamental Astronomy, the open implementation of the IAU's SOFA library), and the orbit-rinex satellites' Earth-fixed positions equal the broadcast-ephemeris positions of the Global Positioning System interface specification to 1 mm. The jamming export's Earth-fixed positions are compared with the positions the jamming run scores, to 5 mm. The GeoJSON route round-trips through a track scenario, the SigMF pair reads back to the same bytes, and every export is byte-deterministic.

These are checks against the published specifications and against the engine itself. The files have not been loaded into CesiumJS, Google Earth, Ansys STK or an SDR tool as part of the test suite, so acceptance by a particular version of those tools is not tested here.

Limitations#

• Only the kinds in the table below export geometry. Kinds whose geometry is centred on the Moon, Mars or another body are not exported: CZML, KML and GeoJSON describe positions about the Earth, and this release writes STK files with CentralBody Earth only, although the STK format itself allows other central bodies.
• constellation-design, earth-gnss-lunar and oem-interop have Earth-referenced geometry that this release does not export; the table gives the reason for each.
• The gnss-ins kind flies its trajectory in a flat local tangent plane, so only the plane's origin is exported, not the trajectory.
• Earth-fixed satellite positions neglect UT1−UTC and polar motion (see Frames and time); KML heights are ellipsoidal, not above mean sea level.
• Footprints assume free-space propagation, a jammer at the receiver's horizon and a spherical Earth for the circle.

Every scenario file#

What kshana <scenario> --export <format> does for each file in scenarios/ (the suite manifest is not a scenario and is left out). "yes" means the format is written and passes its validator; otherwise the number points to the reason. Generated by cargo run --bin gen_validation_artifacts; tests/interop_formats.rs fails when it is stale.

Why a format does not apply:

1. the scenario input carries no horizontal position (no latitude and longitude, no Earth-centred coordinates, no orbital elements beyond at most an altitude), so there is nothing to place on the Earth
2. SigMF holds complex baseband samples, which only the spectrum kind synthesises
3. an STK ephemeris describes a vehicle's position and velocity against time; this scene has only fixed points or untimed tracks (a fixed point is an STK Facility, not an ephemeris)
4. no member scenario of the campaign has anything this format describes; export a member on its own to see its reason
5. the leo-signal kind analyses signal designs (spectra, tracking, acquisition, compatibility) with no satellite or user position; export the leo-pass or leo-pnt-chain scenario that flies the design
6. not exported in this release: the fused positioning kinds place their satellites in an Earth-fixed frame relative to an epoch they never name, so a time-tagged export would have to invent the calendar date (export the leo-pass or leo-pnt-chain scenario instead)
7. the kind's geometry is centred on the Moon, Mars or another solar-system body; CZML, KML and GeoJSON describe positions on or about the Earth, and this release writes STK ephemerides with CentralBody Earth only
8. not exported in this release: constellation-design places its satellites in a body-fixed frame relative to an epoch it never names, so a time-tagged export would have to invent the calendar date
9. not exported in this release: the Earth Global Navigation Satellite System (GNSS) constellation of earth-gnss-lunar is seen from a receiver at lunar distance, whose trajectory the kind does not expose as a time series
10. the launch-window scenario gives the launch site's latitude but no longitude, so the site cannot be placed
11. not exported in this release: the leo-navmsg truth orbit is a fitting reference whose Earth rotation angle at the epoch is an input (theta0_deg, default 0), not derived from the calendar date, so its Earth-fixed positions are not tied to a date
12. this spectrum scenario has no [iq] block, so no samples are synthesised to record
13. not exported in this release: oem-interop reads and writes a CCSDS (Consultative Committee for Space Data Systems) Orbit Ephemeris Message, which is itself the ephemeris interchange file
14. the scenario sweeps another scenario over a grid; export the swept scenario on its own