112 lines
6.9 KiB
Markdown
112 lines
6.9 KiB
Markdown
### 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:*
|
|
```json
|
|
{
|
|
"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):*
|
|
```json
|
|
{
|
|
"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).
|
|
|
|
```
|