Exporty a importy pro interoperabilitu

Běh zapisuje dokument s výsledkem, graf a zprávu. --export zapisuje navíc geometrii scénáře nebo jeho syntetizovaný signál ve formátech, které už jiné nástroje čtou: prohlížeč zeměkoule, desktopová mapa, geografický informační systém (GIS), balík pro analýzu misí nebo nástroj softwarově definovaného rádia (SDR). Nic z toho nečte hodiny ani síť a žádný export nenese časové razítko vytvoření, takže stejný scénář dává při každém běhu bajt po bajtu shodné soubory.

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

Soubory se zapisují vedle scénáře a jmenují se jako dokument s výsledkem: jamming-demo.czml, jamming-demo.kml, jamming-demo.geojson, jeden jamming-demo.<object>.e na každý pohybující se objekt (nebo jamming-demo.e, když je jen jeden) a dvojice l-band-waterfall-jamming.sigmf-meta / .sigmf-data. S --study-name nesou místo toho název studie, jako ostatní výstupy.

Výslovně uvedený formát, který se na scénář nevztahuje, je chyba, která vypíše důvod; pod all se důvod vypíše a formát se přeskočí. Vstupními body knihovny jsou kshana::interop::export(src, format), kshana::interop::plan(src) a kshana::interop::geojson::apply_route(src, geojson); přijímají text scénáře a vracejí bajty, bez doteku souborů, takže běží i v sestavení pro WebAssembly. Server Model Context Protocol (MCP) poskytuje tytéž tři jako nástroje export_interop, list_export_formats a import_route (viz mcp/kshana-mcp/README.md).

Kód: src/interop/ (scene.rs sestaví jeden geometrický popis scénáře, czml.rs, kml.rs, geojson.rs a stk.rs jej zapisují), src/sigmf.rs a src/spectrum.rs pro signál. Testy: tests/interop_formats.rs.

Formáty#

Co který soubor obsahuje#

Každý geoprostorový formát se zapisuje ze stejné scény, takže se nemohou lišit v tom, kde co je. Scéna má až čtyři druhy objektů:

• Pohybující se objekty — družice a uživatelská platforma, když se pohybuje — vzorkované na vlastní časové mřížce scénáře propagátory, které používá běh daného druhu.
• Pevná stanoviště — přijímač, pozemní stanice, rušička nebo počátek místní navigační soustavy.
• Netimované stopy — body trasy, kterou letí druh pro alternativní určování polohy, navigace a času (PNT) založený na terénu, gravitaci nebo jejich kombinaci. Tyto druhy nemají časovou osu, takže stopy žádnou nenesou.
• Stopy rušičky — pro druh jamming dvě kružnice kolem rušičky: pozemní dosah, uvnitř něhož družice v zenitu (nejsilnější) klesne pod práh sledování, takže jsou ztraceny všechny družice, a dosah, uvnitř něhož to platí pro družici na elevační masce (nejslabší), takže sledování začíná selhávat. Obě vycházejí z vlastních rovnic spoje daného druhu (Kaplan a Hegarty, Understanding GPS/GNSS (Global Positioning System / Global Navigation Satellite Systems), 3. vyd., §9,4) s rušičkou na horizontu přijímače a ztrátou ve volném prostoru a testovací sada kontroluje, že efektivní poměr nosné a hustoty šumu na každém poloměru se rovná prahu s přesností 1e-6 dB. Kružnice je kreslena na kouli o středním poloměru Země.

CZML#

První paket je dokumentový paket ("id": "document", "version": "1.0") s hodinami zahrnujícími časovou mřížku. Každý pohybující se objekt je paket, jehož position má epoch ve formátu ISO 8601 (formát data a času Mezinárodní organizace pro normalizaci) UTC (koordinovaný světový čas), referenceFrame "INERTIAL" a vzorky cartesian [t, x, y, z, ...]: sekundy po epoše, metry v Geocentric Celestial Reference System (GCRS). CesiumJS bere INERTIAL jako International Celestial Reference Frame (ICRF), jehož osy GCRS sdílí. Pevná stanoviště a středy stop jsou konstantní polohy cartesian vztažené k Zemi s referenceFrame "FIXED". Stopa rušičky je ellipse s oběma poloosami rovnými jejímu poloměru; netimovaná stopa je polyline přichycená k zemi. description každého paketu uvádí soustavu ještě jednou slovy.

KML#

Jeden <Document> s jednou <Folder> na třídu objektů. Pohybující se objekt je <Placemark> obsahující <gx:Track>: jedno <when> na vzorek (ISO 8601 UTC), pak jedno <gx:coord> na vzorek (délka, šířka, výška). Stanoviště jsou <Point>y, stopy rušičky <Polygon>y s uzavřeným prstencem proti směru hodinových ručiček, netimované stopy <LineString>y. Souřadnice jsou zeměpisná délka a šířka World Geodetic System 1984 (WGS 84) v desetinných stupních a výška v metrech nad elipsoidem WGS 84, zapsané s altitudeMode absolute. KML čte absolute jako výšku nad střední hladinou moře; rozdíl, undulace geoidu, je v rozmezí asi ±110 m a neaplikuje se. Popis dokumentu to uvádí.

GeoJSON#

Jeden FeatureCollection. Polohy jsou [longitude, latitude] nebo [longitude, latitude, height] — nejdřív délka, jak vyžaduje RFC 7946 — ve stupních WGS 84, s výškou v metrech nad elipsoidem. Pohybující se objekt je LineString s vlastností times_utc obsahující jeden čas ISO 8601 na každou polohu; stopa, která kříží poledník 180°, se zapíše jako MultiLineString přerušená tam, jak žádá RFC 7946 §3.1.9 (bod křížení se interpoluje a times_utc pak uvádí jen původní vzorky). Stanoviště jsou Pointy, stopy rušičky Polygony s uzavřeným vnějším prstencem proti směru hodinových ručiček (§3.1.6), netimované stopy LineStringy. Každý prvek má vlastnost units pojmenovávající jednotku každého číselného člena.

STK .e#

Jeden soubor na pohybující se objekt, protože efemerida STK popisuje jedno vozidlo. Záhlaví uvádí NumberOfEphemerisPoints (rovno počtu datových řádků), ScenarioEpoch (UTC, d Mon yyyy hh:mm:ss.ssssss), InterpolationMethod Lagrange s InterpolationSamplesM1 5, CentralBody Earth, CoordinateSystem ICRF a DistanceUnit Meters; řádky pod EphemerisTimePosVel jsou sekundy po epoše, poloha v metrech a rychlost v metrech za sekundu v GCRS. Scéna jen s pevnými stanovišti nebo netimovanými stopami nezapíše žádný soubor .e: pevný bod je STK Facility, nikoli efemerida. Id, které není prostou částí názvu souboru (skořepina konstelace a družice, Pulsar inclined/S1-0163), se zapíše s každým jiným znakem jako -, číslované, pokud by se dvě id pak shodovala.

Druh leo-pass a druh leo-pnt-chain (přes svou fázi [pass]) exportují každou družici na nízké oběžné dráze Země (LEO) i uživatele z vlastních propagátorů a časové mřížky daného druhu. Druh pracuje v ECI0, geocentrické inerciální soustavě zarovnané se soustavou vztaženou k Zemi v epoše; každý vzorek se otočí do soustavy vztažené k Zemi v jeho vlastním čase rotací Země daného druhu a odtud do GCRS přes soustavu true equator, mean equinox (TEME), v níž vydává výstup propagátor Simplified General Perturbations 4 (SGP4), v daném okamžiku, přičemž UT1 (Universal Time, úhel rotace Země) se klade rovno UTC a polární pohyb se zanedbává, jako u ostatních exportů. Ostatní druhy LEO uvádějí, proč se formát neuplatňuje (tabulka níže).

Kampaně#

campaign exportuje každý členský scénář, který má geometrii, jako vlastní sadu souborů, s označením člena vloženým před příponu formátu: každý běh fáze (<phase>, nebo <phase>-<k>, když má fáze několik běhů), základní scénář sweepu (sweep), scénář Monte Carlo (monte-carlo) a každý složený člen (jeho označení, s vázanými sdílenými hodnotami zapsanými dovnitř). campaign-shared-jammer-sea-road.toml --export kml zapíše campaign-shared-jammer-sea-road.ship-strait.kml a campaign-shared-jammer-sea-road.car-coast-road.kml. Člen shodný s dřívějším se zapíše jednou a hodnoty, které kampaň aplikuje za běhu (předání, hodnoty sweepu, seedy), nejsou v exportovaném členu. Formát se na kampaň vztahuje, když se vztahuje na kterýkoli člen; jinak je důvod v poznámce 4 tabulky níže. Viz CAMPAIGNS.md.

SigMF#

Snímek [iq] druhu spectrum — modelované pásmo L vykreslené jako komplexní vzorky v jednom okamžiku — jako dvojice .sigmf-meta / .sigmf-data v datovém typu, který pojmenovává [iq] (cf32_le nebo ci16_le). Je to tatáž nahrávka, kterou běh zapisuje a zpětně čte pro vlastní kontrolu konzistence: exportovaná metadata se rovnají bloku iq.sigmf.meta dokumentu s výsledkem a datový soubor má délku iq.sigmf.data_bytes. Zapisovač je src/sigmf.rs, modul, který už druh spectrum používal; nic se neduplikuje.

Soustavy a čas#

• Engine propaguje v TEME (true equator, mean equinox of date), své nativní soustavě. Pohybující se objekty se do GCRS otáčejí redukcí nutation::teme_to_gcrs (precese IAU 2006 a nutace IAU 2000B, kde IAU je Mezinárodní astronomická unie), která reprodukuje Valladův publikovaný příklad TEME–GCRF (Geocentric Celestial Reference Frame) s přesností 0,11 m, pro CZML a STK, a do soustavy vztažené k Zemi pomocí frames::teme_to_ecef pro KML a GeoJSON. Rotace do soustavy vztažené k Zemi je greenwichský střední hvězdný úhel s UT1 rovným UTC a bez aplikovaného polárního pohybu — tatáž redukce, kterou používá export SP3 (Standard Product 3). Při poloměru dráhy GPS zanedbané UT1−UTC až 0,9 s posune zeměpisnou délku družice až o asi 1,7 km; pozemní stanoviště to neovlivní, protože jsou dána zeměpisnou šířkou a délkou.
• Výjimkou je druh ephemeris: jeho výstup enginu už nese polohy v GCRS i v soustavě vztažené k Zemi (s UT1−UTC a polárním pohybem scénáře nebo se skutečnou řadou International Earth Rotation and Reference Systems Service (IERS)) a ty se zapisují beze změny.
• Každý čas je UTC. Přestupné sekundy se nemodelují: posun přes přestupnou sekundu se počítá, jako by každý den měl 86 400 s, jak počítají časové mřížky enginu.
• Epocha t = 0 je ta, kterou používá běh daného druhu, a každý soubor ji uvádí: epoch druhu orbit; pokud chybí, nejstarší epocha, kterou nesou vlastní data družic (epocha dvouřádkové sady prvků (TLE), referenční čas vysílané efemeridy, začátek souboru SP3), a 2000-01-01T00:00:00Z jen tehdy, když ji nenese žádná družice (keplerovské prvky). Exporty SP3 a OEM (Orbit Ephemeris Message) ponechávají 2000-01-01T00:00:00Z pro scénář bez epoch, takže se pro takový scénář jejich data od těchto souborů liší. Bez epoch scénáře se každá družice, která nese vlastní epochu, otáčí do GCRS a soustav vztažených k Zemi v jejím vlastním okamžiku (její epocha plus t), protože k tomuto datu patří její poloha v TEME; kde se epochy družic liší, sdílené časové značky sledují předpoklad enginu, že každá družice začíná v t = 0, a soubor uvádí, o kolik hodin se liší. Epocha prvků SGP4 Walkerových konstelací druhů jamming a gnss-sim (2018-06-12T00:00:00Z), kterou jejich běhy používají také pro rotaci Země; epoch druhu passes; epoch nebo epocha TLE druhu ephemeris. Druh integrity nemá kalendářní epochu; jeho export datuje t = 0 jako u scénáře orbit bez ní.
• Družice si ponechávají poziční identifikátory G01, G02, ..., které jim dávají exporty SP3 a OEM, protože propagátory nenesou řádky s názvy z TLE.

Importy#

• Trasa GeoJSON. --import-route <file> (knihovna: interop::geojson::apply_route) čte první LineString dokumentu GeoJSON — samostatnou geometrii, Feature nebo FeatureCollection — a zapisuje jej do vstupů stopy druhů terrain-nav, terrain-slam, gravity-map a combined-altpnt (start_lat_deg, start_lon_deg, step_lat_deg, step_lon_deg, waypoints) před během. Tyto druhy létají start + i·step, takže trasa se přijme, jen když je přesně taková: její dva konce (počet waypoints scénáře se zachová) nebo tři či více poloh rovnoměrně rozmístěných na přímce v zeměpisné šířce a délce, s přesností 1e-7 stupně (asi 1 cm). Každá jiná trasa se odmítne a chyba jmenuje polohu nejvíce vzdálenou od přímky. Trasa pro druh bez vstupu trajektorie se odmítne s tímto důvodem. Zeměpisná délka a šířka se kontrolují na rozsah, což zachytí soubor s šířkou na prvním místě.
• Nahrávka SigMF. Blok [recording] druhu spectrum čte dvojici .sigmf-meta / .sigmf-data přes src/sigmf.rs a vykresluje svůj odhad Welch vedle modelu (viz SPECTRUM.md). Čtení souborů je funkce nativního sestavení; sestavení pro WebAssembly přebírá bajty přes kshana::sigmf::read.

Jak se exporty kontrolují#

tests/interop_formats.rs zpracuje každý export validátorem napsaným podle specifikace formátu, nikoli kódem samotného zapisovače:

• CZML: pole JSON, jehož první paket je dokumentový paket s version; jedinečné identifikátory paketů; každá poloha uvádí referenceFrame FIXED nebo INERTIAL; vzorkované polohy jsou [t, x, y, z, ...] s epochou ISO 8601 a rostoucími časy.
• KML: dobře utvořený dokument XML (Extensible Markup Language) v jmenném prostoru OGC KML 2,2 s jedním kořenovým prvkem; pořadí prvků schématu uvnitř Placemark; nejvýše jedna geometrie na Placemark; uzavřené lineární prstence o čtyřech či více polohách; n-tice lon,lat[,alt] v rozsahu; platné hodnoty altitudeMode; styleUrl, které se dají přeložit na existující styl; gx:Track s tolika <when> jako <gx:coord> a deklarovaný jmenný prostor rozšíření.
• GeoJSON: délka na prvním místě a v rozsahu, šířka v rozsahu, dvě nebo tři čísla na polohu, lomené čáry o dvou či více polohách, uzavřené vnější prstence proti směru hodinových ručiček, žádný úsek přes poledník 180°, žádný člen crs, vlastnost units u každého prvku.
• STK: řádek verze stk.v., blok BEGIN Ephemeris / END Ephemeris s požadovanými klíčovými slovy, DistanceUnit Meters, NumberOfEphemerisPoints rovno počtu datových řádků, sedm čísel na řádek, rostoucí časy.
• SigMF: core:datatype a core:version v global, pole captures a annotations, core:sample_start u každého záznamu a datový soubor z celých vzorků.

Kromě struktury se družice exportovaná do CZML a do STK porovnává s vlastním stavem enginu po téže redukci soustavy a shoduje se na 1 mm v poloze (soubory nesou 0,1 mm): proti vlastnímu výstupu GCRS druhu ephemeris a proti nezávislé propagaci TEME–GCRS konstelace orbit-sgp4-gps, přičemž každá družice je datována vlastní epochou TLE přečtenou z textu scénáře. Dvě kontroly jdou mimo engine: polohy CZML první družice orbit-sgp4-gps se shodují na 0,1 m (naměřeno 2,3 cm) s toutéž TLE propagovanou balíčkem Pythonu sgp4 a redukovanou do GCRS pomocí ERFA (Essential Routines for Fundamental Astronomy, otevřená implementace knihovny SOFA od IAU) a polohy družic orbit-rinex vztažené k Zemi se rovnají polohám z vysílané efemeridy podle specifikace rozhraní Global Positioning System na 1 mm. Polohy vztažené k Zemi z exportu jamming se porovnávají s polohami, které hodnotí běh rušení, na 5 mm. Trasa GeoJSON projde zpáteční cestou přes scénář stopy, dvojice SigMF se přečte zpět na tytéž bajty a každý export je bajtově deterministický.

Jde o kontroly proti publikovaným specifikacím a proti samotnému enginu. Soubory nebyly v rámci testovací sady načteny do CesiumJS, Google Earth, Ansys STK ani nástroje SDR, takže přijetí konkrétní verzí těchto nástrojů se zde netestuje.

Výměna drah, orientace a jader (knihovna, 0,36)#

Vedle formátů --export přidala verze 0,36 knihovní čtečky a zapisovače standardních souborů, které si vyměňují nástroje pro analýzu misí. Přijímají a vracejí text či bajty a nedotýkají se souborů. Každý je řádek VALIDATED v ověřovací matici, proti nezávislé implementaci tam uvedené:

• CCSDS Orbit Data Messages (kshana::odm, s kshana::ndm_xml pro formu XML): OPM, OMM a OCM v zápisu klíč–hodnota (KVN) a NDM/XML podle CCSDS 502.0-B-3 (OPM a OMM verze 3,0 a 2,0, OCM 3,0). Zkontrolováno oběma směry proti Orekit: Orekit čte soubory Kshany a Kshana čte soubory Orekit. Zbylá zjištění jsou zafixována testy.
• CCSDS Attitude Data Messages (kshana::adm, s kshana::ndm_xml): AEM a APM podle CCSDS 504.0-B-2, v KVN a NDM/XML. Zkontrolováno proti Orekit stejným způsobem a rotace záznamů proti rotacím Orekit.
• SPICE SPK (kshana::spk_writer): zapisovače a čtečky segmentů NAIF SPK typů 9 a 13 (s exportem CCSDS OEM do jádra SPK) a typů 3 a 21 (Čebyševovy polynomy a rozšířené diferenční řádky), zkontrolované proti vlastním čtečkám knihovny NAIF SPICE, až na shodu bajt po bajtu. Kshana zapisuje segmenty ze záznamů, které dostane: Čebyševovy koeficienty neprokládá ani diferenční řádky nevytváří.

Importér a zapisovač CCSDS OEM a blok kovariance OEM jsou starší a jsou popsány v importech výše a v matici.

Omezení#

• Geometrii exportují jen druhy v tabulce níže. Druhy, jejichž geometrie je vztažena k Měsíci, Marsu nebo jinému tělesu, se neexportují: CZML, KML a GeoJSON popisují polohy kolem Země a toto vydání zapisuje soubory STK jen s CentralBody Earth, ačkoli samotný formát STK jiná centrální tělesa připouští.
• constellation-design, earth-gnss-lunar a oem-interop mají geometrii vztaženou k Zemi, kterou toto vydání neexportuje; tabulka uvádí důvod pro každý.
• Druh gnss-ins letí svou trajektorii v rovinné místní tečné rovině, takže se exportuje jen počátek roviny, nikoli trajektorie.
• Polohy družic vztažené k Zemi zanedbávají UT1−UTC a polární pohyb (viz Soustavy a čas); výšky KML jsou elipsoidické, ne nad střední hladinou moře.
• Stopy rušičky předpokládají šíření ve volném prostoru, rušičku na horizontu přijímače a kulovou Zemi pro kružnici.

Každý soubor scénáře#

Co dělá kshana <scenario> --export <format> pro každý soubor v scenarios/ (manifest sady není scénář a je vynechán). „ano“ znamená, že formát se zapíše a projde svým validátorem; jinak číslo odkazuje na důvod. Generuje cargo run --bin gen_validation_artifacts; tests/interop_formats.rs selže, když je zastaralá.

Proč se formát neuplatňuje:

1. druhy contact-schedule a acm-link plánují kontakty downlinku a kódování; pro geometrii exportujte scénář passes pro stejnou družici a stanici
2. SigMF obsahuje komplexní vzorky v základním pásmu, které syntetizuje jen druh spectrum
3. druh aocs simuluje orientaci kolem těžiště bez dráhy či pozemní polohy, takže není co umístit na Zemi
4. vstup scénáře nenese žádnou horizontální polohu (žádnou zeměpisnou šířku a délku, žádné geocentrické souřadnice, žádné dráhové prvky kromě nejvýše výšky), takže není co umístit na Zemi
5. druhy eo-radiometry a ascent-losses počítají bilance bez polohy na Zemi
6. efemerida STK popisuje polohu a rychlost vozidla v čase; tato scéna má jen pevné body nebo netimované stopy (pevný bod je STK Facility, nikoli efemerida)
7. žádný členský scénář kampaně nemá nic, co tento formát popisuje; exportujte člena samostatně, abyste viděli jeho důvod
8. druh leo-signal analyzuje návrhy signálů (spektra, sledování, akvizici, kompatibilitu) bez polohy družice či uživatele; exportujte scénář leo-pass nebo leo-pnt-chain, který návrh letí
9. v tomto vydání se neexportuje: fúzní polohové druhy umísťují své družice do soustavy vztažené k Zemi vzhledem k epoše, kterou nikdy nejmenují, takže by časově označený export musel kalendářní datum vymyslet (exportujte místo toho scénář leo-pass nebo leo-pnt-chain)
10. geometrie druhu je vztažena k Měsíci, Marsu nebo jinému tělesu Sluneční soustavy; CZML, KML a GeoJSON popisují polohy na Zemi nebo kolem ní a toto vydání zapisuje efemeridy STK jen s CentralBody Earth
11. v tomto vydání se neexportuje: constellation-design umísťuje své družice do soustavy vztažené k tělesu vzhledem k epoše, kterou nikdy nejmenuje, takže by časově označený export musel kalendářní datum vymyslet
12. v tomto vydání se neexportuje: konstelaci globálního družicového navigačního systému (GNSS) Země z earth-gnss-lunar vidí přijímač ve vzdálenosti Měsíce, jehož trajektorii druh nezpřístupňuje jako časovou řadu
13. v tomto vydání se neexportuje: druh entry-heating hlásí špičková zatížení a ohřev a neuchovává žádnou pozemní stopu s časovými značkami
14. druh gnss-ssv prochází dostupnost a sílu spoje pro uživatele na skořepině nebo keplerovské trajektorii; nemá jedinou polohu, kterou lze umístit na mapu
15. scénář launch-window uvádí zeměpisnou šířku místa startu, ale ne délku, takže místo nelze umístit
16. v tomto vydání se neexportuje: pravá dráha leo-navmsg je referenční dráha pro fitování, jejíž úhel rotace Země v epoše je vstup (theta0_deg, výchozí 0), nikoli odvozený z kalendářního data, takže její polohy vztažené k Zemi nejsou vázány na datum
17. tento scénář spectrum nemá blok [iq], takže se nesyntetizují žádné vzorky k nahrání
18. v tomto vydání se neexportuje: oem-interop čte a zapisuje Orbit Ephemeris Message CCSDS (Consultative Committee for Space Data Systems), což je samo o sobě výměnný soubor efemerid
19. druh optical-atmosphere počítá statistiky spoje pro pozemní stanoviště bez geometrie s časovými značkami, kterou by bylo možno umístit
20. scénář prochází jiný scénář přes mřížku; exportujte procházený scénář samostatně
21. druh time-transfer-budget počítá bilanci spoje a stability bez geometrie s časovými značkami, kterou by bylo možno umístit