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)

Questo file contiene le definizioni di tutti gli scenari creati dall'utente. È un dizionario JSON in cui ogni chiave è il nome di uno scenario.

• Ogni scenario contiene a sua volta una lista di targets.
• Ogni target contiene il suo target_id e una lista di trajectory (i waypoint).
• Ogni waypoint è un oggetto che descrive una manovra con i suoi parametri specifici.

Esempio di Struttura:```json { "Scen_Virata_Semplice": { "name": "Scen_Virata_Semplice", "targets": [ { "target_id": 0, "active": true, "traceable": true, "use_spline": false, "trajectory": [ { "maneuver_type": "Fly to Point", "target_range_nm": 50.0, "target_azimuth_deg": 45.0, "target_altitude_ft": 20000.0, "target_velocity_fps": 843.9, "target_heading_deg": 270.0 }, { "maneuver_type": "Dynamic Maneuver", "duration_s": 20.0, "lateral_acceleration_g": 2.0, "turn_direction": "Right" } ] } ] } }

### 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.

*   **`metadata`**: Informazioni sulla sessione (timestamp, durata, latenza stimata, etc.).
*   **`scenario_definition`**: Una copia dello scenario così com'era al momento dell'avvio.
*   **`ownship_trajectory`**: Una serie di snapshot dello stato dell'ownship durante la simulazione.
*   **`simulation_results`**: Il cuore dei dati. Un dizionario per `target_id` che contiene due liste:
    *   **`simulated`**: La "ground truth" di tutti gli stati `(timestamp, x, y, z)` generati dal `SimulationEngine`.
    *   **`real`**: Tutti gli stati `(timestamp, x, y, z)` ricevuti dal sistema radar per quel target.

## 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).