Interoperabilitetseksport og -import

En kørsel skriver et resultatdokument, et diagram og en rapport. --export skriver også scenariets geometri eller dets syntetiserede signal i de formater, som andre værktøjer allerede læser: en globeviser, et skrivebordskort, et geografisk informationssystem (GIS), en pakke til missionsanalyse eller et værktøj til softwaredefineret radio (SDR). Intet her læser et ur eller netværket, og ingen eksport bærer et genereringstidsstempel, så det samme scenarie giver byte-identiske filer ved hver kørsel.

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

Filerne skrives ved siden af scenariet og navngives som resultatdokumentet: jamming-demo.czml, jamming-demo.kml, jamming-demo.geojson, én jamming-demo.<object>.e pr. bevægeligt objekt (eller jamming-demo.e, når der er ét) og parret l-band-waterfall-jamming.sigmf-meta / .sigmf-data. Med --study-name får de undersøgelsens navn i stedet, som de andre output.

Et format, der er navngivet eksplicit og ikke gælder for scenariet, er en fejl, der udskriver begrundelsen; under all udskrives begrundelsen, og formatet springes over. Bibliotekets indgangspunkter er kshana::interop::export(src, format), kshana::interop::plan(src) og kshana::interop::geojson::apply_route(src, geojson); de tager scenarieteksten og returnerer bytes, uden at røre nogen fil, så de også kører i WebAssembly-builden. Serveren for Model Context Protocol (MCP) udstiller de samme tre som værktøjerne export_interop, list_export_formats og import_route (se mcp/kshana-mcp/README.md).

Kode: src/interop/ (scene.rs bygger én geometrisk beskrivelse af scenariet, czml.rs, kml.rs, geojson.rs og stk.rs skriver den), src/sigmf.rs og src/spectrum.rs til signalet. Tests: tests/interop_formats.rs.

Formater#

Hvad hver fil indeholder#

Hvert geospatialt format skrives ud fra den samme scene, så de ikke kan være uenige om, hvor noget er. En scene har op til fire slags objekter:

• Bevægelige objekter — satellitter og en brugerplatform, når den bevæger sig — samplet på scenariets eget tidsgitter med de propagatorer, som typens kørsel bruger.
• Faste steder — en modtager, en jordstation, en jammer eller oprindelsen af et lokalt navigationssystem.
• Spor uden tid — de waypoints, som en alternativ type til positionering, navigation og tidssynkronisering (PNT) baseret på terræn, tyngdekraft eller en kombination flyver. Disse typer har ingen tidsakse, så sporene bærer ingen.
• Jammerens fodaftryk — for typen jamming to cirkler om jammeren: den jordafstand, inden for hvilken en satellit i zenit (den stærkeste) falder under sporingstærsklen, så alle satellitter går tabt, og den afstand, inden for hvilken en satellit ved elevationsmasken (den svageste) gør det, så sporingen begynder at svigte. Begge kommer fra typens egne linkligninger (Kaplan og Hegarty, Understanding GPS/GNSS (Global Positioning System / Global Navigation Satellite Systems), 3. udg., §9,4) med jammeren ved modtagerens horisont og tab i frit rum, og testsuiten kontrollerer, at det effektive forhold mellem bærebølge og støjtæthed ved hver radius er lig med tærsklen med 1e-6 dB. Cirklen tegnes på en kugle med jordens middelradius.

CZML#

Den første pakke er dokumentpakken ("id": "document", "version": "1.0") med et ur, der spænder over tidsgitteret. Hvert bevægeligt objekt er en pakke, hvis position har en ISO 8601 (International Organization for Standardization-format for dato og tid) UTC (Coordinated Universal Time) epoch, referenceFrame "INERTIAL" og cartesian samples [t, x, y, z, ...]: sekunder efter epoken, meter i Geocentric Celestial Reference System (GCRS). CesiumJS tager INERTIAL som International Celestial Reference Frame (ICRF), hvis akser GCRS deler. Faste steder og fodaftrykkenes centre er konstante jordfaste cartesian positioner med referenceFrame "FIXED". Et fodaftryk er en ellipse med begge halvakser lig med dets radius; et spor uden tid er en jordfastholdt polyline. Hver pakkes description angiver referencesystemet igen i ord.

KML#

Ét <Document> med en <Folder> pr. objektklasse. Et bevægeligt objekt er en <Placemark>, der rummer en <gx:Track>: én <when> pr. sample (ISO 8601 UTC), derefter én <gx:coord> pr. sample (længde, bredde, højde). Steder er <Point>, fodaftryk <Polygon>, hvis ring er lukket og mod uret, spor uden tid <LineString>. Koordinater er World Geodetic System 1984 (WGS 84) længde og bredde i decimalgrader og højde i meter over WGS 84-ellipsoiden, skrevet med altitudeMode absolute. KML læser absolute som højde over middelvandstand; forskellen, geoidens undulation, er inden for ca. ±110 m og anvendes ikke. Dokumentets beskrivelse siger det.

GeoJSON#

Ét FeatureCollection. Positioner er [longitude, latitude] eller [longitude, latitude, height] — længde først, som RFC 7946 kræver — i WGS 84-grader, med højde i meter over ellipsoiden. Et bevægeligt objekt er en LineString med en egenskab times_utc, der rummer ét ISO 8601-tidspunkt pr. position; et spor, der krydser meridianen 180°, skrives som en MultiLineString, delt dér, som RFC 7946 §3.1.9 kræver (krydsningspunktet interpoleres, og times_utc viser så kun de oprindelige samples). Steder er Point, fodaftryk Polygon med en lukket ydre ring mod uret (§3.1.6), spor uden tid LineString. Hvert feature har en egenskab units, der angiver enheden for hvert numerisk medlem.

STK .e#

Én fil pr. bevægeligt objekt, da en STK-efemeride beskriver ét køretøj. Headeren angiver NumberOfEphemerisPoints (lig med antallet af datarækker), ScenarioEpoch (UTC, d Mon yyyy hh:mm:ss.ssssss), InterpolationMethod Lagrange med InterpolationSamplesM1 5, CentralBody Earth, CoordinateSystem ICRF og DistanceUnit Meters; rækkerne under EphemerisTimePosVel er sekunder efter epoken, position i meter og hastighed i meter pr. sekund, i GCRS. En scene med kun faste steder eller spor uden tid skriver ingen fil .e: et fast punkt er en STK Facility, ikke en efemeride. Et id, der ikke er en almindelig del af et filnavn (en konstellationsskal og en satellit, Pulsar inclined/S1-0163), skrives med alle andre tegn som -, nummereret, hvis to id'er så falder sammen.

Typen leo-pass og typen leo-pnt-chain (gennem dens trin [pass]) eksporterer hver satellit i lav jordbane (LEO) og brugeren ud fra typens egne propagatorer og tidsgitter. Typen arbejder i ECI0, det jordcentrerede inertialsystem, der ved epoken er på linje med det jordfaste system; hver sample omsættes til det jordfaste system på sit eget tidspunkt med typens jordrotation og derfra til GCRS gennem systemet true equator, mean equinox (TEME), som propagatoren Simplified General Perturbations 4 (SGP4) leverer sit output i, på det tidspunkt, med UT1 (Universal Time, jordens rotationsvinkel) sat lig med UTC og polbevægelse forsømt, som for de andre eksporter. De andre LEO-typer angiver, hvorfor et format ikke gælder (tabellen nedenfor).

Kampagner#

En campaign eksporterer hvert medlemsscenarie, der har geometri, som sit eget filsæt, med medlemmets etiket indsat før formatsuffikset: hver fasekørsel (<phase>, eller <phase>-<k>, når fasen har flere kørsler), sweepets basisscenarie (sweep), Monte Carlo-scenariet (monte-carlo) og hvert sammensat medlem (dets etiket, med de delte værdier, det binder, skrevet ind). campaign-shared-jammer-sea-road.toml --export kml skriver campaign-shared-jammer-sea-road.ship-strait.kml og campaign-shared-jammer-sea-road.car-coast-road.kml. Et medlem, der er identisk med et tidligere, skrives én gang, og værdier, som en kampagne anvender under kørslen (overdragelser, sweepværdier, seeds), er ikke i det eksporterede medlem. Et format gælder for en kampagne, når det gælder for et medlem; ellers er begrundelsen note 4 i tabellen nedenfor. Se CAMPAIGNS.md.

SigMF#

Typen spectrum og dens snapshot [iq] — det modellerede L-bånd tegnet som komplekse samples på ét tidspunkt — som et par .sigmf-meta / .sigmf-data, i den datatype, [iq] angiver (cf32_le eller ci16_le). Det er den samme optagelse, som kørslen skriver og læser tilbage til sin egen konsistenskontrol: de eksporterede metadata er lig med blokken iq.sigmf.meta i resultatdokumentet, og datafilen har længden iq.sigmf.data_bytes. Skribenten er src/sigmf.rs, modulet som typen spectrum allerede brugte; intet er duplikeret.

Referencesystemer og tid#

• Motoren propagerer i TEME (true equator, mean equinox of date), sit oprindelige system. Bevægelige objekter drejes til GCRS med reduktionen nutation::teme_to_gcrs (IAU 2006-præcession og IAU 2000B-nutation, hvor IAU er Den Internationale Astronomiske Union), som gengiver Vallados publicerede eksempel på TEME til GCRF (Geocentric Celestial Reference Frame) med 0,11 m, for CZML og STK, og til det jordfaste system med frames::teme_to_ecef for KML og GeoJSON. Den jordfaste rotation er Greenwichs gennemsnitlige siderale vinkel med UT1 sat lig med UTC og uden polbevægelse — den samme reduktion, som eksporten til SP3 (Standard Product 3) bruger. Ved en GPS-banes radius flytter den forsømte UT1−UTC på op til 0,9 s en satellits længde med op til ca. 1,7 km; jordstationer påvirkes ikke, da de er givet i bredde og længde.
• Typen ephemeris er undtagelsen: dens motoroutput bærer allerede GCRS- og jordfaste positioner (med scenariets UT1−UTC og polbevægelse eller en rigtig serie fra International Earth Rotation and Reference Systems Service (IERS)), og de skrives uændret.
• Alle tider er UTC. Skudsekunder er ikke modelleret: en forskydning henover et skudsekund tælles, som om hver dag havde 86.400 s, som motorens tidsgitre tæller.
• Epoken for t = 0 er den, som typens kørsel bruger, og hver fil navngiver den: typens orbit epoch; når den mangler, den tidligste epoke, satellitternes egne data bærer (en epoke for et two-line element set (TLE), et udsendt efemerides referencetid, starten på en SP3-fil), og 2000-01-01T00:00:00Z kun når ingen satellit bærer en (Kepler-elementer). Eksporterne til SP3 og OEM (Orbit Ephemeris Message) beholder 2000-01-01T00:00:00Z for et scenarie uden epoch, så for et sådant scenarie afviger deres datoer fra disse filers. Uden scenarie-epoch drejes hver satellit, der bærer sin egen epoke, ind i GCRS og de jordfaste systemer på sit eget tidspunkt (dens epoke plus t), da det er den dato, dens TEME-position hører til; hvor satellitternes epoker er forskellige, følger de fælles tidsmærker motorens forudsætning om, at hver satellit starter ved t = 0, og filen angiver, med hvor mange timer de afviger. SGP4-elementepoken for Walker-konstellationerne i typerne jamming og gnss-sim (2018-06-12T00:00:00Z), som deres kørsler også bruger til jordrotationen; typens passes epoch; typens ephemeris epoch eller TLE-epoke. Typen integrity har ingen kalenderepoke; dens eksport dateres t = 0 som for et banescenarie uden en.
• Satellitter beholder de positionelle identifikatorer G01, G02, ... som eksporterne til SP3 og OEM giver dem, fordi propagatorerne ikke bærer TLE'ens navnelinjer.

Importer#

• GeoJSON-rute. --import-route <file> (bibliotek: interop::geojson::apply_route) læser den første LineString i et GeoJSON-dokument — en ren geometri, et Feature eller en FeatureCollection — og skriver den ind i sporinputtene for terrain-nav, terrain-slam, gravity-map og combined-altpnt (start_lat_deg, start_lon_deg, step_lat_deg, step_lon_deg, waypoints) før kørslen. Disse typer flyver start + i·step, så en rute accepteres, når den er netop det: dens to ender (scenariets antal waypoints bevares) eller tre eller flere positioner jævnt fordelt på en ret linje i bredde og længde, inden for 1e-7 grad (ca. 1 cm). Enhver anden rute afvises, og fejlen nævner den position, der ligger længst fra linjen. En rute til en type uden trajektorieinput afvises med den begrundelse. Længde og bredde områdetjekkes, hvilket fanger en fil med bredde først.
• SigMF-optagelse. Blokken [recording] i typen spectrum læser et par .sigmf-meta / .sigmf-data gennem src/sigmf.rs og plotter dets Welch-estimat ved siden af modellen (se SPECTRUM.md). At læse filer er en funktion i den native build; WebAssembly-builden tager bytes gennem kshana::sigmf::read.

Hvordan eksporterne kontrolleres#

tests/interop_formats.rs fortolker hver eksport med en validator, der er skrevet ud fra formatets specifikation, ikke med skribentens egen kode:

• CZML: en JSON-array, hvis første pakke er dokumentpakken med en version; entydige pakkeidentifikatorer; hver position angiver referenceFrame FIXED eller INERTIAL; samplede positioner er [t, x, y, z, ...] med en ISO 8601-epoke og voksende tider.
• KML: et velformet XML-dokument (Extensible Markup Language) i OGC's navneområde for KML 2,2 med ét rodfeature; skemaets rækkefølge af elementer inden for en Placemark; højst én geometri pr. Placemark; lukkede lineære ringe på fire eller flere positioner; lon,lat[,alt]-tupler inden for området; gyldige værdier af altitudeMode; styleUrl, der kan opløses; en gx:Track med lige så mange <when> som <gx:coord> og det deklarerede navneområde for udvidelsen.
• GeoJSON: længde først og inden for området, bredde inden for området, to eller tre tal pr. position, linjestrenge på to eller flere positioner, lukkede ydre ringe mod uret, intet segment henover meridianen 180°, intet medlem crs, en egenskab units på hvert feature.
• STK: versionslinjen stk.v., en blok BEGIN Ephemeris / END Ephemeris med de krævede nøgleord, DistanceUnit Meters, NumberOfEphemerisPoints lig med antallet af datarækker, syv tal pr. række, voksende tider.
• SigMF: core:datatype og core:version i global, arrays captures og annotations, core:sample_start på hver capture og en datafil med hele samples.

Ud over strukturen sammenlignes en satellit eksporteret til CZML og til STK med motorens egen tilstand efter den samme referencesystemreduktion og stemmer med 1 mm i position (filerne bærer 0,1 mm): mod typens egen GCRS-output ephemeris og mod en uafhængig TEME-til-GCRS-propagering af konstellationen orbit-sgp4-gps, hver satellit dateret med sin egen TLE-epoke læst fra scenarieteksten. To kontroller går uden for motoren: den første orbit-sgp4-gps-satellits CZML-positioner stemmer med 0,1 m (målt 2,3 cm) med den samme TLE propageret af Python-pakken sgp4 og reduceret til GCRS af ERFA (Essential Routines for Fundamental Astronomy, den åbne implementering af IAU's SOFA-bibliotek), og de jordfaste positioner for satellitterne orbit-rinex er lig med de udsendte efemeridepositioner i grænsefladespecifikationen for Global Positioning System med 1 mm. De jordfaste positioner i eksporten jamming sammenlignes med de positioner, som jamming-kørslen bedømmer, med 5 mm. GeoJSON-ruten går rundt gennem et sporscenarie, SigMF-parret læses tilbage til de samme bytes, og hver eksport er byte-deterministisk.

Dette er kontroller mod de publicerede specifikationer og mod selve motoren. Filerne er ikke indlæst i CesiumJS, Google Earth, Ansys STK eller et SDR-værktøj som en del af testsuiten, så accept i en bestemt version af de værktøjer er ikke afprøvet her.

Udveksling af bane, attitude og kernel (bibliotek, 0,36)#

Ved siden af formaterne --export tilføjede 0,36 bibliotekslæsere og -skribenter til de standardfiler, som værktøjer til missionsanalyse udveksler. De tager og returnerer tekst eller bytes og rører ingen fil. Hver er en VALIDATED række i verifikationsmatrixen, mod den uafhængige implementering, der er nævnt dér:

• CCSDS Orbit Data Messages (kshana::odm, med kshana::ndm_xml til XML-formen): OPM, OMM og OCM i notation med nøgleord og værdi (KVN) og NDM/XML, efter CCSDS 502.0-B-3 (OPM og OMM i version 3,0 og 2,0, OCM 3,0). Kontrolleret begge veje mod Orekit: Orekit læser Kshanas filer, og Kshana læser Orekits. De fund, der er tilbage, er fastlåst af tests.
• CCSDS Attitude Data Messages (kshana::adm, med kshana::ndm_xml): AEM og APM efter CCSDS 504.0-B-2, i KVN og NDM/XML. Kontrolleret mod Orekit på samme måde, og postrotationerne mod Orekits.
• SPICE SPK (kshana::spk_writer): skribenter og læsere af NAIF SPK-segmenter af typerne 9 og 13 (med eksport af en CCSDS OEM til en SPK-kernel) og typerne 3 og 21 (Chebyshev-polynomier og udvidede differenslinjer), kontrolleret mod NAIF SPICE-værktøjskassens egne læsere, ned til byte-identitet. Kshana skriver segmenterne ud fra de poster, den får: den tilpasser ikke Chebyshev-koefficienter og frembringer ikke differenslinjer.

Importeren og skribenten til CCSDS OEM og kovariansblokken i OEM er ældre og beskrives under importerne ovenfor og i matrixen.

Begrænsninger#

• Kun de typer, der står i tabellen nedenfor, eksporterer geometri. Typer, hvis geometri er centreret om Månen, Mars eller et andet legeme, eksporteres ikke: CZML, KML og GeoJSON beskriver positioner om Jorden, og denne udgivelse skriver kun STK-filer med CentralBody Earth, selv om selve STK-formatet tillader andre centrallegemer.
• constellation-design, earth-gnss-lunar og oem-interop har geometri med jorden som reference, som denne udgivelse ikke eksporterer; tabellen giver begrundelsen for hver.
• Typen gnss-ins flyver sin trajektorie i et fladt lokalt tangentplan, så kun planets oprindelse eksporteres, ikke trajektorien.
• Jordfaste satellitpositioner forsømmer UT1−UTC og polbevægelse (se Referencesystemer og tid); KML-højder er ellipsoidiske, ikke over middelvandstand.
• Fodaftryk forudsætter udbredelse i frit rum, en jammer ved modtagerens horisont og en kugleformet jord for cirklen.

Hver scenariefil#

Hvad kshana <scenario> --export <format> gør for hver fil i scenarios/ (suitens manifest er ikke et scenarie og er udeladt). "yes" betyder, at formatet skrives og består sin validator; ellers peger tallet på begrundelsen. Genereret af cargo run --bin gen_validation_artifacts; tests/interop_formats.rs fejler, når den er forældet.

Hvorfor et format ikke gælder:

1. typerne contact-schedule og acm-link planlægger downlink-kontakter og kodning; eksportér et scenarie passes for den samme satellit og station for at se geometrien
2. SigMF rummer komplekse basisbåndssamples, som kun typen spectrum syntetiserer
3. typen aocs simulerer attitude om massemidtpunktet uden bane eller position på jorden, så der er intet at placere på Jorden
4. scenarieinputtet bærer ingen horisontal position (ingen bredde og længde, ingen jordcentrerede koordinater, ingen banekomponenter ud over højst en højde), så der er intet at placere på Jorden
5. typerne eo-radiometry og ascent-losses beregner budgetter uden position på Jorden
6. en STK-efemeride beskriver et køretøjs position og hastighed over tid; denne scene har kun faste punkter eller spor uden tid (et fast punkt er en STK Facility, ikke en efemeride)
7. intet medlemsscenarie i kampagnen har noget, som dette format beskriver; eksportér et medlem for sig for at se dets begrundelse
8. typen leo-signal analyserer signaludformninger (spektre, sporing, erhvervelse, kompatibilitet) uden satellit- eller brugerposition; eksportér scenariet leo-pass eller leo-pnt-chain, der flyver udformningen
9. ikke eksporteret i denne udgivelse: de sammensmeltede positioneringstyper placerer deres satellitter i et jordfast system i forhold til en epoke, de aldrig nævner, så en tidsmærket eksport ville skulle opfinde kalenderdatoen (eksportér i stedet scenariet leo-pass eller leo-pnt-chain)
10. typens geometri er centreret om Månen, Mars eller et andet legeme i solsystemet; CZML, KML og GeoJSON beskriver positioner på eller om Jorden, og denne udgivelse skriver kun STK-efemerider med CentralBody Earth
11. ikke eksporteret i denne udgivelse: constellation-design placerer sine satellitter i et legemefast system i forhold til en epoke, den aldrig nævner, så en tidsmærket eksport ville skulle opfinde kalenderdatoen
12. ikke eksporteret i denne udgivelse: jordens konstellation af Global Navigation Satellite System (GNSS) i earth-gnss-lunar ses fra en modtager i månens afstand, hvis trajektorie typen ikke udstiller som en tidsserie
13. ikke eksporteret i denne udgivelse: typen entry-heating rapporterer spidsbelastninger og opvarmning og beholder intet tidsmærket sporet på jorden
14. typen gnss-ssv sweeper tilgængelighed og linkstyrke for en bruger på en skal eller en Kepler-trajektorie; den har ingen enkelt position at placere på et kort
15. scenariet launch-window angiver opsendelsesstedets breddegrad, men ingen længdegrad, så stedet kan ikke placeres
16. ikke eksporteret i denne udgivelse: sandhedsbanen i leo-navmsg er en tilpasningsreference, hvis jordrotationsvinkel ved epoken er et input (theta0_deg, standard 0) og ikke udledt af kalenderdatoen, så dens jordfaste positioner er ikke knyttet til en dato
17. dette spektrumscenarie har ingen blok [iq], så der syntetiseres ingen samples til optagelse
18. ikke eksporteret i denne udgivelse: oem-interop læser og skriver en Orbit Ephemeris Message fra CCSDS (Consultative Committee for Space Data Systems), som selv er udvekslingsfilen for efemerider
19. typen optical-atmosphere beregner linkstatistik for jordsteder uden tidsmærket geometri at placere
20. scenariet sweeper et andet scenarie over et gitter; eksportér det sweepede scenarie for sig
21. typen time-transfer-budget beregner et linkbudget og stabiliteter uden tidsmærket geometri at placere