Exportações e importações de interoperabilidade

Uma execução escreve um documento de resultados, um gráfico e um relatório. --export escreve também a geometria do cenário, ou o seu sinal sintetizado, nos formatos que outras ferramentas já leem: um visualizador de globo, um mapa de secretária, um sistema de informação geográfica (SIG), 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 inclui uma marca temporal de geração, pelo que o mesmo cenário dá ficheiros idênticos byte a byte em todas as execuções.

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 ficheiros são escritos junto do cenário, com nomes como o do documento de resultados: jamming-demo.czml, jamming-demo.kml, jamming-demo.geojson, um jamming-demo.<object>.e por objeto em movimento (ou jamming-demo.e quando há um só) e o par l-band-waterfall-jamming.sigmf-meta / .sigmf-data. Com --study-name adotam o nome do estudo, tal como as outras saídas.

Um formato indicado explicitamente que não se aplique 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); recebem o texto do cenário e devolvem bytes, sem tocar em nenhum ficheiro, pelo que também funcionam na versão WebAssembly. O servidor Model Context Protocol (MCP) disponibiliza os mesmos três como as ferramentas export_interop, list_export_formats e import_route (ver 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 escrevem-na), src/sigmf.rs e src/spectrum.rs para o sinal. Testes: tests/interop_formats.rs.

Formatos#

O que cada ficheiro contém#

Todos os formatos geoespaciais são escritos a partir da mesma cena, pelo que não podem divergir quanto ao local onde está cada coisa. Uma cena tem até quatro tipos de objeto:

• Objetos em movimento — satélites e uma plataforma de utilizador quando se move — amostrados na grelha temporal do próprio cenário com os propagadores que a execução do tipo usa.
• Locais fixos — um recetor, uma estação terrestre, um jammer ou a origem de um referencial de navegação local.
• Trajetórias sem tempo — os pontos de passagem que um tipo de posicionamento, navegação e temporização (PNT) alternativo de terreno, gravidade ou combinado percorre. Estes tipos não têm eixo temporal, pelo que as trajetórias não o têm.
• Áreas de cobertura do jammer — para o tipo jamming, dois círculos em torno do jammer: o alcance à superfície dentro do qual um satélite no zénite (o mais forte) fica abaixo do limiar de seguimento, de modo que todos os satélites se perdem, e o alcance dentro do qual um satélite na máscara de elevação (o mais fraco) o faz, de modo que o seguimento começa a falhar. Ambos provêm das equações de ligação do próprio tipo (Kaplan e Hegarty, Understanding GPS/GNSS (Global Positioning System / Global Navigation Satellite Systems), 3.ª ed., §9,4) com o jammer no horizonte do recetor e perda em espaço livre, e o conjunto de testes verifica que a razão efetiva entre a portadora e a densidade de ruído em cada raio é igual ao limiar com 1e-6 dB. O círculo é desenhado numa 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 grelha temporal. Cada objeto em movimento é um pacote cujo position tem um epoch ISO 8601 (formato de data e hora da International Organization for Standardization) UTC (Coordinated Universal Time), 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 partilha. 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 trajetória sem tempo é uma polyline fixada ao solo. A description de cada pacote volta a indicar o referencial por 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>s, as áreas de cobertura <Polygon>s cujo anel é fechado e no sentido anti-horário, as trajetórias sem tempo <LineString>s. As coordenadas são longitude e latitude do World Geodetic System 1984 (WGS 84) em graus decimais e a altura em metros acima do elipsoide WGS 84, escritas 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, está dentro de cerca de ±110 m e não é aplicada. A descrição do documento di-lo.

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 a altura em metros acima do elipsoide. Um objeto em movimento é um LineString com uma propriedade times_utc que contém um tempo ISO 8601 por posição; uma trajetória que atravesse o meridiano de 180° é escrita como um MultiLineString cortado aí, como a RFC 7946 §3.1.9 pede (o ponto de passagem é interpolado, e times_utc lista então apenas as amostras originais). Os locais são Points, as áreas de cobertura Polygons com um anel exterior fechado no sentido anti-horário (§3.1.6), as trajetórias sem tempo LineStrings. Cada elemento tem uma propriedade units que indica a unidade de cada membro numérico.

STK .e#

Um ficheiro por objeto em movimento, dado que umas efemérides STK descrevem um veículo. O cabeçalho indica 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 apenas com locais fixos ou trajetórias sem tempo não escreve nenhum ficheiro .e: um ponto fixo é uma Facility do STK, não umas efemérides. Um identificador que não seja uma parte simples de nome de ficheiro (uma camada de constelação e um satélite, Pulsar inclined/S1-0163) é escrito com cada outro caráter como -, numerado se dois identificadores passarem a coincidir.

O tipo leo-pass e o tipo leo-pnt-chain (através da sua fase [pass]) exportam cada satélite em órbita terrestre baixa (LEO) e o utilizador a partir dos propagadores e da grelha temporal do próprio tipo. O tipo 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 e daí para o GCRS através do referencial true equator, mean equinox (TEME) em que o propagador Simplified General Perturbations 4 (SGP4) produz a saída, nesse instante, com o UT1 (Universal Time, o ângulo de rotação da Terra) tomado igual ao UTC e o movimento polar desprezado, como nas outras exportações. Os outros tipos LEO indicam porque um formato não se aplica (a tabela abaixo).

Campanhas#

Um campaign exporta cada cenário membro que tenha geometria como o seu próprio conjunto de ficheiros, com a etiqueta do membro inserida 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 de base da varredura (sweep), o cenário de Monte Carlo (monte-carlo) e cada membro composto (a sua etiqueta, com os valores partilhados a que se liga escritos). campaign-shared-jammer-sea-road.toml --export kml escreve 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 é escrito uma só vez, e os valores que uma campanha aplica em tempo de execução (transferências, valores de varredura, sementes) não constam do membro exportado. Um formato aplica-se a uma campanha quando se aplica a algum membro; caso contrário, o motivo é a nota 4 da tabela abaixo. Ver CAMPAIGNS.md.

SigMF#

O instantâneo [iq] do tipo spectrum — a banda L modelada desenhada como amostras complexas num instante — como um par .sigmf-meta / .sigmf-data, no tipo de dados que [iq] indica (cf32_le ou ci16_le). É a mesma gravação que a execução escreve e volta a ler para a sua própria verificação de consistência: os metadados exportados são iguais ao bloco iq.sigmf.meta do documento de resultados, e o ficheiro de dados tem o comprimento iq.sigmf.data_bytes. O escritor é src/sigmf.rs, o módulo que o tipo 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 rodados para o GCRS pela redução nutation::teme_to_gcrs (precessão IAU 2006 e nutação IAU 2000B, em que IAU é a International Astronomical Union), 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 para o referencial fixo à Terra é o ângulo sidéreo médio de Greenwich com o UT1 tomado igual ao UTC e sem aplicar o movimento polar — a mesma redução que a exportação SP3 (Standard Product 3) usa. Num raio de órbita GPS, a diferença UT1−UTC desprezada, de até 0,9 s, desloca a longitude de um satélite até cerca de 1,7 km; os locais em terra não são afetados, dado serem indicados em latitude e longitude.
• O tipo ephemeris é a exceção: a sua saída do motor já contém 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 estas são escritas sem alteração.
• Todas as horas são UTC. Os segundos intercalares não são modelados: um desvio que atravesse um segundo intercalar é contado como se cada dia tivesse 86 400 s, como contam as grelhas temporais do motor.
• A época de t = 0 é a que a execução do tipo usa, e cada ficheiro indica-a: o epoch do tipo orbit; quando está ausente, a época mais antiga que os dados dos próprios satélites contêm (uma época de conjunto de elementos de duas linhas (TLE), o tempo de referência de umas efemérides difundidas, o início de um ficheiro SP3), e 2000-01-01T00:00:00Z apenas quando nenhum satélite contém 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, pelo que, para esse cenário, as suas datas diferem das destes ficheiros. Sem epoch de cenário, cada satélite que contenha a sua própria época é rodado para os referenciais GCRS e fixo à Terra no seu próprio instante (a sua época mais t), dado ser essa a data a que pertence a sua posição TEME; quando as épocas dos satélites diferem, as marcas temporais partilhadas seguem a premissa do motor de que cada satélite começa em t = 0, e o ficheiro indica por quantas horas diferem. A época do elemento SGP4 das constelações Walker dos tipos jamming e gnss-sim (2018-06-12T00:00:00Z), que as suas execuções usam também para a rotação da Terra; a epoch do tipo passes; a epoch ou a época TLE do tipo ephemeris. O tipo 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 transportam as linhas de nome dos TLE.

Importações#

• Rota GeoJSON. --import-route <file> (biblioteca: interop::geojson::apply_route) lê o primeiro LineString de um documento GeoJSON — uma geometria isolada, um Feature ou um FeatureCollection — e escreve-o nas entradas de trajetória 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 percorrem start + i·step, pelo que uma rota é aceite quando é exatamente isso: os seus dois extremos (a contagem waypoints do cenário é mantida), ou três ou mais posições uniformemente espaçadas numa linha reta em latitude e longitude, com 1e-7 grau de tolerância (cerca de 1 cm). Qualquer outra rota é recusada e o erro indica a posição mais afastada da linha. Uma rota para um tipo sem entrada de trajetória é recusada com esse motivo. A longitude e a latitude têm o intervalo verificado, o que apanha um ficheiro com a latitude primeiro.
• Gravação SigMF. O bloco [recording] do tipo spectrum lê um par .sigmf-meta / .sigmf-data através de src/sigmf.rs e traça a sua estimativa de Welch junto do modelo (ver SPECTRUM.md). Ler ficheiros é uma funcionalidade da versão nativa; a versão WebAssembly recebe os bytes através 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 escritor:

• CZML: um vetor JSON cujo primeiro pacote é o pacote do documento com uma version; identificadores de pacote únicos; cada posição indica 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 espaço de nomes OGC KML 2,2 com um elemento 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; tuplos lon,lat[,alt] dentro do intervalo; valores altitudeMode válidos; styleUrls que se resolvem; um gx:Track com tantos <when> como <gx:coord>, e o espaço de nomes 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 no sentido anti-horário, nenhum segmento a atravessar o meridiano de 180°, nenhum membro crs, uma propriedade units em cada elemento.
• STK: a linha de versão stk.v., um bloco BEGIN Ephemeris / END Ephemeris com as palavras-chave obrigatórias, 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, vetores captures e annotations, core:sample_start em cada captura, e um ficheiro de dados de amostras inteiras.

Para além da estrutura, um satélite exportado para CZML e para STK é comparado com o estado do próprio motor após a mesma redução de referencial, e concorda com 1 mm na posição (os ficheiros contêm 0,1 mm): face à saída GCRS do próprio tipo ephemeris, e face a uma propagação independente de TEME para GCRS da constelação orbit-sgp4-gps, cada satélite datado pela sua própria época TLE lida do texto do cenário. Duas verificações saem do motor: as posições CZML do primeiro satélite de orbit-sgp4-gps concordam com 0,1 m (medido 2,3 cm) com o mesmo TLE propagado pelo pacote Python sgp4 e reduzido para o 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 de orbit-rinex são iguais às posições de efemérides difundidas da especificação de interface do Global Positioning System com 1 mm. As posições fixas à Terra da exportação jamming são comparadas com as posições que a execução de jamming pontua, com 5 mm. A rota GeoJSON faz ida e volta através de um cenário de trajetória, o par SigMF volta a ser lido com os mesmos bytes, e toda a exportação é determinista byte a byte.

Estas são verificações face às especificações publicadas e face ao próprio motor. Os ficheiros não foram carregados no CesiumJS, no Google Earth, no Ansys STK nem numa ferramenta SDR como parte do conjunto de testes, pelo que a aceitação por uma versão concreta dessas ferramentas não é testada aqui.

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

Para além dos formatos de --export, a 0,36 acrescentou leitores e escritores de biblioteca para os ficheiros normalizados que as ferramentas de análise de missão trocam. Recebem e devolvem texto ou bytes e não tocam em nenhum ficheiro. Cada um é uma linha VALIDATED da matriz de verificação, face à implementação independente aí indicada:

• CCSDS Orbit Data Messages (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 a CCSDS 502.0-B-3 (OPM e OMM versões 3,0 e 2,0, OCM 3,0). Verificados nos dois sentidos face ao Orekit: o Orekit lê os ficheiros do Kshana e o Kshana lê os do Orekit. As conclusões que permanecem estão fixadas por testes.
• CCSDS Attitude Data Messages (kshana::adm, com kshana::ndm_xml): AEM e APM segundo a CCSDS 504.0-B-2, em KVN e NDM/XML. Verificados face ao Orekit da mesma forma, e as rotações dos registos face às do Orekit.
• SPICE SPK (kshana::spk_writer): escritores e leitores de segmentos NAIF SPK dos tipos 9 e 13 (com a exportação de um CCSDS OEM para um kernel SPK) e dos tipos 3 e 21 (polinómios de Chebyshev e linhas de diferenças estendidas), verificados face aos leitores do próprio NAIF SPICE toolkit, até à identidade byte a byte. O Kshana escreve os segmentos a partir de registos que lhe são fornecidos: não ajusta coeficientes de Chebyshev nem produz linhas de diferenças.

O importador e escritor de CCSDS OEM, 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#

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

Todos os ficheiros de cenário#

O que kshana <scenario> --export <format> faz para cada ficheiro em scenarios/ (o manifesto do conjunto não é um cenário e fica de fora). "sim" significa que o formato é escrito e passa o seu validador; caso contrário, o número remete para o motivo. Gerado por cargo run --bin gen_validation_artifacts; tests/interop_formats.rs falha quando está desatualizado.

Porque é que um formato não se aplica:

1. os tipos contact-schedule e acm-link planeiam contactos de descida 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 spectrum sintetiza
3. o tipo aocs simula a atitude em torno do centro de massa sem órbita nem posição no solo, pelo que não há nada a colocar na Terra
4. a entrada do cenário não contém nenhuma posição horizontal (nem latitude e longitude, nem coordenadas centradas na Terra, nem elementos orbitais para além, no máximo, de uma altitude), pelo que não há nada a colocar na Terra
5. os tipos eo-radiometry e ascent-losses calculam balanços sem posição na Terra
6. umas efemérides STK descrevem a posição e a velocidade de um veículo em função do tempo; esta cena tem apenas pontos fixos ou trajetórias sem tempo (um ponto fixo é uma Facility do STK, não umas efemérides)
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 leo-signal analisa projetos de sinal (espetros, seguimento, aquisição, compatibilidade) sem posição de satélite nem de utilizador; exporte o cenário leo-pass ou leo-pnt-chain que percorre o projeto
9. não exportado nesta versão: os tipos de posicionamento fundido colocam os seus satélites num referencial fixo à Terra relativo a uma época que nunca nomeiam, pelo que uma exportação com marcas temporais teria de inventar a data de calendário (exporte antes o cenário leo-pass ou leo-pnt-chain)
10. a geometria do tipo está centrada na Lua, em Marte ou noutro corpo do sistema solar; CZML, KML e GeoJSON descrevem posições na Terra ou em torno dela, e esta versão escreve efemérides STK apenas com CentralBody Earth
11. não exportado nesta versão: constellation-design coloca os seus satélites num referencial fixo ao corpo relativo a uma época que nunca nomeia, pelo que uma exportação com marcas temporais teria de inventar a data de calendário
12. não exportado nesta versão: a constelação Global Navigation Satellite System (GNSS) da Terra de earth-gnss-lunar é vista a partir de um recetor à distância lunar, cuja trajetória o tipo não expõe como série temporal
13. não exportado nesta versão: o tipo entry-heating comunica cargas e aquecimentos máximos, e não guarda nenhuma projeção no solo com marcas temporais
14. o tipo gnss-ssv varre a disponibilidade e a intensidade da ligação para um utilizador numa camada ou numa trajetória kepleriana; não tem uma posição única para colocar num mapa
15. o cenário launch-window indica a latitude do local de lançamento mas não a longitude, pelo que o local não pode ser colocado
16. não exportado nesta versão: a órbita de referência de leo-navmsg é uma referência de ajuste cujo ângulo de rotação da Terra na época é uma entrada (theta0_deg, por predefinição 0), não derivado da data de calendário, pelo que as suas posições fixas à Terra não estão ligadas a uma data
17. este cenário de espetro não tem bloco [iq], pelo que não são sintetizadas amostras para gravar
18. não exportado nesta versão: oem-interop lê e escreve uma Orbit Ephemeris Message do CCSDS (Consultative Committee for Space Data Systems), que é ela própria o ficheiro de intercâmbio de efemérides
19. o tipo optical-atmosphere calcula estatísticas de ligação para locais em terra sem geometria com marcas temporais para colocar
20. o cenário varre outro cenário numa grelha; exporte o cenário varrido isoladamente
21. o tipo time-transfer-budget calcula um balanço de ligação e estabilidades, sem geometria com marcas temporais para colocar