Exports et imports d'interopérabilité

Une exécution écrit un document de résultat, un graphique et un rapport. --export écrit aussi la géométrie du scénario, ou son signal synthétisé, dans les formats que d'autres outils lisent déjà : un visualiseur de globe, une carte de bureau, un système d'information géographique (SIG), un logiciel d'analyse de mission ou un outil de radio logicielle (SDR). Rien ici ne lit une horloge ni le réseau, et aucun export ne porte d'horodatage de génération, de sorte que le même scénario donne des fichiers identiques à l'octet près à chaque exécution.

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

Les fichiers sont écrits à côté du scénario, nommés comme le document de résultat : jamming-demo.czml, jamming-demo.kml, jamming-demo.geojson, un jamming-demo.<object>.e par objet mobile (ou jamming-demo.e lorsqu'il n'y en a qu'un), et la paire l-band-waterfall-jamming.sigmf-meta / .sigmf-data. Avec --study-name, ils prennent à la place le nom de l'étude, comme les autres sorties.

Un format nommé explicitement qui ne s'applique pas au scénario est une erreur qui affiche la raison ; avec all, la raison est affichée et le format ignoré. Les points d'entrée de la bibliothèque sont kshana::interop::export(src, format), kshana::interop::plan(src) et kshana::interop::geojson::apply_route(src, geojson) ; ils prennent le texte du scénario et renvoient des octets, sans toucher à aucun fichier, de sorte qu'ils s'exécutent aussi dans la version WebAssembly. Le serveur Model Context Protocol (MCP) sert les trois mêmes sous forme des outils export_interop, list_export_formats et import_route (voir mcp/kshana-mcp/README.md).

Code : src/interop/ (scene.rs construit une description géométrique unique du scénario, czml.rs, kml.rs, geojson.rs et stk.rs l'écrivent), src/sigmf.rs et src/spectrum.rs pour le signal. Tests : tests/interop_formats.rs.

Formats#

Ce que contient chaque fichier#

Chaque format géospatial est écrit à partir de la même scène, de sorte qu'ils ne peuvent pas être en désaccord sur la position de quoi que ce soit. Une scène comporte jusqu'à quatre sortes d'objets :

• Objets mobiles — les satellites, et une plateforme utilisateur lorsqu'elle se déplace — échantillonnés sur la grille temporelle propre au scénario avec les propagateurs qu'utilise l'exécution du type de scénario.
• Sites fixes — un récepteur, une station au sol, un brouilleur, ou l'origine d'un référentiel de navigation local.
• Traces sans horodatage — les points de passage que parcourt un type de scénario de positionnement, navigation et synchronisation temporelle (PNT) alternatif fondé sur le terrain, la gravité ou une combinaison. Ces types n'ont pas d'axe temporel, de sorte que les traces n'en portent aucun.
• Empreintes de brouilleur — pour le type de scénario jamming, deux cercles autour du brouilleur : la portée au sol à l'intérieur de laquelle un satellite au zénith (le plus fort) passe sous le seuil de poursuite, de sorte que tous les satellites sont perdus, et la portée à l'intérieur de laquelle un satellite au masque d'élévation (le plus faible) le fait, de sorte que la poursuite commence à défaillir. Les deux proviennent des équations de liaison propres au type de scénario (Kaplan et Hegarty, Understanding GPS/GNSS (Global Positioning System / Global Navigation Satellite Systems), 3e éd., §9,4) avec le brouilleur à l'horizon du récepteur et une perte en espace libre, et la suite de tests vérifie que le rapport effectif porteuse sur densité de bruit à chaque rayon est égal au seuil à 1e-6 dB près. Le cercle est tracé sur une sphère du rayon moyen de la Terre.

CZML#

Le premier paquet est le paquet de document ("id": "document", "version": "1.0") avec une horloge couvrant la grille temporelle. Chaque objet mobile est un paquet dont position a une epoch UTC (temps universel coordonné) au format ISO 8601 (format de date et d'heure de l'Organisation internationale de normalisation), referenceFrame "INERTIAL", et des échantillons cartesian [t, x, y, z, ...] : secondes après l'époque, mètres dans le Geocentric Celestial Reference System (GCRS). CesiumJS prend INERTIAL pour l'International Celestial Reference Frame (ICRF), dont le GCRS partage les axes. Les sites fixes et les centres d'empreinte sont des positions cartesian constantes liées à la Terre avec referenceFrame "FIXED". Une empreinte est une ellipse dont les deux demi-axes sont égaux à son rayon ; une trace sans horodatage est une polyline plaquée au sol. La description de chaque paquet énonce de nouveau le référentiel en toutes lettres.

KML#

Un <Document> avec un <Folder> par classe d'objets. Un objet mobile est un <Placemark> contenant un <gx:Track> : un <when> par échantillon (UTC au format ISO 8601), puis un <gx:coord> par échantillon (longitude, latitude, hauteur). Les sites sont des <Point>, les empreintes des <Polygon> dont l'anneau est fermé et orienté dans le sens antihoraire, les traces sans horodatage des <LineString>. Les coordonnées sont la longitude et la latitude du World Geodetic System 1984 (WGS 84) en degrés décimaux et la hauteur en mètres au-dessus de l'ellipsoïde WGS 84, écrites avec altitudeMode absolute. KML lit absolute comme une hauteur au-dessus du niveau moyen de la mer ; la différence, l'ondulation du géoïde, est d'au plus environ ±110 m et n'est pas appliquée. La description du document le dit.

GeoJSON#

Une FeatureCollection. Les positions sont [longitude, latitude] ou [longitude, latitude, height] — longitude d'abord, comme l'exige la RFC 7946 — en degrés WGS 84, avec la hauteur en mètres au-dessus de l'ellipsoïde. Un objet mobile est une LineString avec une propriété times_utc contenant un temps ISO 8601 par position ; une trace qui franchit le méridien 180° est écrite comme une MultiLineString coupée à cet endroit, comme le demande la RFC 7946 §3.1.9 (le point de franchissement est interpolé, et times_utc ne liste alors que les échantillons d'origine). Les sites sont des Point, les empreintes des Polygon avec un anneau extérieur fermé orienté dans le sens antihoraire (§3.1.6), les traces sans horodatage des LineString. Chaque entité a une propriété units nommant l'unité de chaque membre numérique.

STK .e#

Un fichier par objet mobile, puisqu'une éphéméride STK décrit un seul véhicule. L'en-tête donne NumberOfEphemerisPoints (égal au nombre de lignes de données), ScenarioEpoch (UTC, d Mon yyyy hh:mm:ss.ssssss), InterpolationMethod Lagrange avec InterpolationSamplesM1 5, CentralBody Earth, CoordinateSystem ICRF et DistanceUnit Meters ; les lignes sous EphemerisTimePosVel sont des secondes après l'époque, la position en mètres et la vitesse en mètres par seconde, dans le GCRS. Une scène ne comportant que des sites fixes ou des traces sans horodatage n'écrit aucun fichier .e : un point fixe est une Facility STK, et non une éphéméride. Un identifiant qui n'est pas un élément simple de nom de fichier (une couche de constellation et un satellite, Pulsar inclined/S1-0163) est écrit avec chaque autre caractère remplacé par -, numéroté si deux identifiants coïncident alors.

Le type de scénario leo-pass et le type de scénario leo-pnt-chain (par son étape [pass]) exportent chaque satellite en orbite terrestre basse (LEO) et l'utilisateur à partir des propagateurs et de la grille temporelle propres au type de scénario. Le type de scénario travaille dans l'ECI0, le référentiel inertiel géocentrique aligné sur le référentiel terrestre à l'époque ; chaque échantillon est converti dans le référentiel terrestre à son propre instant par la rotation terrestre du type de scénario, puis de là dans le GCRS en passant par le référentiel de l'équateur vrai et de l'équinoxe moyen (TEME) dans lequel le propagateur Simplified General Perturbations 4 (SGP4) fournit ses sorties, à cet instant, avec UT1 (temps universel, l'angle de rotation de la Terre) pris égal à UTC et le mouvement du pôle négligé, comme pour les autres exports. Les autres types de scénario LEO indiquent pourquoi un format ne s'applique pas (le tableau ci-dessous).

Campagnes#

Un campaign exporte chaque scénario membre qui a une géométrie comme son propre jeu de fichiers, l'étiquette du membre étant insérée avant le suffixe de format : chaque exécution de phase (<phase>, ou <phase>-<k> lorsque la phase a plusieurs exécutions), le scénario de base du balayage (sweep), le scénario Monte Carlo (monte-carlo) et chaque membre composé (son étiquette, avec les valeurs partagées qu'il lie incluses). campaign-shared-jammer-sea-road.toml --export kml écrit campaign-shared-jammer-sea-road.ship-strait.kml et campaign-shared-jammer-sea-road.car-coast-road.kml. Un membre identique à un membre précédent n'est écrit qu'une fois, et les valeurs qu'une campagne applique à l'exécution (transferts, valeurs de balayage, graines) ne figurent pas dans le membre exporté. Un format s'applique à une campagne lorsqu'il s'applique à l'un des membres ; sinon la raison est la note 4 du tableau ci-dessous. Voir CAMPAIGNS.md.

SigMF#

L'instantané [iq] du type de scénario spectrum — la bande L modélisée dessinée sous forme d'échantillons complexes à un instant — sous forme d'une paire .sigmf-meta / .sigmf-data, dans le type de données que nomme [iq] (cf32_le ou ci16_le). C'est le même enregistrement que l'exécution écrit et relit pour son propre contrôle de cohérence : les métadonnées exportées sont égales au bloc iq.sigmf.meta du document de résultat, et le fichier de données a la longueur iq.sigmf.data_bytes. L'écriture est assurée par src/sigmf.rs, le module que le type de scénario spectrum utilisait déjà ; rien n'est dupliqué.

Référentiels et temps#

• Le moteur propage en TEME (équateur vrai, équinoxe moyen de la date), son référentiel natif. Les objets mobiles sont tournés vers le GCRS par la réduction nutation::teme_to_gcrs (précession IAU 2006 et nutation IAU 2000B, où IAU est l'Union astronomique internationale), qui reproduit à 0,11 m l'exemple publié par Vallado de TEME vers GCRF (Geocentric Celestial Reference Frame), pour CZML et STK, et vers le référentiel terrestre par frames::teme_to_ecef pour KML et GeoJSON. La rotation vers le référentiel terrestre est l'angle sidéral moyen de Greenwich avec UT1 pris égal à UTC et sans mouvement du pôle — la même réduction que celle de l'export SP3 (Standard Product 3). Au rayon d'une orbite GPS, l'écart UT1−UTC négligé, pouvant atteindre 0,9 s, déplace la longitude d'un satellite d'au plus environ 1,7 km ; les sites au sol ne sont pas affectés, puisqu'ils sont donnés en latitude et longitude.
• Le type de scénario ephemeris fait exception : sa sortie du moteur porte déjà des positions GCRS et liées à la Terre (avec l'UT1−UTC et le mouvement du pôle du scénario, ou une véritable série de l'International Earth Rotation and Reference Systems Service (IERS)), et celles-ci sont écrites telles quelles.
• Tout temps est en UTC. Les secondes intercalaires ne sont pas modélisées : un décalage à travers une seconde intercalaire est compté comme si chaque jour avait 86 400 s, comme le comptent les grilles temporelles du moteur.
• L'époque de t = 0 est celle qu'utilise l'exécution du type de scénario, et chaque fichier la nomme : le epoch du type de scénario orbit ; lorsqu'il est absent, la plus ancienne époque que portent les données propres aux satellites (une époque d'ensemble d'éléments à deux lignes (TLE), le temps de référence d'une éphéméride diffusée, le début d'un fichier SP3), et 2000-01-01T00:00:00Z seulement lorsqu'aucun satellite n'en porte (éléments képlériens). Les exports SP3 et OEM (Orbit Ephemeris Message) conservent 2000-01-01T00:00:00Z pour un scénario sans epoch, de sorte que, pour un tel scénario, leurs dates diffèrent de celles de ces fichiers. Sans epoch de scénario, chaque satellite qui porte sa propre époque est tourné vers les référentiels GCRS et terrestre à son propre instant (son époque plus t), puisque c'est la date à laquelle appartient sa position TEME ; lorsque les époques des satellites diffèrent, les étiquettes de temps partagées suivent la prémisse du moteur selon laquelle chaque satellite démarre à t = 0, et le fichier dit de combien d'heures elles diffèrent. L'époque d'élément SGP4 des constellations de Walker des types de scénario jamming et gnss-sim (2018-06-12T00:00:00Z), que leurs exécutions utilisent aussi pour la rotation de la Terre ; le epoch du type de scénario passes ; le epoch ou l'époque TLE du type de scénario ephemeris. Le type de scénario integrity n'a pas d'époque calendaire ; son export date t = 0 comme pour un scénario d'orbite sans époque.
• Les satellites conservent les identifiants positionnels G01, G02, ... que leur donnent les exports SP3 et OEM, car les propagateurs ne portent pas les lignes de nom des TLE.

Importations#

• Itinéraire GeoJSON. --import-route <file> (bibliothèque : interop::geojson::apply_route) lit la première LineString d'un document GeoJSON — une géométrie seule, une Feature, ou une FeatureCollection — et l'écrit dans les entrées de trace de terrain-nav, terrain-slam, gravity-map et combined-altpnt (start_lat_deg, start_lon_deg, step_lat_deg, step_lon_deg, waypoints) avant l'exécution. Ces types de scénario parcourent start + i·step ; un itinéraire n'est donc accepté que s'il est exactement cela : ses deux extrémités (le nombre de waypoints du scénario est conservé), ou trois positions ou plus régulièrement espacées sur une droite en latitude et en longitude, à 1e-7 degré près (environ 1 cm). Tout autre itinéraire est refusé et l'erreur nomme la position la plus éloignée de la droite. Un itinéraire pour un type de scénario sans entrée de trajectoire est refusé avec cette raison. La longitude et la latitude sont contrôlées en plage, ce qui détecte un fichier à latitude en premier.
• Enregistrement SigMF. Le bloc [recording] du type de scénario spectrum lit une paire .sigmf-meta / .sigmf-data via src/sigmf.rs et trace son estimation de Welch à côté du modèle (voir SPECTRUM.md). La lecture de fichiers est une fonctionnalité de la version native ; la version WebAssembly prend les octets par kshana::sigmf::read.

Comment les exports sont vérifiés#

tests/interop_formats.rs analyse chaque export avec un validateur écrit à partir de la spécification du format, et non avec le code propre de l'écriture :

• CZML : un tableau JSON dont le premier paquet est le paquet de document avec version ; des identifiants de paquet uniques ; chaque position indique referenceFrame FIXED ou INERTIAL ; les positions échantillonnées sont [t, x, y, z, ...] avec une époque ISO 8601 et des temps croissants.
• KML : un document XML (Extensible Markup Language) bien formé dans l'espace de noms OGC KML 2,2 avec une seule entité racine ; l'ordre des éléments du schéma à l'intérieur d'un Placemark ; au plus une géométrie par Placemark ; des anneaux linéaires fermés de quatre positions ou plus ; des n-uplets lon,lat[,alt] dans la plage ; des valeurs altitudeMode valides ; des styleUrl qui se résolvent ; un gx:Track avec autant de <when> que de <gx:coord>, et l'espace de noms de l'extension déclaré.
• GeoJSON : longitude d'abord et dans la plage, latitude dans la plage, deux ou trois nombres par position, lignes brisées d'au moins deux positions, anneaux extérieurs fermés orientés dans le sens antihoraire, aucun segment à travers le méridien 180°, aucun membre crs, une propriété units sur chaque entité.
• STK : la ligne de version stk.v., un bloc BEGIN Ephemeris / END Ephemeris avec les mots-clés requis, DistanceUnit Meters, NumberOfEphemerisPoints égal au nombre de lignes de données, sept nombres par ligne, temps croissants.
• SigMF : core:datatype et core:version dans global, tableaux captures et annotations, core:sample_start sur chaque capture, et un fichier de données d'échantillons entiers.

Au-delà de la structure, un satellite exporté vers CZML et vers STK est comparé à l'état propre du moteur après la même réduction de référentiel, et concorde à 1 mm en position (les fichiers portent 0,1 mm) : par rapport à la sortie GCRS propre du type de scénario ephemeris, et par rapport à une propagation TEME vers GCRS indépendante de la constellation orbit-sgp4-gps, chaque satellite étant daté par sa propre époque TLE lue dans le texte du scénario. Deux contrôles sortent du moteur : les positions CZML du premier satellite orbit-sgp4-gps concordent à 0,1 m (mesuré 2,3 cm) avec le même TLE propagé par le paquet Python sgp4 et réduit vers le GCRS par ERFA (Essential Routines for Fundamental Astronomy, l'implémentation ouverte de la bibliothèque SOFA de l'IAU), et les positions liées à la Terre des satellites orbit-rinex sont égales à 1 mm aux positions d'éphéméride diffusée de la spécification d'interface du Global Positioning System. Les positions liées à la Terre de l'export jamming sont comparées aux positions que note l'exécution de brouillage, à 5 mm. L'itinéraire GeoJSON fait l'aller-retour via un scénario de trace, la paire SigMF se relit aux mêmes octets, et chaque export est déterministe à l'octet près.

Ce sont des contrôles par rapport aux spécifications publiées et par rapport au moteur lui-même. Les fichiers n'ont pas été chargés dans CesiumJS, Google Earth, Ansys STK ou un outil SDR dans le cadre de la suite de tests ; l'acceptation par une version particulière de ces outils n'est donc pas testée ici.

Échange d'orbite, d'attitude et de noyau (bibliothèque, 0,36)#

Outre les formats --export, 0,36 a ajouté des lecteurs et des écrivains de bibliothèque pour les fichiers standard qu'échangent les outils d'analyse de mission. Ils prennent et renvoient du texte ou des octets et ne touchent à aucun fichier. Chacun est une ligne VALIDATED de la matrice de vérification, par rapport à l'implémentation indépendante qui y est nommée :

• CCSDS Orbit Data Messages (kshana::odm, avec kshana::ndm_xml pour la forme XML) : OPM, OMM et OCM en notation clé-valeur (KVN) et NDM/XML, selon CCSDS 502.0-B-3 (OPM et OMM versions 3,0 et 2,0, OCM 3,0). Vérifiés dans les deux sens par rapport à Orekit : Orekit lit les fichiers de Kshana et Kshana lit ceux d'Orekit. Les constats qui subsistent sont figés par des tests.
• CCSDS Attitude Data Messages (kshana::adm, avec kshana::ndm_xml) : AEM et APM selon CCSDS 504.0-B-2, en KVN et NDM/XML. Vérifiés par rapport à Orekit de la même façon, ainsi que les rotations d'enregistrement par rapport à celles d'Orekit.
• SPICE SPK (kshana::spk_writer) : écrivains et lecteurs de segments NAIF SPK des types 9 et 13 (avec l'export d'un OEM CCSDS vers un noyau SPK) et des types 3 et 21 (polynômes de Tchebychev et lignes de différences étendues), vérifiés par rapport aux lecteurs propres de la boîte à outils NAIF SPICE, jusqu'à l'identité d'octets. Kshana écrit les segments à partir des enregistrements qu'on lui donne : il n'ajuste pas de coefficients de Tchebychev et ne produit pas de lignes de différences.

L'importateur et l'écrivain CCSDS OEM, ainsi que le bloc de covariance OEM, sont plus anciens et sont décrits dans les importations ci-dessus et dans la matrice.

Limites#

• Seuls les types de scénario du tableau ci-dessous exportent une géométrie. Les types de scénario dont la géométrie est centrée sur la Lune, Mars ou un autre corps ne sont pas exportés : CZML, KML et GeoJSON décrivent des positions autour de la Terre, et cette version n'écrit des fichiers STK qu'avec CentralBody Earth, bien que le format STK lui-même admette d'autres corps centraux.
• constellation-design, earth-gnss-lunar et oem-interop ont une géométrie référencée à la Terre que cette version n'exporte pas ; le tableau donne la raison pour chacun.
• Le type de scénario gnss-ins fait voler sa trajectoire dans un plan tangent local plat ; seule l'origine du plan est donc exportée, et non la trajectoire.
• Les positions de satellites liées à la Terre négligent UT1−UTC et le mouvement du pôle (voir Référentiels et temps) ; les hauteurs KML sont ellipsoïdales, et non au-dessus du niveau moyen de la mer.
• Les empreintes supposent une propagation en espace libre, un brouilleur à l'horizon du récepteur et une Terre sphérique pour le cercle.

Chaque fichier de scénario#

Ce que fait kshana <scenario> --export <format> pour chaque fichier de scenarios/ (le manifeste de la suite n'est pas un scénario et est écarté). « oui » signifie que le format est écrit et passe son validateur ; sinon le numéro renvoie à la raison. Généré par cargo run --bin gen_validation_artifacts ; tests/interop_formats.rs échoue lorsqu'il est périmé.

Pourquoi un format ne s'applique pas :

1. les types de scénario contact-schedule et acm-link planifient les contacts de liaison descendante et le codage ; exportez un scénario passes pour le même satellite et la même station afin de voir la géométrie
2. SigMF contient des échantillons complexes en bande de base, que seul le type de scénario spectrum synthétise
3. le type de scénario aocs simule l'attitude autour du centre de masse sans orbite ni position au sol, il n'y a donc rien à placer sur la Terre
4. l'entrée du scénario ne porte aucune position horizontale (ni latitude ni longitude, ni coordonnées géocentriques, ni éléments orbitaux au-delà d'au plus une altitude), il n'y a donc rien à placer sur la Terre
5. les types de scénario eo-radiometry et ascent-losses calculent des bilans sans position terrestre
6. une éphéméride STK décrit la position et la vitesse d'un véhicule en fonction du temps ; cette scène n'a que des points fixes ou des traces sans horodatage (un point fixe est une Facility STK, et non une éphéméride)
7. aucun scénario membre de la campagne n'a rien que ce format décrive ; exportez un membre seul pour voir sa raison
8. le type de scénario leo-signal analyse des conceptions de signal (spectres, poursuite, acquisition, compatibilité) sans position de satellite ni d'utilisateur ; exportez le scénario leo-pass ou leo-pnt-chain qui fait voler la conception
9. non exporté dans cette version : les types de scénario de positionnement fusionné placent leurs satellites dans un référentiel terrestre relatif à une époque qu'ils ne nomment jamais, de sorte qu'un export horodaté devrait inventer la date calendaire (exportez plutôt le scénario leo-pass ou leo-pnt-chain)
10. la géométrie du type de scénario est centrée sur la Lune, Mars ou un autre corps du système solaire ; CZML, KML et GeoJSON décrivent des positions sur ou autour de la Terre, et cette version n'écrit des éphémérides STK qu'avec CentralBody Earth
11. non exporté dans cette version : constellation-design place ses satellites dans un référentiel lié au corps relatif à une époque qu'il ne nomme jamais, de sorte qu'un export horodaté devrait inventer la date calendaire
12. non exporté dans cette version : la constellation terrestre de système mondial de navigation par satellite (GNSS) de earth-gnss-lunar est vue depuis un récepteur à distance lunaire, dont le type de scénario n'expose pas la trajectoire sous forme de série temporelle
13. non exporté dans cette version : le type de scénario entry-heating rapporte des charges de pointe et un échauffement, et ne conserve aucune trace au sol horodatée
14. le type de scénario gnss-ssv balaie la disponibilité et la puissance de liaison pour un utilisateur sur une couche ou une trajectoire képlérienne ; il n'a pas de position unique à placer sur une carte
15. le scénario launch-window donne la latitude du site de lancement mais pas de longitude, le site ne peut donc pas être placé
16. non exporté dans cette version : l'orbite de vérité de leo-navmsg est une référence d'ajustement dont l'angle de rotation de la Terre à l'époque est une entrée (theta0_deg, par défaut 0), et non dérivé de la date calendaire, de sorte que ses positions liées à la Terre ne sont pas rattachées à une date
17. ce scénario de spectre n'a pas de bloc [iq], aucun échantillon n'est donc synthétisé pour être enregistré
18. non exporté dans cette version : oem-interop lit et écrit un Orbit Ephemeris Message du CCSDS (Consultative Committee for Space Data Systems), qui est lui-même le fichier d'échange d'éphéméride
19. le type de scénario optical-atmosphere calcule des statistiques de liaison pour des sites au sol sans géométrie horodatée à placer
20. le scénario balaie un autre scénario sur une grille ; exportez le scénario balayé seul
21. le type de scénario time-transfer-budget calcule un bilan de liaison et des stabilités, sans géométrie horodatée à placer