Interoperabilitetsexporter och -importer

En körning skriver ett resultatdokument, ett diagram och en rapport. --export skriver också scenariots geometri, eller dess syntetiserade signal, i de format som andra verktyg redan läser: en globvisare, en skrivbordskarta, ett geografiskt informationssystem (GIS), ett uppdragsanalyspaket eller ett verktyg för programvarudefinierad radio (SDR). Ingenting här läser en klocka eller nätverket, och ingen export bär en genereringstidsstämpel, så samma scenario ger byteidentiska filer vid varje körning.

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

Filerna skrivs bredvid scenariot och får namn som resultatdokumentet: jamming-demo.czml, jamming-demo.kml, jamming-demo.geojson, en jamming-demo.<object>.e per rörligt objekt (eller jamming-demo.e när det finns ett) och paret l-band-waterfall-jamming.sigmf-meta / .sigmf-data. Med --study-name får de studiens namn i stället, som de andra utdata gör.

Ett format som namnges uttryckligen men inte gäller för scenariot är ett fel som skriver ut skälet; under all skrivs skälet ut och formatet hoppas över. Biblioteksingångarna är kshana::interop::export(src, format), kshana::interop::plan(src) och kshana::interop::geojson::apply_route(src, geojson); de tar scenariotexten och returnerar bytes, utan att röra någon fil, så de körs också i WebAssembly-bygget. Model Context Protocol-servern (MCP) tillhandahåller samma tre som verktygen export_interop, list_export_formats och import_route (se mcp/kshana-mcp/README.md).

Kod: src/interop/ (scene.rs bygger en geometrisk beskrivning av scenariot, czml.rs, kml.rs, geojson.rs och stk.rs skriver den), src/sigmf.rs och src/spectrum.rs för signalen. Tester: tests/interop_formats.rs.

Format#

Vad varje fil innehåller#

Varje geospatialt format skrivs från samma scen, så de kan inte vara oeniga om var något befinner sig. En scen har upp till fyra slags objekt:

• Rörliga objekt — satelliter, och en användarplattform när den rör sig — samplade på scenariots eget tidsrutnät med de propagerare som typens körning använder.
• Fasta platser — en mottagare, en markstation, en jammer eller ursprunget för ett lokalt navigeringssystem.
• Tidslösa spår — de vägpunkter som en typ för alternativ positionering, navigering och tidssynkronisering (PNT) med terräng, gravitation eller kombination flyger. De här typerna har ingen tidsaxel, så spåren bär ingen.
• Jammerfotavtryck — för typen jamming, två cirklar kring jammern: markavståndet inom vilket en satellit i zenit (den starkaste) hamnar under spårningströskeln, så att varje satellit förloras, och avståndet inom vilket en satellit vid elevationsmasken (den svagaste) gör det, så att spårningen börjar misslyckas. Båda kommer från typens egna länkekvationer (Kaplan och Hegarty, Understanding GPS/GNSS (Global Positioning System / Global Navigation Satellite Systems), 3:e uppl., §9,4) med jammern vid mottagarens horisont och friutrymmesdämpning, och testsviten kontrollerar att den effektiva kvoten mellan bärvåg och brustäthet vid varje radie är lika med tröskeln inom 1e-6 dB. Cirkeln ritas på en sfär med jordens medelradie.

CZML#

Det första paketet är dokumentpaketet ("id": "document", "version": "1.0") med en klocka som spänner över tidsrutnätet. Varje rörligt objekt är ett paket vars position har en ISO 8601 (International Organization for Standardization-format för datum och tid) UTC (Coordinated Universal Time) epoch, referenceFrame "INERTIAL" och cartesian sampel [t, x, y, z, ...]: sekunder efter epoken, meter i Geocentric Celestial Reference System (GCRS). CesiumJS tar INERTIAL som International Celestial Reference Frame (ICRF), vars axlar GCRS delar. Fasta platser och fotavtryckens mittpunkter är konstanta jordfasta cartesian-positioner med referenceFrame "FIXED". Ett fotavtryck är en ellipse med båda halvaxlarna lika med sin radie; ett tidslöst spår en markfäst polyline. Varje pakets description anger systemet en gång till i ord.

KML#

Ett <Document> med en <Folder> per objektklass. Ett rörligt objekt är en <Placemark> som innehåller en <gx:Track>: en <when> per sampel (ISO 8601 UTC), därefter en <gx:coord> per sampel (longitud, latitud, höjd). Platser är <Point>er, fotavtryck <Polygon>er vars ring är sluten och moturs, tidslösa spår <LineString>er. Koordinater är longitud och latitud i World Geodetic System 1984 (WGS 84) i decimala grader och höjd i meter över WGS 84-ellipsoiden, skrivna med altitudeMode absolute. KML läser absolute som höjd över medelhavsytan; skillnaden, geoidundulationen, ligger inom cirka ±110 m och tillämpas inte. Dokumentets beskrivning säger det.

GeoJSON#

Ett FeatureCollection. Positioner är [longitude, latitude] eller [longitude, latitude, height] — longitud först, som RFC 7946 kräver — i WGS 84-grader, med höjd i meter över ellipsoiden. Ett rörligt objekt är en LineString med en egenskap times_utc som innehåller en ISO 8601-tid per position; ett spår som korsar meridianen 180° skrivs som en MultiLineString som klipps där, som RFC 7946 §3.1.9 anger (korsningspunkten interpoleras, och times_utc listar då bara de ursprungliga samplen). Platser är Pointer, fotavtryck Polygoner med en sluten yttre ring moturs (§3.1.6), tidslösa spår LineStringer. Varje objekt har en egenskap units som anger enheten för varje numerisk medlem.

STK .e#

En fil per rörligt objekt, eftersom en STK-efemerid beskriver ett fordon. Huvudet anger NumberOfEphemerisPoints (lika med antalet datarader), ScenarioEpoch (UTC, d Mon yyyy hh:mm:ss.ssssss), InterpolationMethod Lagrange med InterpolationSamplesM1 5, CentralBody Earth, CoordinateSystem ICRF och DistanceUnit Meters; raderna under EphemerisTimePosVel är sekunder efter epoken, position i meter och hastighet i meter per sekund, i GCRS. En scen med enbart fasta platser eller tidslösa spår skriver ingen .e-fil: en fast punkt är en STK Facility, inte en efemerid. Ett id som inte är en vanlig del av ett filnamn (ett konstellationsskal och en satellit, Pulsar inclined/S1-0163) skrivs med varje annat tecken som -, numrerat om två id då sammanfaller.

Typen leo-pass och typen leo-pnt-chain (genom sitt steg [pass]) exporterar varje satellit i låg omloppsbana (LEO) och användaren från typens egna propagerare och tidsrutnät. Typen arbetar i ECI0, det jordcentrerade tröghetssystem som är i linje med det jordfasta systemet vid epoken; varje sampel omvandlas till det jordfasta systemet vid sin egen tid med typens jordrotation och därifrån till GCRS via systemet true equator, mean equinox (TEME) som propagatorn Simplified General Perturbations 4 (SGP4) ger utdata i, vid det ögonblicket, med UT1 (Universal Time, jordrotationsvinkeln) satt lika med UTC och polrörelse försummad, som för de andra exporterna. De andra LEO-typerna anger varför ett format inte gäller (tabellen nedan).

Kampanjer#

En campaign exporterar varje medlemsscenario som har geometri som sin egen filuppsättning, med medlemmens etikett insatt före formatsuffixet: varje fas körning (<phase>, eller <phase>-<k> när fasen har flera körningar), svepets basscenario (sweep), Monte Carlo-scenariot (monte-carlo) och varje sammansatt medlem (dess etikett, med de delade värden den binder inskrivna). campaign-shared-jammer-sea-road.toml --export kml skriver campaign-shared-jammer-sea-road.ship-strait.kml och campaign-shared-jammer-sea-road.car-coast-road.kml. En medlem som är identisk med en tidigare skrivs en gång, och värden som en kampanj tillämpar vid körning (överlämningar, svepvärden, frön) finns inte i den exporterade medlemmen. Ett format gäller för en kampanj när det gäller för någon medlem; annars är skälet not 4 i tabellen nedan. Se CAMPAIGNS.md.

SigMF#

Typen spectrum och dess ögonblicksbild [iq] — det modellerade L-bandet ritat som komplexa sampel vid ett ögonblick — som ett par .sigmf-meta / .sigmf-data, i den datatyp som [iq] anger (cf32_le eller ci16_le). Det är samma inspelning som körningen skriver och läser tillbaka för sin egen konsistenskontroll: de exporterade metadata är lika med blocket iq.sigmf.meta i resultatdokumentet, och datafilen har längden iq.sigmf.data_bytes. Skrivaren är src/sigmf.rs, modulen som typen spectrum redan använde; ingenting dupliceras.

Referenssystem och tid#

• Motorn propagerar i TEME (true equator, mean equinox of date), sitt eget system. Rörliga objekt roteras till GCRS med reduktionen nutation::teme_to_gcrs (IAU 2006 precession och IAU 2000B nutation, där IAU är International Astronomical Union), som återger Vallados publicerade TEME-till-GCRF-exempel (Geocentric Celestial Reference Frame) inom 0,11 m, för CZML och STK, och till det jordfasta systemet med frames::teme_to_ecef för KML och GeoJSON. Den jordfasta rotationen är Greenwichs mean sidereal-vinkel med UT1 satt lika med UTC och polrörelse inte tillämpad — samma reduktion som SP3-exporten (Standard Product 3) använder. Vid en GPS-banradie flyttar den försummade UT1−UTC på upp till 0,9 s en satellits longitud med upp till cirka 1,7 km; markplatser påverkas inte, eftersom de anges i latitud och longitud.
• Typen ephemeris är undantaget: dess motorutdata bär redan GCRS- och jordfasta positioner (med scenariots UT1−UTC och polrörelse, eller en verklig serie från International Earth Rotation and Reference Systems Service (IERS)), och de skrivs oförändrade.
• Varje tid är UTC. Skottsekunder modelleras inte: en förskjutning över en skottsekund räknas som om varje dag hade 86 400 s, som motorns tidsrutnät räknar.
• Epoken för t = 0 är den som typens körning använder, och varje fil anger den: typen orbit har epoch; när den saknas, den tidigaste epok som satelliternas egna data bär (en epok för en two-line element set (TLE), referenstiden för en sänd efemerid, starten på en SP3-fil), och 2000-01-01T00:00:00Z först när ingen satellit bär någon (Kepler-element). SP3- och OEM-exporterna (Orbit Ephemeris Message) behåller 2000-01-01T00:00:00Z för ett scenario utan epoch, så för ett sådant scenario skiljer sig deras datum från de här filernas. Utan scenariots epoch roteras varje satellit som bär sin egen epok in i GCRS och de jordfasta systemen vid sitt eget ögonblick (dess epok plus t), eftersom det är det datum dess TEME-position hör till; där satelliternas epoker skiljer sig följer de gemensamma tidsmärkena motorns förutsättning att varje satellit startar vid t = 0, och filen anger med hur många timmar de skiljer sig. SGP4-elementepoken för Walker-konstellationerna i typerna jamming och gnss-sim (2018-06-12T00:00:00Z), som deras körningar också använder för jordrotationen; typen passes har epoch; typen ephemeris har epoch eller TLE-epok. Typen integrity har ingen kalenderepok; dess export datumsätter t = 0 som för ett banscenario utan en.
• Satelliter behåller de positionella identifierarna G01, G02, ... som SP3- och OEM-exporterna ger dem, eftersom propagerarna inte bär TLE:ernas namnrader.

Importer#

• GeoJSON-rutt. --import-route <file> (bibliotek: interop::geojson::apply_route) läser den första LineString i ett GeoJSON-dokument — en ensam geometri, en Feature eller en FeatureCollection — och skriver den till spårindata för terrain-nav, terrain-slam, gravity-map och combined-altpnt (start_lat_deg, start_lon_deg, step_lat_deg, step_lon_deg, waypoints) före körningen. De typerna flyger start + i·step, så en rutt godtas när den är exakt det: dess två ändar (scenariots antal waypoints behålls), eller tre eller fler positioner jämnt fördelade på en rak linje i latitud och longitud, inom 1e-7 grad (cirka 1 cm). Varje annan rutt vägras och felet namnger den position som ligger längst från linjen. En rutt för en typ utan trajektoriaindata vägras med det skälet. Longitud och latitud intervallkontrolleras, vilket fångar upp en fil med latitud först.
• SigMF-inspelning. Blocket [recording] i typen spectrum läser ett par .sigmf-meta / .sigmf-data genom src/sigmf.rs och ritar dess Welch-skattning bredvid modellen (se SPECTRUM.md). Att läsa filer är en funktion i det inbyggda bygget; WebAssembly-bygget tar bytes genom kshana::sigmf::read.

Hur exporterna kontrolleras#

tests/interop_formats.rs tolkar varje export med en validerare skriven utifrån formatets specifikation, inte med skrivarens egen kod:

• CZML: en JSON-array vars första paket är dokumentpaketet med en version; unika paketidentifierare; varje position anger referenceFrame FIXED eller INERTIAL; samplade positioner är [t, x, y, z, ...] med en ISO 8601-epok och ökande tider.
• KML: ett välformat XML-dokument (Extensible Markup Language) i OGC:s KML 2,2-namnrymd med ett rotobjekt; schemats elementordning inuti en Placemark; högst en geometri per Placemark; slutna linjära ringar med fyra eller fler positioner; lon,lat[,alt]-tupler inom intervall; giltiga altitudeMode-värden; styleUrl som går att lösa upp; en gx:Track med lika många <when> som <gx:coord>, och tilläggets namnrymd deklarerad.
• GeoJSON: longitud först och inom intervall, latitud inom intervall, två eller tre tal per position, linjer om två eller fler positioner, slutna yttre ringar moturs, inget segment över meridianen 180°, ingen medlem crs, en egenskap units på varje objekt.
• STK: versionsraden stk.v., ett block BEGIN Ephemeris / END Ephemeris med de nyckelord som krävs, DistanceUnit Meters, NumberOfEphemerisPoints lika med antalet datarader, sju tal per rad, ökande tider.
• SigMF: core:datatype och core:version i global, arrayerna captures och annotations, core:sample_start på varje inspelning, och en datafil med hela sampel.

Utöver strukturen jämförs en satellit som exporteras till CZML och till STK med motorns eget tillstånd efter samma systemreduktion, och stämmer inom 1 mm i position (filerna bär 0,1 mm): mot typen ephemeriss eget GCRS-utdata, och mot en oberoende TEME-till-GCRS-propagering av konstellationen orbit-sgp4-gps, där varje satellit datumsätts med sin egen TLE-epok läst från scenariotexten. Två kontroller går utanför motorn: den första satellitens orbit-sgp4-gps CZML-positioner stämmer inom 0,1 m (uppmätt 2,3 cm) med samma TLE propagerad av Python-paketet sgp4 och reducerad till GCRS av ERFA (Essential Routines for Fundamental Astronomy, den öppna implementationen av IAU:s SOFA-bibliotek), och de jordfasta positionerna för satelliterna orbit-rinex är lika med de sända efemeridpositionerna i gränssnittsspecifikationen för Global Positioning System inom 1 mm. Exporten jamming jordfasta positioner jämförs med de positioner som jammingkörningen poängsätter, inom 5 mm. GeoJSON-rutten går fram och tillbaka genom ett spårscenario, SigMF-paret läses tillbaka till samma bytes, och varje export är byte-deterministisk.

Det här är kontroller mot de publicerade specifikationerna och mot själva motorn. Filerna har inte lästs in i CesiumJS, Google Earth, Ansys STK eller ett SDR-verktyg som en del av testsviten, så godtagande av en viss version av de verktygen är inte testat här.

Utbyte av bana, attityd och kärnor (bibliotek, 0,36)#

Vid sidan av formaten --export lade 0,36 till biblioteksläsare och -skrivare för de standardfiler som uppdragsanalysverktyg utbyter. De tar och returnerar text eller bytes och rör ingen fil. Var och en är en VALIDATED rad i verifieringsmatrisen, mot den oberoende implementation som namnges där:

• CCSDS Orbit Data Messages (kshana::odm, med kshana::ndm_xml för XML-formen): OPM, OMM och OCM i nyckelvärdesnotation (KVN) och NDM/XML, enligt CCSDS 502.0-B-3 (OPM och OMM versionerna 3,0 och 2,0, OCM 3,0). Kontrollerad åt båda hållen mot Orekit: Orekit läser Kshanas filer och Kshana läser Orekits. De fynd som återstår är fastlåsta av tester.
• CCSDS Attitude Data Messages (kshana::adm, med kshana::ndm_xml): AEM och APM enligt CCSDS 504.0-B-2, i KVN och NDM/XML. Kontrollerade mot Orekit på samma sätt, och postrotationerna mot Orekits.
• SPICE SPK (kshana::spk_writer): skrivare och läsare för NAIF SPK-segment av typerna 9 och 13 (med export av en CCSDS OEM till en SPK-kärna) och typerna 3 och 21 (Chebyshev-polynom och utökade differensrader), kontrollerade mot NAIF SPICE-verktygslådans egna läsare, ända ned till byteidentitet. Kshana skriver segmenten från poster den får: den anpassar inte Chebyshev-koefficienter och producerar inga differensrader.

CCSDS OEM-importeraren och -skrivaren samt OEM-kovariansblocket är äldre och beskrivs under importerna ovan och i matrisen.

Begränsningar#

• Bara typerna i tabellen nedan exporterar geometri. Typer vars geometri har Månen, Mars eller en annan himlakropp som centrum exporteras inte: CZML, KML och GeoJSON beskriver positioner kring jorden, och den här versionen skriver STK-filer endast med CentralBody Earth, även om själva STK-formatet tillåter andra centralkroppar.
• constellation-design, earth-gnss-lunar och oem-interop har jordrelaterad geometri som den här versionen inte exporterar; tabellen anger skälet för var och en.
• Typen gnss-ins flyger sin bana i ett plant lokalt tangentplan, så bara planets origo exporteras, inte banan.
• Jordfasta satellitpositioner bortser från UT1−UTC och polrörelse (se Referenssystem och tid); KML-höjder är ellipsoidiska, inte över medelvattenyta.
• Täckningsområden förutsätter fri rymdutbredning, en jammer vid mottagarens horisont och en sfärisk jord för cirkeln.

Varje scenariofil#

Vad kshana <scenario> --export <format> gör för varje fil i scenarios/ (sviten manifest är inte ett scenario och är utelämnad). "ja" betyder att formatet skrivs och klarar sin validerare; annars pekar numret på skälet. Genereras av cargo run --bin gen_validation_artifacts; tests/interop_formats.rs misslyckas när tabellen är föråldrad.

Varför ett format inte är tillämpligt:

1. typerna contact-schedule och acm-link planerar nedlänkskontakter och kodning; exportera ett passes-scenario för samma satellit och station för att se geometrin
2. SigMF innehåller komplexa basbandssampel, som bara typen spectrum syntetiserar
3. typen aocs simulerar attityd kring masscentrum utan bana eller markposition, så det finns inget att placera på jorden
4. scenariots indata har ingen horisontell position (ingen latitud och longitud, inga jordcentrerade koordinater, inga banelement utöver högst en höjd), så det finns inget att placera på jorden
5. typerna eo-radiometry och ascent-losses beräknar budgetar utan jordposition
6. en STK-efemerid beskriver ett farkostens position och hastighet mot tid; den här scenen har bara fasta punkter eller spår utan tidsangivelser (en fast punkt är en STK Facility, inte en efemerid)
7. ingen medlemsscenario i kampanjen har något som det här formatet beskriver; exportera en medlem för sig för att se dess skäl
8. typen leo-signal analyserar signalutformningar (spektrum, spårning, förvärv, kompatibilitet) utan satellit- eller användarposition; exportera scenariot leo-pass eller leo-pnt-chain som flyger utformningen
9. exporteras inte i den här versionen: de sammanslagna positioneringstyperna placerar sina satelliter i ett jordfast system relativt en epok som de aldrig anger, så en tidsstämplad export skulle behöva hitta på kalenderdatumet (exportera scenariot leo-pass eller leo-pnt-chain i stället)
10. typens geometri har Månen, Mars eller en annan himlakropp i solsystemet som centrum; CZML, KML och GeoJSON beskriver positioner på eller kring jorden, och den här versionen skriver STK-efemerider endast med CentralBody Earth
11. exporteras inte i den här versionen: constellation-design placerar sina satelliter i ett kroppsfast system relativt en epok som den aldrig anger, så en tidsstämplad export skulle behöva hitta på kalenderdatumet
12. exporteras inte i den här versionen: jordens konstellation av Global Navigation Satellite System (GNSS) i earth-gnss-lunar ses från en mottagare på månavstånd, vars bana typen inte visar som en tidsserie
13. exporteras inte i den här versionen: typen entry-heating redovisar toppbelastningar och uppvärmning och för inget tidsstämplat markspår
14. typen gnss-ssv svepar tillgänglighet och länkstyrka för en användare på ett skal eller en keplersk bana; den har ingen enskild position att placera på en karta
15. scenariot launch-window anger uppskjutningsplatsens latitud men ingen longitud, så platsen kan inte placeras
16. exporteras inte i den här versionen: sanningsbanan för leo-navmsg är en anpassningsreferens vars jordrotationsvinkel vid epoken är en indata (theta0_deg, standardvärde 0), inte härledd från kalenderdatumet, så dess jordfasta positioner är inte knutna till ett datum
17. det här spektrumscenariot har inget [iq]-block, så inga sampel syntetiseras att spela in
18. exporteras inte i den här versionen: oem-interop läser och skriver ett CCSDS (Consultative Committee for Space Data Systems) Orbit Ephemeris Message, som i sig är utbytesfilen för efemerider
19. typen optical-atmosphere beräknar länkstatistik för markstationer utan tidsstämplad geometri att placera
20. scenariot svepar ett annat scenario över ett rutnät; exportera det svepta scenariot för sig
21. typen time-transfer-budget beräknar en länkbudget och stabiliteter, utan tidsstämplad geometri att placera