S1005403_RisCC/doc/manual/08_riferimenti_tecnici.md

File: 08_riferimenti_tecnici.md

Capitolo 8: Riferimenti Tecnici

Questo capitolo finale fornisce dettagli tecnici sui formati dei file utilizzati dall'applicazione e un glossario dei termini chiave.

8.1. Formato dei File di Dati

L'applicazione utilizza il formato JSON (JavaScript Object Notation) per la persistenza di tutte le sue configurazioni e dati. Questo formato è stato scelto per la sua leggibilità umana e per la facilità di parsing in Python.

8.1.1. File di Impostazioni (settings.json)

Questo file contiene tutte le impostazioni globali dell'applicazione, esclusi gli scenari. È suddiviso in sezioni:

• general: Contiene le impostazioni generali della GUI (es. geometria della finestra) e la configurazione della connessione.
  • connection: Un oggetto che contiene le sotto-sezioni target e lru, ciascuna delle quali definisce il tipo di protocollo (sfp, tftp, serial) e i relativi parametri.
• debug: Contiene flag e impostazioni per le funzionalità di debug (es. save_tftp_scripts).

Esempio di Struttura:

{
    "general": {
        "scan_limit": 60,
        "max_range": 100,
        "geometry": "1200x900+100+100",
        "last_selected_scenario": "Scen_Esempio",
        "connection": {
            "target": {
                "type": "sfp",
                "sfp": {
                    "ip": "127.0.0.1",
                    "port": 60003,
                    "local_port": 60002,
                    "use_json_protocol": true,
                    "prediction_offset_ms": 20.0
                },
                "tftp": { ... },
                "serial": { ... }
            },
            "lru": { ... }
        }
    },
    "debug": {
        "enable_io_trace": false
    }
}

8.1.2. File degli Scenari (scenarios.json)

Le definizioni degli scenari dell'utente sono raccolte in un singolo file JSON chiamato scenarios.json, organizzato come un dizionario dove ogni chiave è il nome dello scenario.

• Ogni scenario contiene una lista di targets e i relativi parametri.
• Ogni target contiene il suo target_id, flag di stato (active, traceable, ecc.) e una lista trajectory (i waypoint).
• Ogni waypoint descrive una manovra con i suoi parametri specifici.

Il salvataggio e il ripristino degli scenari sono gestiti dal ConfigManager: le scritture su scenarios.json sono atomiche e vengono mantenuti backup rotanti (scenarios.json.bak1, scenarios.json.bak2, …) per garantire la resilienza dei dati. In assenza di scenarios.json viene effettuato un fallback a eventuali definizioni presenti in settings.json.

Esempio di struttura (semplificata):

{
    "Scen_Virata_Semplice": {
        "name": "Scen_Virata_Semplice",
        "targets": [
            {
                "target_id": 0,
                "active": true,
                "traceable": true,
                "use_spline": false,
                "trajectory": [ /* waypoint objects */ ]
            }
        ]
    }
}

8.1.3. File di Archivio Simulazione (YYYYMMDD_HHMMSS_NomeScenario.json)

Questi file, salvati nella cartella archive_simulations/, contengono un resoconto completo di una singola sessione di simulazione e i dati necessari per l'analisi posteriore.

• metadata: Informazioni sulla sessione (timestamp, durata, latenza stimata, versione del software, informazioni di sincronizzazione clock, ecc.).

  • Nota sui file di output delle metriche e del profiling: Durante la sessione il sistema può generare diversi file CSV utili per l'analisi:
    • <timestamp>_<scenario>.trail.csv — file "trail" delle posizioni (simulated/real) finalizzato e spostato nella cartella archive_simulations/.
    • <timestamp>_<scenario>.latency.csv — file delle latenze campionate e finalizzato nella cartella archive_simulations/.
    • <timestamp>_<scenario>.perf.csv — file delle performance (se enable_performance_profiling era attivo). Questo file, quando prodotto, viene scritto direttamente nella cartella archive_simulations/.

  Il JSON di archivio (<timestamp>_<scenario>.json) contiene i campi trail_file e latency_file che indicano i nomi dei file finali per trail e latency. Il file .perf.csv viene generato se erano presenti campioni di performance raccolti durante l'esecuzione; tuttavia la presenza di un riferimento esplicito a questo file nel blocco metadata può variare a seconda della versione. Se non troviate il riferimento nei metadati, verificate la cartella archive_simulations/ per il file *.perf.csv corrispondente.

• scenario_definition: Una copia dello scenario così com'era al momento dell'avvio.

• ownship_trajectory: Serie di snapshot dello stato dell'ownship durante la simulazione; contiene anche coordinate geografiche (lat, lon) quando disponibili.

• simulation_results: Dati per target_id con due insiemi principali:

  • simulated: La "ground truth" (serie di (timestamp, x, y, z) o con lat/lon se presente) generata dal SimulationEngine.
  • real: Gli stati (timestamp, x, y, z) ricevuti dal sistema radar per quel target.

Oltre al file JSON di archivio, la sessione può includere riferimenti a file CSV di performance e latenze (es. latency_<timestamp>.csv) generati se il flag di debug per l'IO-trace era abilitato. Nei metadati è presente un campo che indica i percorsi ai file CSV prodotti (ad es. latency_csv_path, perf_csv_path). Questo aiuta ad integrare le analisi numeriche esterne con i dati dell'archivio JSON.

8.2. Glossario

• Azimuth: L'angolo orizzontale di un target rispetto al Nord. Nell'applicazione, la convenzione è: 0° = Nord, angoli positivi in senso antiorario (CCW, verso Sinistra/Ovest), angoli negativi in senso orario (CW, verso Destra/Est).
• Heading (Prua): La direzione orizzontale in cui l'aereo (ownship o target) sta volando. Segue la stessa convenzione dell'azimuth.
• North-Up: Modalità di visualizzazione PPI in cui la griglia è fissa con il Nord (0°) in alto.
• Heading-Up: Modalità di visualizzazione PPI in cui la prua dell'ownship è sempre fissa verso l'alto e la griglia del mondo ruota.
• Ownship: La propria piattaforma (il nostro aereo) su cui il radar è installato.
• PPI (Plan Position Indicator): La classica visualizzazione radar circolare che mostra range e azimut dei target.
• Simulation Frame: Il sistema di coordinate cartesiane fisso, definito dallo stato dell'ownship a T=0, all'interno del quale si evolvono i target simulati.
• SFP (Simple Fragmentation Protocol): Protocollo di comunicazione su UDP usato per lo scambio di dati con il sistema radar.
• Target: Un oggetto (simulato o reale) tracciato dal sistema.
• Trajectory: La sequenza di manovre (waypoint) che definisce il percorso di un target simulato.
• Waypoint: Un singolo segmento di una traiettoria che definisce una manovra specifica (es. volo rettilineo, virata a 'g' costante).