Экспорт и импорт для совместимости

Прогон записывает документ результата, график и отчёт. --export также записывает геометрию сценария или его синтезированный сигнал в форматах, которые другие инструменты уже читают: программа просмотра земного шара, настольная карта, географическая информационная система (ГИС), пакет анализа миссий или инструмент программно-определяемого радио (SDR). Здесь ничто не обращается к часам или сети, и ни один экспорт не несёт отметки времени создания, поэтому один и тот же сценарий при каждом прогоне даёт побайтно идентичные файлы.

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

Файлы записываются рядом со сценарием и называются так же, как документ результата: jamming-demo.czml, jamming-demo.kml, jamming-demo.geojson, по одному jamming-demo.<object>.e на каждый движущийся объект (или jamming-demo.e, когда он один), и пара l-band-waterfall-jamming.sigmf-meta / .sigmf-data. С --study-name они получают имя исследования, как и прочие выходные файлы.

Формат, названный явно, но не применимый к сценарию, — это ошибка, выводящая причину; при all причина выводится, а формат пропускается. Точки входа библиотеки — kshana::interop::export(src, format), kshana::interop::plan(src) и kshana::interop::geojson::apply_route(src, geojson); они принимают текст сценария и возвращают байты, не трогая файлов, поэтому работают и в сборке WebAssembly. Сервер Model Context Protocol (MCP) предоставляет те же три функции как инструменты export_interop, list_export_formats и import_route (см. mcp/kshana-mcp/README.md).

Код: src/interop/ (scene.rs строит единое геометрическое описание сценария, czml.rs, kml.rs, geojson.rs и stk.rs записывают его), src/sigmf.rs и src/spectrum.rs для сигнала. Тесты: tests/interop_formats.rs.

Форматы#

Что содержит каждый файл#

Каждый геопространственный формат записывается из одной и той же сцены, поэтому они не могут расходиться в том, где что находится. В сцене до четырёх видов объектов:

• Движущиеся объекты — спутники и пользовательская платформа, когда она движется, — дискретизированные на собственной временной сетке сценария теми пропагаторами, которые использует прогон данного вида.
• Неподвижные пункты — приёмник, наземная станция, источник помех (jammer) или начало локальной навигационной системы координат.
• Треки без времени — путевые точки, по которым идёт вид альтернативного позиционирования, навигации и времени (PNT) по рельефу, гравитации или комбинированный. У этих видов нет оси времени, поэтому у треков её нет.
• Зоны воздействия источника помех — для вида jamming две окружности вокруг источника помех: дальность по земле, внутри которой спутник в зените (самый сильный) падает ниже порога слежения, так что теряются все спутники, и дальность, внутри которой так происходит со спутником на маске возвышения (самым слабым), так что слежение начинает отказывать. Обе получены из собственных уравнений линии связи данного вида (Kaplan и Hegarty, Understanding GPS/GNSS (Global Positioning System / Global Navigation Satellite Systems), 3-е изд., §9,4) при источнике помех на горизонте приёмника и потерях в свободном пространстве, а набор тестов проверяет, что эффективное отношение несущей к плотности шума на каждом радиусе равно порогу с точностью 1e-6 дБ. Окружность строится на сфере среднего радиуса Земли.

CZML#

Первый пакет — пакет документа ("id": "document", "version": "1.0") с часами, охватывающими временную сетку. Каждый движущийся объект — это пакет, у которого position содержит эпоху epoch в формате ISO 8601 (формат даты и времени Международной организации по стандартизации) UTC (всемирное координированное время), referenceFrame "INERTIAL" и отсчёты cartesian [t, x, y, z, ...]: секунды после эпохи, метры в Геоцентрической небесной системе отсчёта (GCRS). CesiumJS принимает INERTIAL за Международную небесную систему отсчёта (ICRF), оси которой совпадают с осями GCRS. Неподвижные пункты и центры зон — это постоянные положения cartesian в земной системе с referenceFrame "FIXED". Зона — это ellipse с обеими полуосями, равными её радиусу; трек без времени — polyline, прижатая к земле. Поле description каждого пакета снова описывает систему отсчёта словами.

KML#

Один <Document> с <Folder> на каждый класс объектов. Движущийся объект — это <Placemark>, содержащий <gx:Track>: по одному <when> на отсчёт (ISO 8601 UTC), затем по одному <gx:coord> на отсчёт (долгота, широта, высота). Пункты — это <Point>, зоны — <Polygon> с замкнутым кольцом против часовой стрелки, треки без времени — <LineString>. Координаты — долгота и широта Всемирной геодезической системы 1984 (WGS 84) в десятичных градусах и высота в метрах над эллипсоидом WGS 84, записанные с altitudeMode absolute. KML читает absolute как высоту над средним уровнем моря; разница, ундуляция геоида, находится в пределах около ±110 м и не применяется. В описании документа это сказано.

GeoJSON#

Один FeatureCollection. Позиции — [longitude, latitude] или [longitude, latitude, height] — сначала долгота, как требует RFC 7946 — в градусах WGS 84, высота в метрах над эллипсоидом. Движущийся объект — это LineString со свойством times_utc, содержащим одно время ISO 8601 на каждую позицию; трек, пересекающий меридиан 180°, записывается как MultiLineString, разрезанный на нём, как требует RFC 7946 §3.1.9 (точка пересечения интерполируется, а times_utc затем перечисляет только исходные отсчёты). Пункты — это Point, зоны — Polygon с замкнутым внешним кольцом против часовой стрелки (§3.1.6), треки без времени — LineString. У каждого объекта есть свойство units, называющее единицу каждого числового члена.

STK .e#

Один файл на каждый движущийся объект, поскольку эфемериды STK описывают одно транспортное средство. Заголовок задаёт NumberOfEphemerisPoints (равно числу строк данных), ScenarioEpoch (UTC, d Mon yyyy hh:mm:ss.ssssss), InterpolationMethod Lagrange с InterpolationSamplesM1 5, CentralBody Earth, CoordinateSystem ICRF и DistanceUnit Meters; строки под EphemerisTimePosVel — это секунды после эпохи, положение в метрах и скорость в метрах в секунду, в GCRS. Сцена только с неподвижными пунктами или треками без времени не записывает файл .e: неподвижная точка — это объект STK Facility, а не эфемериды. Идентификатор, не являющийся простой частью имени файла (оболочка орбитальной группировки и спутник, Pulsar inclined/S1-0163), записывается с заменой каждого другого символа на -, с нумерацией, если два идентификатора после этого совпадают.

Вид leo-pass и вид leo-pnt-chain (через его этап [pass]) экспортируют каждый спутник на низкой околоземной орбите (LEO) и пользователя, используя собственные пропагаторы и временную сетку вида. Вид работает в ECI0 — земной инерциальной системе, совмещённой с земной фиксированной системой на эпоху; каждый отсчёт переводится в земную фиксированную систему на собственный момент времени с помощью вращения Земли, принятого в данном виде, а оттуда в GCRS через систему истинного экватора и среднего равноденствия (TEME), в которой выдаёт результат пропагатор Simplified General Perturbations 4 (SGP4), на тот же момент, при этом UT1 (всемирное время, угол вращения Земли) принято равным UTC, а движение полюса не учитывается, как и в других экспортах. Остальные виды LEO указывают, почему формат неприменим (таблица ниже).

Кампании#

campaign экспортирует каждый входящий в него сценарий, имеющий геометрию, в виде отдельного набора файлов, причём метка участника вставляется перед суффиксом формата: каждый прогон фазы (<phase> или <phase>-<k>, если в фазе несколько прогонов), базовый сценарий перебора (sweep), сценарий Монте-Карло (monte-carlo) и каждый составной участник (его метка с вписанными общими значениями, которые он привязывает). campaign-shared-jammer-sea-road.toml --export kml записывает campaign-shared-jammer-sea-road.ship-strait.kml и campaign-shared-jammer-sea-road.car-coast-road.kml. Участник, идентичный более раннему, записывается один раз, а значения, которые кампания применяет во время прогона (передачи, значения перебора, начальные значения seed), в экспортированном участнике отсутствуют. Формат применим к кампании, если применим к любому участнику; в противном случае причина указана в примечании 4 таблицы ниже. См. CAMPAIGNS.md.

SigMF#

Снимок [iq] вида spectrum — смоделированный L-диапазон, представленный комплексными отсчётами в один момент, — в виде пары .sigmf-meta / .sigmf-data, в типе данных, который называет [iq] (cf32_le или ci16_le). Это та же запись, которую прогон записывает и считывает обратно для собственной проверки согласованности: экспортированные метаданные равны блоку iq.sigmf.meta документа результата, а у файла данных длина iq.sigmf.data_bytes. Записывает её src/sigmf.rs — модуль, который вид spectrum уже использовал; ничего не дублируется.

Системы отсчёта и время#

• Движок выполняет пропагацию в TEME (истинный экватор, среднее равноденствие даты), своей родной системе. Движущиеся объекты поворачиваются в GCRS редукцией nutation::teme_to_gcrs (прецессия IAU 2006 и нутация IAU 2000B, где IAU — Международный астрономический союз), которая воспроизводит опубликованный у Валладо пример перехода TEME в GCRF (Geocentric Celestial Reference Frame) с точностью 0,11 м, — для CZML и STK, а в земную фиксированную систему — через frames::teme_to_ecef для KML и GeoJSON. Поворот в земную систему задаётся гринвичским средним звёздным углом при UT1, принятом равным UTC, без учёта движения полюса — та же редукция, что и в экспорте SP3 (Standard Product 3). На радиусе орбиты GPS неучтённая разность UT1−UTC до 0,9 с смещает долготу спутника до примерно 1,7 км; наземные пункты не затрагиваются, поскольку заданы широтой и долготой.
• Исключение составляет вид ephemeris: его выход движка уже содержит положения в GCRS и в земной системе (с UT1−UTC и движением полюса сценария либо с реальным рядом Международной службы вращения Земли и систем отсчёта (IERS)), и они записываются без изменений.
• Всё время — UTC. Високосные секунды не моделируются: смещение через високосную секунду считается так, как если бы в каждых сутках было 86 400 с, как считают временные сетки движка.
• Эпоха t = 0 — та, которую использует прогон данного вида, и каждый файл её называет: epoch вида orbit; при её отсутствии — самая ранняя эпоха, которую несут собственные данные спутников (эпоха двухстрочного набора элементов (TLE), опорное время широковещательных эфемерид, начало файла SP3), и 2000-01-01T00:00:00Z лишь тогда, когда ни один спутник её не несёт (кеплеровы элементы). Экспорты SP3 и OEM (Orbit Ephemeris Message) сохраняют 2000-01-01T00:00:00Z для сценария без epoch, поэтому для такого сценария их даты отличаются от дат этих файлов. Без epoch сценария каждый спутник, несущий собственную эпоху, поворачивается в GCRS и земную системы на собственный момент (его эпоха плюс t), поскольку именно этой дате принадлежит его положение в TEME; там, где эпохи спутников различаются, общие метки времени следуют предпосылке движка, что каждый спутник стартует в t = 0, а файл указывает, на сколько часов они различаются. Эпоха элементов SGP4 орбитальных группировок Уокера видов jamming и gnss-sim (2018-06-12T00:00:00Z), которую их прогоны также используют для вращения Земли; epoch вида passes; epoch или эпоха TLE вида ephemeris. У вида integrity нет календарной эпохи; его экспорт датирует t = 0 так же, как для сценария орбиты без неё.
• Спутники сохраняют позиционные идентификаторы G01, G02, ..., которые им дают экспорты SP3 и OEM, потому что пропагаторы не несут строк имён TLE.

Импорт#

• Маршрут GeoJSON. --import-route <file> (библиотека: interop::geojson::apply_route) читает первый LineString документа GeoJSON — отдельную геометрию, Feature или FeatureCollection — и записывает его во входные данные треков видов terrain-nav, terrain-slam, gravity-map и combined-altpnt (start_lat_deg, start_lon_deg, step_lat_deg, step_lon_deg, waypoints) перед прогоном. Эти виды летят по start + i·step, поэтому маршрут принимается, когда он именно таков: два его конца (число waypoints сценария сохраняется) либо три или более позиций, равномерно расположенных на прямой по широте и долготе, с точностью до 1e-7 градуса (около 1 см). Любой другой маршрут отклоняется, а ошибка называет позицию, наиболее удалённую от прямой. Маршрут для вида без входных данных траектории отклоняется с указанием этой причины. Долгота и широта проверяются на диапазон, что выявляет файл, где широта идёт первой.
• Запись SigMF. Блок [recording] вида spectrum читает пару .sigmf-meta / .sigmf-data через src/sigmf.rs и строит график своей оценки Уэлча рядом с моделью (см. SPECTRUM.md). Чтение файлов — возможность нативной сборки; сборка WebAssembly получает байты через kshana::sigmf::read.

Как проверяются экспорты#

tests/interop_formats.rs разбирает каждый экспорт валидатором, написанным по спецификации формата, а не кодом самого записывающего модуля:

• CZML: массив JSON, первый пакет которого — пакет документа с version; уникальные идентификаторы пакетов; каждая позиция задаёт referenceFrame FIXED или INERTIAL; дискретизированные позиции — это [t, x, y, z, ...] с эпохой ISO 8601 и возрастающими временами.
• KML: корректно сформированный документ XML (Extensible Markup Language) в пространстве имён OGC KML 2,2 с одним корневым объектом; порядок элементов схемы внутри Placemark; не более одной геометрии на Placemark; замкнутые линейные кольца из четырёх или более позиций; кортежи lon,lat[,alt] в допустимом диапазоне; допустимые значения altitudeMode; styleUrl, которые разрешаются; gx:Track с таким же числом <when>, как и <gx:coord>, и объявленное пространство имён расширения.
• GeoJSON: сначала долгота и в допустимом диапазоне, широта в допустимом диапазоне, два или три числа на позицию, ломаные из двух или более позиций, замкнутые внешние кольца против часовой стрелки, ни одного сегмента через меридиан 180°, ни одного члена crs, свойство units у каждого объекта.
• STK: строка версии stk.v., блок BEGIN Ephemeris / END Ephemeris с обязательными ключевыми словами, DistanceUnit Meters, NumberOfEphemerisPoints, равное числу строк данных, семь чисел в строке, возрастающие времена.
• SigMF: core:datatype и core:version в global, массивы captures и annotations, core:sample_start в каждом захвате и файл данных из целых отсчётов.

Помимо структуры, спутник, экспортированный в CZML и STK, сравнивается с собственным состоянием движка после той же редукции систем отсчёта и совпадает с ним до 1 мм по положению (файлы несут 0,1 мм): с собственным выходом в GCRS вида ephemeris и с независимой пропагацией из TEME в GCRS группировки orbit-sgp4-gps, где каждый спутник датирован собственной эпохой TLE, считанной из текста сценария. Две проверки выходят за пределы движка: положения CZML первого спутника orbit-sgp4-gps совпадают с точностью 0,1 м (измерено 2,3 см) с тем же TLE, пропагированным пакетом Python sgp4 и приведённым к GCRS средствами ERFA (Essential Routines for Fundamental Astronomy, открытая реализация библиотеки SOFA Международного астрономического союза), а положения спутников orbit-rinex в земной системе равны положениям из широковещательных эфемерид по спецификации интерфейса Global Positioning System с точностью 1 мм. Положения экспорта jamming в земной системе сравниваются с положениями, по которым оценивается прогон с подавлением, с точностью 5 мм. Маршрут GeoJSON проходит круговой путь через сценарий трека, пара SigMF считывается обратно в те же байты, и каждый экспорт побайтно детерминирован.

Это проверки по опубликованным спецификациям и по самому движку. Файлы не загружались в CesiumJS, Google Earth, Ansys STK или инструмент SDR в составе набора тестов, поэтому приём конкретной версией этих инструментов здесь не проверяется.

Обмен данными об орбитах, ориентации и ядрах (библиотека, 0,36)#

Помимо форматов --export, в 0,36 добавлены библиотечные читатели и записыватели стандартных файлов, которыми обмениваются инструменты анализа миссий. Они принимают и возвращают текст или байты и не трогают файлов. Каждый из них — строка VALIDATED в матрице верификации по независимой реализации, названной там:

• Сообщения CCSDS с данными об орбите (kshana::odm, с kshana::ndm_xml для формы XML): OPM, OMM и OCM в нотации «ключ — значение» (KVN) и NDM/XML по CCSDS 502.0-B-3 (OPM и OMM версий 3,0 и 2,0, OCM 3,0). Проверено в обе стороны на Orekit: Orekit читает файлы Kshana, а Kshana читает файлы Orekit. Остающиеся расхождения закреплены тестами.
• Сообщения CCSDS с данными об ориентации (kshana::adm, с kshana::ndm_xml): AEM и APM по CCSDS 504.0-B-2, в KVN и NDM/XML. Проверено на Orekit тем же способом, а повороты записей — по Orekit.
• SPICE SPK (kshana::spk_writer): записыватели и читатели сегментов NAIF SPK типов 9 и 13 (с экспортом CCSDS OEM в ядро SPK) и типов 3 и 21 (полиномы Чебышёва и расширенные строки разностей), проверенные по собственным читателям набора NAIF SPICE вплоть до побайтного совпадения. Kshana записывает сегменты по переданным ей записям: она не подбирает коэффициенты Чебышёва и не создаёт строки разностей.

Импортёр и записыватель CCSDS OEM, а также блок ковариации OEM появились раньше и описаны в разделе об импорте выше и в матрице.

Ограничения#

• Геометрию экспортируют только виды из таблицы ниже. Виды, геометрия которых центрирована на Луне, Марсе или другом теле, не экспортируются: CZML, KML и GeoJSON описывают положения относительно Земли, а в этом выпуске файлы STK записываются только с CentralBody Earth, хотя сам формат STK допускает и другие центральные тела.
• constellation-design, earth-gnss-lunar и oem-interop имеют геометрию, привязанную к Земле, которую этот выпуск не экспортирует; причина для каждого вида указана в таблице.
• Вид gnss-ins прокладывает траекторию в плоской локальной касательной плоскости, поэтому экспортируется только начало этой плоскости, а не траектория.
• Положения спутников в земной системе не учитывают UT1−UTC и движение полюса (см. «Системы отсчёта и время»); высоты KML эллипсоидальные, а не над средним уровнем моря.
• Зоны воздействия предполагают распространение в свободном пространстве, источник помех на горизонте приёмника и сферическую Землю для окружности.

Каждый файл сценария#

Что делает kshana <scenario> --export <format> для каждого файла в scenarios/ (манифест набора не является сценарием и опущен). «yes» означает, что формат записан и проходит свой валидатор; в противном случае номер указывает на причину. Создано с помощью cargo run --bin gen_validation_artifacts; tests/interop_formats.rs завершается неудачей, если таблица устарела.

Почему формат неприменим:

1. виды contact-schedule и acm-link планируют контакты нисходящей линии и кодирование; чтобы увидеть геометрию, экспортируйте сценарий passes для того же спутника и той же станции
2. SigMF содержит комплексные отсчёты в основной полосе, которые синтезирует только вид spectrum
3. вид aocs моделирует ориентацию относительно центра масс без орбиты и положения на земле, поэтому на Земле размещать нечего
4. во входных данных сценария нет горизонтального положения (ни широты и долготы, ни геоцентрических координат, ни орбитальных элементов, кроме, самое большее, высоты), поэтому на Земле размещать нечего
5. виды eo-radiometry и ascent-losses вычисляют бюджеты без положения на Земле
6. эфемериды STK описывают положение и скорость аппарата в зависимости от времени; в этой сцене есть только неподвижные точки или треки без времени (неподвижная точка — это объект STK Facility, а не эфемериды)
7. ни у одного входящего в кампанию сценария нет ничего, что описывает этот формат; экспортируйте участника отдельно, чтобы увидеть его причину
8. вид leo-signal анализирует проекты сигналов (спектры, слежение, захват, совместимость) без положения спутника или пользователя; экспортируйте сценарий leo-pass или leo-pnt-chain, в котором летит этот проект
9. не экспортируется в этом выпуске: виды комплексного позиционирования размещают свои спутники в земной фиксированной системе относительно эпохи, которую никогда не называют, поэтому экспорт с отметками времени пришлось бы придумывать календарную дату (вместо этого экспортируйте сценарий leo-pass или leo-pnt-chain)
10. геометрия вида центрирована на Луне, Марсе или другом теле Солнечной системы; CZML, KML и GeoJSON описывают положения на Земле или вокруг неё, а в этом выпуске эфемериды STK записываются только с CentralBody Earth
11. не экспортируется в этом выпуске: constellation-design размещает свои спутники в системе, фиксированной относительно тела, относительно эпохи, которую никогда не называет, поэтому экспорт с отметками времени пришлось бы придумывать календарную дату
12. не экспортируется в этом выпуске: орбитальная группировка земной глобальной навигационной спутниковой системы (GNSS) в earth-gnss-lunar видна из приёмника на лунном расстоянии, траекторию которого вид не предоставляет в виде временного ряда
13. не экспортируется в этом выпуске: вид entry-heating сообщает пиковые нагрузки и нагрев и не хранит трассу на поверхности с отметками времени
14. вид gnss-ssv перебирает доступность и мощность линии для пользователя на оболочке или кеплеровой траектории; у него нет единственного положения, которое можно разместить на карте
15. сценарий launch-window задаёт широту места старта, но не долготу, поэтому место нельзя разместить
16. не экспортируется в этом выпуске: истинная орбита leo-navmsg — это подгоночная опорная орбита, у которой угол вращения Земли на эпоху является входным параметром (theta0_deg, по умолчанию 0), а не выводится из календарной даты, поэтому её положения в земной системе не привязаны к дате
17. в этом сценарии спектра нет блока [iq], поэтому отсчёты для записи не синтезируются
18. не экспортируется в этом выпуске: oem-interop читает и записывает Orbit Ephemeris Message CCSDS (Consultative Committee for Space Data Systems), который сам является файлом обмена эфемеридами
19. вид optical-atmosphere вычисляет статистику линий для наземных пунктов без геометрии с отметками времени, которую можно разместить
20. сценарий перебирает другой сценарий по сетке; экспортируйте перебираемый сценарий отдельно
21. вид time-transfer-budget вычисляет бюджет линии и стабильности без геометрии с отметками времени, которую можно разместить