Exportações e importações de interoperabilidade

Uma execução grava um documento de resultado, um gráfico e um relatório. --export também grava a geometria do cenário, ou o seu sinal sintetizado, nos formatos que outras ferramentas já leem: um visualizador de globo, um mapa de desktop, um sistema de informação geográfica (GIS), um pacote de análise de missão ou uma ferramenta de rádio definido por software (SDR). Nada aqui lê um relógio ou a rede, e nenhuma exportação traz carimbo de data e hora de geração; assim, o mesmo cenário gera arquivos idênticos byte a byte a cada execução.

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

Os arquivos são gravados ao lado do cenário, com nomes iguais ao do documento de resultado: jamming-demo.czml, jamming-demo.kml, jamming-demo.geojson, um jamming-demo.<object>.e por objeto em movimento (ou jamming-demo.e quando há apenas um) e o par l-band-waterfall-jamming.sigmf-meta / .sigmf-data. Com --study-name, eles tomam o nome do estudo, como as outras saídas.

Um formato nomeado explicitamente que não se aplica ao cenário é um erro que imprime o motivo; com all, o motivo é impresso e o formato é ignorado. Os pontos de entrada da biblioteca são kshana::interop::export(src, format), kshana::interop::plan(src) e kshana::interop::geojson::apply_route(src, geojson); eles recebem o texto do cenário e devolvem bytes, sem tocar em nenhum arquivo, de modo que rodam também na build WebAssembly. O servidor do Model Context Protocol (MCP) oferece os mesmos três como as ferramentas export_interop, list_export_formats e import_route (veja mcp/kshana-mcp/README.md).

Código: src/interop/ (scene.rs constrói uma descrição geométrica do cenário; czml.rs, kml.rs, geojson.rs e stk.rs a gravam), src/sigmf.rs e src/spectrum.rs para o sinal. Testes: tests/interop_formats.rs.

Formatos#

O que cada arquivo contém#

Todo formato geoespacial é gravado a partir da mesma cena, de modo que não podem divergir quanto à posição de qualquer coisa. Uma cena tem até quatro tipos de objeto:

• Objetos em movimento — satélites e uma plataforma de usuário quando se move — amostrados na própria grade de tempo do cenário, com os propagadores que a execução do tipo de cenário usa.
• Locais fixos — um receptor, uma estação terrestre, um jammer ou a origem de um referencial de navegação local.
• Trilhas sem tempo — os pontos de passagem que um tipo de cenário de posicionamento, navegação e temporização (PNT) alternativo de terreno, gravidade ou combinado percorre. Esses tipos de cenário não têm eixo de tempo, portanto as trilhas não carregam nenhum.
• Áreas de cobertura do jammer — para o tipo de cenário jamming, dois círculos em torno do jammer: o alcance no solo dentro do qual um satélite no zênite (o mais forte) cai abaixo do limiar de rastreamento, de modo que todos os satélites são perdidos, e o alcance dentro do qual um satélite na máscara de elevação (o mais fraco) cai, de modo que o rastreamento começa a falhar. Ambos vêm das equações de enlace do próprio tipo de cenário (Kaplan e Hegarty, Understanding GPS/GNSS (Global Positioning System / Global Navigation Satellite Systems), 3ª ed., §9,4), com o jammer no horizonte do receptor e perda no espaço livre, e o conjunto de testes verifica que a relação portadora/densidade de ruído efetiva em cada raio é igual ao limiar com precisão de 1e-6 dB. O círculo é desenhado em uma esfera com o raio médio da Terra.

CZML#

O primeiro pacote é o pacote do documento ("id": "document", "version": "1.0"), com um relógio que abrange a grade de tempo. Cada objeto em movimento é um pacote cujo position tem uma epoch ISO 8601 (formato de data e hora da Organização Internacional de Normalização) UTC (Tempo Universal Coordenado), referenceFrame "INERTIAL" e amostras cartesian [t, x, y, z, ...]: segundos após a época, metros no Geocentric Celestial Reference System (GCRS). O CesiumJS toma INERTIAL como o International Celestial Reference Frame (ICRF), cujos eixos o GCRS compartilha. Os locais fixos e os centros das áreas de cobertura são posições cartesian constantes, fixas à Terra, com referenceFrame "FIXED". Uma área de cobertura é uma ellipse com ambos os semieixos iguais ao seu raio; uma trilha sem tempo é uma polyline fixada ao solo. A description de cada pacote declara o referencial novamente em palavras.

KML#

Um <Document> com uma <Folder> por classe de objeto. Um objeto em movimento é um <Placemark> que contém um <gx:Track>: um <when> por amostra (ISO 8601 UTC) e depois um <gx:coord> por amostra (longitude, latitude, altura). Os locais são <Point>, as áreas de cobertura são <Polygon> cujo anel é fechado e anti-horário, e as trilhas sem tempo são <LineString>. As coordenadas são longitude e latitude do World Geodetic System 1984 (WGS 84) em graus decimais e altura em metros acima do elipsoide WGS 84, gravadas com altitudeMode absolute. O KML lê absolute como altura acima do nível médio do mar; a diferença, a ondulação do geoide, fica dentro de cerca de ±110 m e não é aplicada. A descrição do documento informa isso.

GeoJSON#

Uma FeatureCollection. As posições são [longitude, latitude] ou [longitude, latitude, height] — longitude primeiro, como a RFC 7946 exige — em graus WGS 84, com altura em metros acima do elipsoide. Um objeto em movimento é um LineString com uma propriedade times_utc que contém um horário ISO 8601 por posição; uma trilha que cruza o meridiano de 180° é gravada como um MultiLineString cortado ali, como a RFC 7946 §3.1.9 pede (o ponto de cruzamento é interpolado, e times_utc lista então apenas as amostras originais). Os locais são Point, as áreas de cobertura são Polygon com anel exterior fechado e anti-horário (§3.1.6), e as trilhas sem tempo são LineString. Cada feature tem uma propriedade units que nomeia a unidade de cada membro numérico.

STK .e#

Um arquivo por objeto em movimento, já que uma efeméride do STK descreve um veículo. O cabeçalho traz NumberOfEphemerisPoints (igual ao número de linhas de dados), ScenarioEpoch (UTC, d Mon yyyy hh:mm:ss.ssssss), InterpolationMethod Lagrange com InterpolationSamplesM1 5, CentralBody Earth, CoordinateSystem ICRF e DistanceUnit Meters; as linhas sob EphemerisTimePosVel são segundos após a época, posição em metros e velocidade em metros por segundo, no GCRS. Uma cena com apenas locais fixos ou trilhas sem tempo não grava nenhum arquivo .e: um ponto fixo é uma Facility do STK, não uma efeméride. Um id que não é uma parte simples de nome de arquivo (uma camada de constelação e um satélite, Pulsar inclined/S1-0163) é gravado com cada outro caractere como -, numerado se dois ids passarem a coincidir.

O tipo de cenário leo-pass e o tipo de cenário leo-pnt-chain (por meio do seu estágio [pass]) exportam todos os satélites de órbita terrestre baixa (LEO) e o usuário a partir dos propagadores e da grade de tempo do próprio tipo de cenário. O tipo de cenário trabalha em ECI0, o referencial inercial centrado na Terra alinhado com o referencial fixo à Terra na época; cada amostra é convertida para o referencial fixo à Terra no seu próprio instante pela rotação da Terra do tipo de cenário e, a partir daí, para o GCRS por meio do referencial true equator, mean equinox (TEME) em que o propagador Simplified General Perturbations 4 (SGP4) produz a saída, naquele instante, com o UT1 (Tempo Universal, o ângulo de rotação da Terra) tomado igual ao UTC e o movimento polar desprezado, como nas outras exportações. Os outros tipos de cenário LEO informam por que um formato não se aplica (a tabela abaixo).

Campanhas#

Um campaign exporta cada cenário membro que tem geometria como seu próprio conjunto de arquivos, com o rótulo do membro inserido antes do sufixo do formato: cada execução de fase (<phase>, ou <phase>-<k> quando a fase tem várias execuções), o cenário-base do sweep (sweep), o cenário de Monte Carlo (monte-carlo) e cada membro composto (o seu rótulo, com os valores compartilhados que ele vincula gravados). campaign-shared-jammer-sea-road.toml --export kml grava campaign-shared-jammer-sea-road.ship-strait.kml e campaign-shared-jammer-sea-road.car-coast-road.kml. Um membro idêntico a um anterior é gravado uma vez, e os valores que uma campanha aplica em tempo de execução (transferências, valores de sweep, sementes) não estão no membro exportado. Um formato se aplica a uma campanha quando se aplica a qualquer membro; caso contrário, o motivo é a nota 4 da tabela abaixo. Veja CAMPAIGNS.md.

SigMF#

O instantâneo [iq] do tipo de cenário spectrum — a banda L modelada, desenhada como amostras complexas em um instante — como um par .sigmf-meta / .sigmf-data, no tipo de dado que [iq] nomeia (cf32_le ou ci16_le). É a mesma gravação que a execução grava e relê para a sua própria verificação de consistência: os metadados exportados são iguais ao bloco iq.sigmf.meta do documento de resultado, e o arquivo de dados tem o comprimento iq.sigmf.data_bytes. O gravador é src/sigmf.rs, o módulo que o tipo de cenário spectrum já usava; nada é duplicado.

Referenciais e tempo#

• O motor propaga em TEME (true equator, mean equinox of date), o seu referencial nativo. Os objetos em movimento são rotacionados para o GCRS pela redução nutation::teme_to_gcrs (precessão IAU 2006 e nutação IAU 2000B, em que IAU é a União Astronômica Internacional), que reproduz o exemplo publicado de Vallado de TEME para GCRF (Geocentric Celestial Reference Frame) com 0,11 m, para CZML e STK, e para o referencial fixo à Terra por frames::teme_to_ecef para KML e GeoJSON. A rotação fixa à Terra é o ângulo sideral médio de Greenwich, com o UT1 tomado igual ao UTC e o movimento polar não aplicado — a mesma redução que a exportação SP3 (Standard Product 3) usa. Em um raio de órbita de GPS, o UT1−UTC desprezado, de até 0,9 s, desloca a longitude de um satélite em até cerca de 1,7 km; os locais em terra não são afetados, pois são dados em latitude e longitude.
• O tipo de cenário ephemeris é a exceção: a sua saída do motor já traz posições GCRS e fixas à Terra (com o UT1−UTC e o movimento polar do cenário, ou uma série real do International Earth Rotation and Reference Systems Service (IERS)), e essas são gravadas sem alteração.
• Todo horário é UTC. Os segundos intercalares não são modelados: um deslocamento que atravessa um segundo intercalar é contado como se todo dia tivesse 86.400 s, como as grades de tempo do motor contam.
• A época de t = 0 é a que a execução do tipo de cenário usa, e cada arquivo a nomeia: a epoch do tipo de cenário orbit; quando ela está ausente, a época mais antiga que os próprios dados dos satélites trazem (uma época de conjunto de elementos de duas linhas (TLE), o tempo de referência de uma efeméride transmitida, o início de um arquivo SP3) e 2000-01-01T00:00:00Z somente quando nenhum satélite traz uma (elementos keplerianos). As exportações SP3 e OEM (Orbit Ephemeris Message) mantêm 2000-01-01T00:00:00Z para um cenário sem epoch; assim, para esse cenário, as suas datas diferem das destes arquivos. Sem epoch de cenário, cada satélite que traz a sua própria época é rotacionado para os referenciais GCRS e fixo à Terra no seu próprio instante (a sua época mais t), já que é essa a data a que pertence a sua posição TEME; quando as épocas dos satélites diferem, as marcas de tempo compartilhadas seguem a premissa do motor de que todo satélite começa em t = 0, e o arquivo informa por quantas horas elas diferem. A época do elemento SGP4 das constelações Walker dos tipos de cenário jamming e gnss-sim (2018-06-12T00:00:00Z), que as suas execuções também usam para a rotação da Terra; a epoch do tipo de cenário passes; a epoch do tipo de cenário ephemeris ou a época do TLE. O tipo de cenário integrity não tem época de calendário; a sua exportação data t = 0 como para um cenário de órbita sem ela.
• Os satélites mantêm os identificadores posicionais G01, G02, ... que as exportações SP3 e OEM lhes dão, porque os propagadores não carregam as linhas de nome do TLE.

Importações#

• Rota GeoJSON. --import-route <file> (biblioteca: interop::geojson::apply_route) lê o primeiro LineString de um documento GeoJSON — uma geometria simples, uma Feature ou uma FeatureCollection — e o grava nas entradas de trilha de terrain-nav, terrain-slam, gravity-map e combined-altpnt (start_lat_deg, start_lon_deg, step_lat_deg, step_lon_deg, waypoints) antes da execução. Esses tipos de cenário percorrem start + i·step; por isso uma rota é aceita quando é exatamente isso: os seus dois extremos (a contagem de waypoints do cenário é mantida), ou três ou mais posições igualmente espaçadas em uma reta em latitude e longitude, com precisão de 1e-7 grau (cerca de 1 cm). Qualquer outra rota é recusada e o erro nomeia a posição mais afastada da reta. Uma rota para um tipo de cenário sem entrada de trajetória é recusada com esse motivo. Longitude e latitude têm o intervalo verificado, o que detecta um arquivo com latitude primeiro.
• Gravação SigMF. O bloco [recording] do tipo de cenário spectrum lê um par .sigmf-meta / .sigmf-data por meio de src/sigmf.rs e plota a sua estimativa de Welch ao lado do modelo (veja SPECTRUM.md). Ler arquivos é um recurso da build nativa; a build WebAssembly recebe os bytes por meio de kshana::sigmf::read.

Como as exportações são verificadas#

tests/interop_formats.rs analisa cada exportação com um validador escrito a partir da especificação do formato, e não com o código do próprio gravador:

• CZML: um array JSON cujo primeiro pacote é o pacote do documento com um version; identificadores de pacote únicos; toda posição declara referenceFrame FIXED ou INERTIAL; as posições amostradas são [t, x, y, z, ...] com uma época ISO 8601 e tempos crescentes.
• KML: um documento XML (Extensible Markup Language) bem formado no namespace OGC KML 2,2, com uma feature raiz; a ordem dos elementos do esquema dentro de um Placemark; no máximo uma geometria por Placemark; anéis lineares fechados de quatro ou mais posições; tuplas lon,lat[,alt] dentro do intervalo; valores altitudeMode válidos; styleUrl que se resolvem; um gx:Track com tantos <when> quantos <gx:coord>, e o namespace da extensão declarado.
• GeoJSON: longitude primeiro e dentro do intervalo, latitude dentro do intervalo, dois ou três números por posição, linhas de duas ou mais posições, anéis exteriores fechados e anti-horários, nenhum segmento cruzando o meridiano de 180°, nenhum membro crs, uma propriedade units em cada feature.
• STK: a linha de versão stk.v., um bloco BEGIN Ephemeris / END Ephemeris com as palavras-chave exigidas, DistanceUnit Meters, NumberOfEphemerisPoints igual ao número de linhas de dados, sete números por linha, tempos crescentes.
• SigMF: core:datatype e core:version em global, arrays captures e annotations, core:sample_start em cada captura e um arquivo de dados com amostras inteiras.

Além da estrutura, um satélite exportado para CZML e para STK é comparado com o próprio estado do motor após a mesma redução de referencial, e concorda a 1 mm em posição (os arquivos trazem 0,1 mm): contra a própria saída GCRS do tipo de cenário ephemeris e contra uma propagação TEME para GCRS independente da constelação orbit-sgp4-gps, cada satélite datado pela sua própria época de TLE lida do texto do cenário. Duas verificações saem do motor: as posições CZML do primeiro satélite orbit-sgp4-gps concordam a 0,1 m (medido 2,3 cm) com o mesmo TLE propagado pelo pacote Python sgp4 e reduzido ao GCRS pelo ERFA (Essential Routines for Fundamental Astronomy, a implementação aberta da biblioteca SOFA da IAU), e as posições fixas à Terra dos satélites orbit-rinex são iguais às posições da efeméride transmitida da especificação de interface do Global Positioning System a 1 mm. As posições fixas à Terra da exportação jamming são comparadas com as posições que a execução de jamming avalia, a 5 mm. A rota GeoJSON faz ida e volta por um cenário de trilha, o par SigMF é relido para os mesmos bytes e toda exportação é determinística byte a byte.

Estas são verificações contra as especificações publicadas e contra o próprio motor. Os arquivos não foram carregados no CesiumJS, no Google Earth, no Ansys STK nem em uma ferramenta SDR como parte do conjunto de testes; portanto, a aceitação por uma versão específica dessas ferramentas não é testada aqui.

Intercâmbio de órbita, atitude e kernels (biblioteca, 0,36)#

Ao lado dos formatos --export, a 0,36 acrescentou leitores e gravadores de biblioteca para os arquivos padrão que as ferramentas de análise de missão trocam. Eles recebem e devolvem texto ou bytes e não tocam em nenhum arquivo. Cada um é uma linha VALIDATED da matriz de verificação, contra a implementação independente nomeada ali:

• Orbit Data Messages do CCSDS (kshana::odm, com kshana::ndm_xml para a forma XML): OPM, OMM e OCM em notação de palavra-chave e valor (KVN) e NDM/XML, segundo o CCSDS 502.0-B-3 (OPM e OMM nas versões 3,0 e 2,0, OCM 3,0). Verificadas nos dois sentidos contra o Orekit: o Orekit lê os arquivos do Kshana e o Kshana lê os do Orekit. Os achados que permanecem são fixados por testes.
• Attitude Data Messages do CCSDS (kshana::adm, com kshana::ndm_xml): AEM e APM segundo o CCSDS 504.0-B-2, em KVN e NDM/XML. Verificadas contra o Orekit do mesmo modo, e as rotações de registro contra as do Orekit.
• SPICE SPK (kshana::spk_writer): gravadores e leitores de segmentos SPK do NAIF dos tipos 9 e 13 (com a exportação de um OEM do CCSDS para um kernel SPK) e dos tipos 3 e 21 (polinômios de Chebyshev e linhas de diferenças estendidas), verificados contra os próprios leitores do toolkit NAIF SPICE, até a identidade byte a byte. O Kshana grava os segmentos a partir de registros que lhe são dados: não ajusta coeficientes de Chebyshev nem produz linhas de diferenças.

O importador e gravador de OEM do CCSDS, e o bloco de covariância do OEM, são mais antigos e estão descritos nas importações acima e na matriz.

Limitações#

• Somente os tipos de cenário da tabela abaixo exportam geometria. Os tipos de cenário cuja geometria é centrada na Lua, em Marte ou em outro corpo não são exportados: CZML, KML e GeoJSON descrevem posições em torno da Terra, e esta versão grava arquivos STK somente com CentralBody Earth, embora o próprio formato STK permita outros corpos centrais.
• constellation-design, earth-gnss-lunar e oem-interop têm geometria referenciada à Terra que esta versão não exporta; a tabela indica o motivo de cada um.
• O tipo de cenário gnss-ins percorre a sua trajetória em um plano tangente local plano; por isso, apenas a origem do plano é exportada, não a trajetória.
• As posições dos satélites fixas à Terra desprezam o UT1−UTC e o movimento polar (veja Referenciais e tempo); as alturas do KML são elipsoidais, não acima do nível médio do mar.
• As áreas de cobertura supõem propagação no espaço livre, um jammer no horizonte do receptor e uma Terra esférica para o círculo.

Todos os arquivos de cenário#

O que kshana <scenario> --export <format> faz com cada arquivo em scenarios/ (o manifesto da suíte não é um cenário e fica de fora). "yes" significa que o formato é gravado e passa pelo seu validador; caso contrário, o número aponta para o motivo. Gerada por cargo run --bin gen_validation_artifacts; tests/interop_formats.rs falha quando ela está desatualizada.

Por que um formato não se aplica:

1. os tipos de cenário contact-schedule e acm-link planejam contatos de downlink e codificação; exporte um cenário passes para o mesmo satélite e a mesma estação para ver a geometria
2. o SigMF contém amostras complexas em banda base, que apenas o tipo de cenário spectrum sintetiza
3. o tipo de cenário aocs simula a atitude em torno do centro de massa, sem órbita nem posição no solo, de modo que não há nada a posicionar na Terra
4. a entrada do cenário não traz posição horizontal (nem latitude e longitude, nem coordenadas centradas na Terra, nem elementos orbitais além, no máximo, de uma altitude), de modo que não há nada a posicionar na Terra
5. os tipos de cenário eo-radiometry e ascent-losses calculam orçamentos sem posição na Terra
6. uma efeméride do STK descreve a posição e a velocidade de um veículo em função do tempo; esta cena tem apenas pontos fixos ou trilhas sem tempo (um ponto fixo é uma Facility do STK, não uma efeméride)
7. nenhum cenário membro da campanha tem algo que este formato descreva; exporte um membro isoladamente para ver o seu motivo
8. o tipo de cenário leo-signal analisa projetos de sinal (espectros, rastreamento, aquisição, compatibilidade) sem posição de satélite ou de usuário; exporte o cenário leo-pass ou leo-pnt-chain que percorre o projeto
9. não exportado nesta versão: os tipos de cenário de posicionamento fundido colocam seus satélites em um referencial fixo à Terra relativo a uma época que nunca nomeiam, de modo que uma exportação com marcação de tempo teria de inventar a data de calendário (exporte, em vez disso, o cenário leo-pass ou leo-pnt-chain)
10. a geometria do tipo de cenário é centrada na Lua, em Marte ou em outro corpo do sistema solar; CZML, KML e GeoJSON descrevem posições na Terra ou em torno dela, e esta versão grava efemérides STK somente com CentralBody Earth
11. não exportado nesta versão: constellation-design coloca seus satélites em um referencial fixo ao corpo relativo a uma época que nunca nomeia, de modo que uma exportação com marcação de tempo teria de inventar a data de calendário
12. não exportado nesta versão: a constelação do Global Navigation Satellite System (GNSS) da Terra de earth-gnss-lunar é vista de um receptor à distância lunar, cuja trajetória o tipo de cenário não expõe como série temporal
13. não exportado nesta versão: o tipo de cenário entry-heating informa cargas e aquecimento de pico e não mantém nenhuma trilha no solo com marcação de tempo
14. o tipo de cenário gnss-ssv varre a disponibilidade e a intensidade do enlace para um usuário em uma camada ou em uma trajetória kepleriana; não tem uma única posição a colocar em um mapa
15. o cenário launch-window fornece a latitude do local de lançamento, mas não a longitude, de modo que o local não pode ser posicionado
16. não exportado nesta versão: a órbita verdadeira de leo-navmsg é uma referência de ajuste cujo ângulo de rotação da Terra na época é uma entrada (theta0_deg, padrão 0), não derivado da data de calendário, de modo que as suas posições fixas à Terra não estão ligadas a uma data
17. este cenário de espectro não tem bloco [iq], de modo que nenhuma amostra é sintetizada para gravar
18. não exportado nesta versão: oem-interop lê e grava uma Orbit Ephemeris Message do CCSDS (Consultative Committee for Space Data Systems), que já é, em si, o arquivo de intercâmbio de efemérides
19. o tipo de cenário optical-atmosphere calcula estatísticas de enlace para locais em terra, sem geometria com marcação de tempo a posicionar
20. o cenário varre outro cenário sobre uma grade; exporte o cenário varrido isoladamente
21. o tipo de cenário time-transfer-budget calcula um orçamento de enlace e estabilidades, sem geometria com marcação de tempo a posicionar