Interoperabilitetseksporter og -importer

En kjøring skriver et resultatdokument, et diagram og en rapport. --export skriver i tillegg scenarioets geometri, eller det syntetiserte signalet, i formater som andre verktøy allerede leser: en globusvisning, et skrivebordskart, et geografisk informasjonssystem (GIS), en pakke for oppdragsanalyse eller et verktøy for programvaredefinert radio (SDR). Ingenting her leser en klokke eller nettverket, og ingen eksport har et tidsstempel for opprettelse, så det samme scenarioet gir byte-identiske filer ved hver kjøring.

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

Filene skrives ved siden av scenarioet, med navn som resultatdokumentet: jamming-demo.czml, jamming-demo.kml, jamming-demo.geojson, én jamming-demo.<object>.e per bevegelig objekt (eller jamming-demo.e når det bare er ett), og paret l-band-waterfall-jamming.sigmf-meta / .sigmf-data. Med --study-name får de navnet på studien i stedet, slik de andre utdataene gjør.

Et format som er navngitt eksplisitt og ikke gjelder for scenarioet, er en feil som skriver ut årsaken; under all skrives årsaken ut og formatet hoppes over. Inngangspunktene i biblioteket er kshana::interop::export(src, format), kshana::interop::plan(src) og kshana::interop::geojson::apply_route(src, geojson); de tar scenarioteksten og returnerer bytes, uten å røre noen fil, så de kjører også i WebAssembly-bygget. Model Context Protocol-serveren (MCP) tilbyr de samme tre som verktøyene export_interop, list_export_formats og import_route (se mcp/kshana-mcp/README.md).

Kode: src/interop/ (scene.rs bygger én geometrisk beskrivelse av scenarioet, czml.rs, kml.rs, geojson.rs og stk.rs skriver den), src/sigmf.rs og src/spectrum.rs for signalet. Tester: tests/interop_formats.rs.

Formater#

Hva hver fil inneholder#

Alle geospatiale formater skrives fra den samme scenen, så de kan ikke være uenige om hvor noe er. En scene har opptil fire typer objekter:

• Bevegelige objekter: satellitter, og en brukerplattform når den beveger seg, samplet på scenarioets eget tidsrutenett med propagatorene som kjøringen for typen bruker.
• Faste steder: en mottaker, en bakkestasjon, en jammer eller opprinnelsen til et lokalt navigasjonsreferansesystem.
• Tidsløse spor: veipunktene en alternativ PNT-type (posisjonering, navigasjon og tidssynkronisering) for terreng, tyngdekraft eller kombinasjon flyr. Disse typene har ingen tidsakse, så sporene har ingen tid.
• Jammer-fotavtrykk: for typen jamming to sirkler rundt jammeren: bakkeavstanden innenfor hvilken en satellitt i senit (den sterkeste) faller under sporingsterskelen, slik at alle satellitter går tapt, og avstanden innenfor hvilken en satellitt ved høydemasken (den svakeste) gjør det, slik at sporingen begynner å svikte. Begge kommer fra typens egne linkligninger (Kaplan og Hegarty, Understanding GPS/GNSS (Global Positioning System / Global Navigation Satellite Systems), 3. utg., §9,4) med jammeren ved mottakerens horisont og frirom-tap, og testsuiten kontrollerer at det effektive forholdet mellom bærebølge og støytetthet ved hver radius er lik terskelen innenfor 1e-6 dB. Sirkelen tegnes på en kule med jordens middelradius.

CZML#

Den første pakken er dokumentpakken ("id": "document", "version": "1.0") med en klokke som spenner over tidsrutenettet. Hvert bevegelig objekt er en pakke der position har en ISO 8601 (International Organization for Standardization-format for dato og tid) UTC-epoch (Coordinated Universal Time), referenceFrame "INERTIAL", og cartesian-sampler [t, x, y, z, ...]: sekunder etter epoken, meter i Geocentric Celestial Reference System (GCRS). CesiumJS tar INERTIAL som International Celestial Reference Frame (ICRF), hvis akser GCRS deler. Faste steder og sentre for fotavtrykk er konstante jordfaste cartesian-posisjoner med referenceFrame "FIXED". Et fotavtrykk er en ellipse med begge halvaksene lik radiusen; et tidsløst spor en bakkeklemt polyline. Hver pakkes description sier rammen en gang til i ord.

KML#

Ett <Document> med en <Folder> per objektklasse. Et bevegelig objekt er en <Placemark> som holder en <gx:Track>: én <when> per sampel (ISO 8601 UTC), deretter én <gx:coord> per sampel (lengdegrad, breddegrad, høyde). Steder er <Point>-er, fotavtrykk <Polygon>-er der ringen er lukket og mot klokken, tidsløse spor <LineString>-er. Koordinatene er World Geodetic System 1984 (WGS 84) lengdegrad og breddegrad i desimalgrader og høyde i meter over WGS 84-ellipsoiden, skrevet med altitudeMode absolute. KML leser absolute som høyde over middelhavsnivå; forskjellen, geoideundulasjonen, ligger innenfor omtrent ±110 m og påføres ikke. Dokumentets beskrivelse sier det.

GeoJSON#

Én FeatureCollection. Posisjonene er [longitude, latitude] eller [longitude, latitude, height], med lengdegrad først, slik RFC 7946 krever, i WGS 84-grader, med høyde i meter over ellipsoiden. Et bevegelig objekt er en LineString med en times_utc-egenskap som holder én ISO 8601-tid per posisjon; et spor som krysser 180°-meridianen skrives som en MultiLineString kuttet der, slik RFC 7946 §3.1.9 ber om (krysningspunktet interpoleres, og times_utc lister da bare de opprinnelige samplene). Steder er Point-er, fotavtrykk Polygon-er med en lukket ytre ring mot klokken (§3.1.6), tidsløse spor LineString-er. Hvert objekt har en units-egenskap som navngir enheten til hvert numeriske medlem.

STK .e#

Én fil per bevegelig objekt, siden en STK-efemeride beskriver ett kjøretøy. Hodet gir NumberOfEphemerisPoints (lik antallet datarader), ScenarioEpoch (UTC, d Mon yyyy hh:mm:ss.ssssss), InterpolationMethod Lagrange med InterpolationSamplesM1 5, CentralBody Earth, CoordinateSystem ICRF og DistanceUnit Meters; radene under EphemerisTimePosVel er sekunder etter epoken, posisjon i meter og hastighet i meter per sekund, i GCRS. En scene med bare faste steder eller tidsløse spor skriver ingen .e-fil: et fast punkt er en STK Facility, ikke en efemeride. En id som ikke er en vanlig del av et filnavn (et konstellasjonsskall og en satellitt, Pulsar inclined/S1-0163) skrives med hvert annet tegn som -, nummerert hvis to id-er da faller sammen.

Typen leo-pass og typen leo-pnt-chain (gjennom trinnet [pass]) eksporterer hver satellitt i lav jordbane (LEO) og brukeren fra typens egne propagatorer og tidsrutenett. Typen arbeider i ECI0, det jordsentrerte treghetssystemet som er innrettet etter det jordfaste systemet ved epoken; hvert sampel dreies over i det jordfaste systemet på sitt eget tidspunkt med typens jordrotasjon og derfra inn i GCRS gjennom TEME-systemet (true equator, mean equinox) som propagatoren Simplified General Perturbations 4 (SGP4) gir utdata i, i det øyeblikket, med UT1 (Universal Time, jordrotasjonsvinkelen) satt lik UTC og polbevegelse sett bort fra, som for de andre eksportene. De andre LEO-typene sier hvorfor et format ikke gjelder (tabellen nedenfor).

Kampanjer#

En campaign eksporterer hvert medlemsscenario som har geometri som sitt eget filsett, med medlemmets etikett satt inn før formatsuffikset: hver fasekjøring (<phase>, eller <phase>-<k> når fasen har flere kjøringer), sweepens basisscenario (sweep), Monte Carlo-scenarioet (monte-carlo) og hvert sammensatt medlem (dets etikett, med de delte verdiene det binder skrevet inn). 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 som er likt et tidligere skrives én gang, og verdier en campaign bruker under kjøring (overleveringer, sweep-verdier, seeds) er ikke i det eksporterte medlemmet. Et format gjelder for en campaign når det gjelder for et medlem; ellers står årsaken i note 4 i tabellen nedenfor. Se CAMPAIGNS.md.

SigMF#

Øyeblikksbildet [iq] fra typen spectrum, det modellerte L-båndet tegnet som komplekse sampler i ett tidspunkt, som et .sigmf-meta / .sigmf-data-par, i datatypen [iq] navngir (cf32_le eller ci16_le). Det er den samme opptaken som kjøringen skriver og leser tilbake for sin egen konsistenskontroll: de eksporterte metadataene er lik blokken iq.sigmf.meta i resultatdokumentet, og datafilen har lengden iq.sigmf.data_bytes. Skriveren er src/sigmf.rs, modulen typen spectrum allerede brukte; ingenting dupliseres.

Referansesystemer og tid#

• Motoren propagerer i TEME (true equator, mean equinox of date), sitt eget system. Bevegelige objekter dreies til GCRS med reduksjonen nutation::teme_to_gcrs (IAU 2006-presesjon og IAU 2000B-nutasjon, der IAU er International Astronomical Union), som gjengir Vallados publiserte TEME-til-GCRF-eksempel (Geocentric Celestial Reference Frame) innenfor 0,11 m, for CZML og STK, og til det jordfaste systemet med frames::teme_to_ecef for KML og GeoJSON. Den jordfaste rotasjonen er Greenwich-middelsideralvinkelen med UT1 satt lik UTC og polbevegelse ikke påført, den samme reduksjonen som SP3-eksporten (Standard Product 3) bruker. Ved en GPS-banes radius flytter den utelatte UT1−UTC på opptil 0,9 s lengdegraden til en satellitt med opptil omtrent 1,7 km; bakkesteder påvirkes ikke, siden de oppgis i breddegrad og lengdegrad.
• Typen ephemeris er unntaket: dens utdata fra motoren har allerede GCRS- og jordfaste posisjoner (med scenarioets UT1−UTC og polbevegelse, eller en ekte serie fra International Earth Rotation and Reference Systems Service (IERS)), og de skrives uendret.
• All tid er UTC. Skuddsekunder er ikke modellert: en forskyvning over et skuddsekund telles som om hver dag hadde 86 400 s, slik motorens tidsrutenett teller.
• Epoken for t = 0 er den typens kjøring bruker, og hver fil navngir den: epoch for typen orbit; når den mangler, den tidligste epoken satellittenes egne data har (en TLE-epoke (two-line element set), referansetiden til en kringkastet efemeride, starten på en SP3-fil), og 2000-01-01T00:00:00Z bare når ingen satellitt har en (keplerske elementer). SP3- og OEM-eksportene (Orbit Ephemeris Message) beholder 2000-01-01T00:00:00Z for et scenario uten epoch, så for et slikt scenario avviker datoene deres fra disse filenes. Uten scenarioets epoch dreies hver satellitt som har sin egen epoke inn i GCRS og de jordfaste systemene i sitt eget øyeblikk (epoken pluss t), siden det er datoen TEME-posisjonen hører til; der satellittenes epoker er ulike, følger de delte tidsmerkene motorens forutsetning om at hver satellitt starter ved t = 0, og filen sier hvor mange timer de avviker. SGP4-elementepoken til Walker-konstellasjonene i typene jamming og gnss-sim (2018-06-12T00:00:00Z), som kjøringene deres også bruker for jordrotasjonen; epoch for typen passes; epoch eller TLE-epoken for typen ephemeris. Typen integrity har ingen kalenderepoke; eksporten datosetter t = 0 som for et banescenario uten en.
• Satellittene beholder de posisjonsbaserte identifikatorene G01, G02, ... som SP3- og OEM-eksportene gir dem, fordi propagatorene ikke bærer TLE-navnelinjene.

Importer#

• GeoJSON-rute. --import-route <file> (bibliotek: interop::geojson::apply_route) leser den første LineString i et GeoJSON-dokument (en bar geometri, en Feature eller en FeatureCollection) og skriver den inn i sporinndataene til terrain-nav, terrain-slam, gravity-map og combined-altpnt (start_lat_deg, start_lon_deg, step_lat_deg, step_lon_deg, waypoints) før kjøringen. Disse typene flyr start + i·step, så en rute godtas når den er nøyaktig det: de to endepunktene (scenarioets antall waypoints beholdes), eller tre eller flere posisjoner med jevn avstand på en rett linje i breddegrad og lengdegrad, innenfor 1e-7 grad (omtrent 1 cm). Enhver annen rute avvises, og feilen navngir posisjonen lengst fra linjen. En rute for en type uten sporinndata avvises med den begrunnelsen. Lengdegrad og breddegrad områdekontrolleres, noe som fanger en fil med breddegrad først.
• SigMF-opptak. Blokken [recording] i typen spectrum leser et .sigmf-meta / .sigmf-data-par gjennom src/sigmf.rs og plotter Welch-estimatet ved siden av modellen (se SPECTRUM.md). Å lese filer er en funksjon i det native bygget; WebAssembly-bygget tar bytes gjennom kshana::sigmf::read.

Hvordan eksportene kontrolleres#

tests/interop_formats.rs tolker hver eksport med en validator skrevet ut fra formatets spesifikasjon, ikke med skriverens egen kode:

• CZML: en JSON-tabell der den første pakken er dokumentpakken med en version; unike pakkeidentifikatorer; hver posisjon oppgir referenceFrame FIXED eller INERTIAL; samplede posisjoner er [t, x, y, z, ...] med en ISO 8601-epoke og økende tider.
• KML: et velformet XML-dokument (Extensible Markup Language) i OGC KML 2,2-navnerommet med ett rotobjekt; skjemaets elementrekkefølge inne i en Placemark; høyst én geometri per Placemark; lukkede lineære ringer på fire eller flere posisjoner; lon,lat[,alt]-tupler innenfor området; gyldige altitudeMode-verdier; styleUrl-er som kan løses opp; en gx:Track med like mange <when> som <gx:coord>, og utvidelsesnavnerommet deklarert.
• GeoJSON: lengdegrad først og innenfor området, breddegrad innenfor området, to eller tre tall per posisjon, linjestrenger på to eller flere posisjoner, lukkede ytre ringer mot klokken, ingen segment over 180°-meridianen, ingen crs-medlem, en units-egenskap på hvert objekt.
• STK: versjonslinjen stk.v., en blokk BEGIN Ephemeris / END Ephemeris med de påkrevde nøkkelordene, DistanceUnit Meters, NumberOfEphemerisPoints lik antallet datarader, sju tall per rad, økende tider.
• SigMF: core:datatype og core:version i global, tabellene captures og annotations, core:sample_start på hver opptaksbolk, og en datafil med hele sampler.

Utover strukturen sammenlignes en satellitt eksportert til CZML og til STK med motorens egen tilstand etter den samme rammereduksjonen, og stemmer til 1 mm i posisjon (filene har 0,1 mm): mot typen ephemeris sin egen GCRS-utdata, og mot en uavhengig TEME-til-GCRS-propagering av konstellasjonen orbit-sgp4-gps, der hver satellitt er datert med sin egen TLE-epoke lest fra scenarioteksten. To kontroller går utenfor motoren: CZML-posisjonene til den første satellitten i orbit-sgp4-gps stemmer til 0,1 m (målt 2,3 cm) med den samme TLE-en propagert av Python-pakken sgp4 og redusert til GCRS av ERFA (Essential Routines for Fundamental Astronomy, den åpne implementeringen av IAUs SOFA-bibliotek), og de jordfaste posisjonene til satellittene i orbit-rinex er lik de kringkastede efemeride-posisjonene i grensesnittspesifikasjonen for Global Positioning System til 1 mm. De jordfaste posisjonene i eksporten jamming sammenlignes med posisjonene jamming-kjøringen poengsetter, til 5 mm. GeoJSON-ruten går rundt gjennom et sporscenario, SigMF-paret leses tilbake til de samme bytene, og hver eksport er byte-deterministisk.

Dette er kontroller mot de publiserte spesifikasjonene og mot motoren selv. Filene er ikke lastet inn i CesiumJS, Google Earth, Ansys STK eller et SDR-verktøy som en del av testsuiten, så hvorvidt en bestemt versjon av disse verktøyene tar imot dem er ikke testet her.

Utveksling av bane, attityde og kjerner (bibliotek, 0,36)#

Ved siden av formatene for --export la 0,36 til bibliotekslesere og -skrivere for standardfilene som verktøy for oppdragsanalyse utveksler. De tar og returnerer tekst eller bytes og berører ingen fil. Hver er en VALIDATED-rad i verifikasjonsmatrisen, mot den uavhengige implementeringen som er navngitt der:

• CCSDS Orbit Data Messages (kshana::odm, med kshana::ndm_xml for XML-formen): OPM, OMM og OCM i nøkkelord-verdi-notasjon (KVN) og NDM/XML, etter CCSDS 502.0-B-3 (OPM og OMM versjon 3,0 og 2,0, OCM 3,0). Kontrollert begge veier mot Orekit: Orekit leser Kshanas filer, og Kshana leser Orekits. Funnene som gjenstår er festet av tester.
• CCSDS Attitude Data Messages (kshana::adm, med kshana::ndm_xml): AEM og APM etter CCSDS 504.0-B-2, i KVN og NDM/XML. Kontrollert mot Orekit på samme måte, og postrotasjonene mot Orekits.
• SPICE SPK (kshana::spk_writer): skrivere og lesere for NAIF SPK-segmenter av typene 9 og 13 (med eksport av en CCSDS OEM til en SPK-kjerne) og typene 3 og 21 (Chebyshev-polynomer og utvidede differanselinjer), kontrollert mot NAIF SPICE-verktøykassens egne lesere, ned til byte-identitet. Kshana skriver segmentene fra postene den får: den tilpasser ikke Chebyshev-koeffisienter og lager ikke differanselinjer.

Importøren og skriveren for CCSDS OEM, og OEM-kovariansblokken, er eldre og beskrives under importene ovenfor og i matrisen.

Begrensninger#

• Bare typene i tabellen nedenfor eksporterer geometri. Typer der geometrien er sentrert om Månen, Mars eller et annet legeme eksporteres ikke: CZML, KML og GeoJSON beskriver posisjoner om Jorden, og denne utgivelsen skriver bare STK-filer med CentralBody Earth, selv om selve STK-formatet tillater andre sentrallegemer.
• constellation-design, earth-gnss-lunar og oem-interop har jordreferert geometri som denne utgivelsen ikke eksporterer; tabellen gir årsaken for hver.
• Typen gnss-ins flyr banen sin i et flatt lokalt tangentplan, så bare planets opprinnelse eksporteres, ikke banen.
• Jordfaste satellittposisjoner ser bort fra UT1−UTC og polbevegelse (se Referansesystemer og tid); KML-høyder er ellipsoidiske, ikke over middelhavsnivå.
• Fotavtrykk forutsetter frirom-propagering, en jammer ved mottakerens horisont og en kuleformet Jord for sirkelen.

Hver scenariofil#

Hva kshana <scenario> --export <format> gjør for hver fil i scenarios/ (suitemanifestet er ikke et scenario og er utelatt). «yes» betyr at formatet skrives og består validatoren; ellers peker tallet på årsaken. Generert av cargo run --bin gen_validation_artifacts; tests/interop_formats.rs feiler når den er utdatert.

Hvorfor et format ikke gjelder:

1. typene contact-schedule og acm-link planlegger nedlinjekontakter og koding; eksporter et passes-scenario for den samme satellitten og stasjonen for å se geometrien
2. SigMF holder komplekse basebåndsampler, som bare typen spectrum syntetiserer
3. typen aocs simulerer attityde om massesenteret uten bane eller bakkeposisjon, så det er ingenting å plassere på Jorden
4. scenarioinndataene har ingen horisontal posisjon (ingen breddegrad og lengdegrad, ingen jordsentrerte koordinater, ingen baneelementer utover høyst en høyde), så det er ingenting å plassere på Jorden
5. typene eo-radiometry og ascent-losses beregner budsjetter uten jordposisjon
6. en STK-efemeride beskriver et kjøretøys posisjon og hastighet mot tid; denne scenen har bare faste punkter eller tidsløse spor (et fast punkt er en STK Facility, ikke en efemeride)
7. ingen av medlemsscenarioene i campaign-en har noe dette formatet beskriver; eksporter et medlem for seg for å se årsaken
8. typen leo-signal analyserer signalutforminger (spektre, sporing, innhenting, kompatibilitet) uten satellitt- eller brukerposisjon; eksporter scenarioet leo-pass eller leo-pnt-chain som flyr utformingen
9. ikke eksportert i denne utgivelsen: de fusjonerte posisjoneringstypene plasserer satellittene sine i et jordfast system i forhold til en epoke de aldri navngir, så en tidsmerket eksport måtte funnet på kalenderdatoen (eksporter scenarioet leo-pass eller leo-pnt-chain i stedet)
10. typens geometri er sentrert om Månen, Mars eller et annet legeme i solsystemet; CZML, KML og GeoJSON beskriver posisjoner på eller om Jorden, og denne utgivelsen skriver bare STK-efemerider med CentralBody Earth
11. ikke eksportert i denne utgivelsen: constellation-design plasserer satellittene sine i et legemefast system i forhold til en epoke den aldri navngir, så en tidsmerket eksport måtte funnet på kalenderdatoen
12. ikke eksportert i denne utgivelsen: konstellasjonen av jordens Global Navigation Satellite System (GNSS) i earth-gnss-lunar sees fra en mottaker på månens avstand, hvis bane typen ikke tilbyr som en tidsserie
13. ikke eksportert i denne utgivelsen: typen entry-heating rapporterer toppbelastninger og oppvarming, og beholder ikke noe tidsmerket sporet på jorden
14. typen gnss-ssv sveiper tilgjengelighet og linkstyrke for en bruker på et skall eller en keplersk bane; den har ingen enkeltposisjon å plassere på et kart
15. scenarioet launch-window oppgir oppskytingsstedets breddegrad, men ingen lengdegrad, så stedet kan ikke plasseres
16. ikke eksportert i denne utgivelsen: referansebanen i leo-navmsg er en tilpasningsreferanse der jordrotasjonsvinkelen ved epoken er en inndata (theta0_deg, standard 0), ikke utledet fra kalenderdatoen, så de jordfaste posisjonene er ikke knyttet til en dato
17. dette spektrumscenarioet har ingen [iq]-blokk, så ingen sampler syntetiseres for opptak
18. ikke eksportert i denne utgivelsen: oem-interop leser og skriver en Orbit Ephemeris Message fra CCSDS (Consultative Committee for Space Data Systems), som i seg selv er efemeridens utvekslingsfil
19. typen optical-atmosphere beregner linkstatistikk for bakkesteder uten tidsmerket geometri å plassere
20. scenarioet sveiper et annet scenario over et rutenett; eksporter det sveipede scenarioet for seg
21. typen time-transfer-budget beregner et linkbudsjett og stabiliteter, uten tidsmerket geometri å plassere