# Capitolo 2: Concetti Fondamentali

Questo capitolo descrive i concetti teorici e le convenzioni di base che governano il funzionamento del Radar Target Simulator. Una comprensione solida di questi principi è essenziale per utilizzare l'applicazione in modo efficace e per interpretarne correttamente i risultati.

## 2.1. Scenario, Target e Traiettoria

L'applicazione organizza i dati secondo una struttura gerarchica semplice ma potente:

*   **Scenario:** È il contenitore di livello più alto. Rappresenta una singola sessione di test e contiene una collezione di uno o più target. Ogni scenario ha un nome univoco che permette di salvarlo e ricaricarlo.

*   **Target:** Rappresenta un singolo oggetto (es. un aereo, un missile) che il simulatore deve muovere. Ogni target è definito da:
    *   Un **ID** numerico univoco.
    *   Una serie di **attributi di stato** (attivo, tracciabile).
    *   Una **traiettoria** che ne descrive il movimento nel tempo.

*   **Traiettoria:** È una sequenza ordinata di `Waypoint` che definisce il percorso di un target. La traiettoria non è un semplice elenco di coordinate, ma una serie di istruzioni di manovra.

*   **Waypoint (o Punto di Manovra):** È il blocco costruttivo fondamentale di una traiettoria. Ogni waypoint descrive un segmento di volo o una manovra specifica. L'applicazione supporta diversi tipi di manovra (`ManeuverType`), tra cui:
    *   **Fly to Point:** Usato tipicamente come punto di partenza, definisce una posizione iniziale in coordinate polari (range, azimut, altitudine) e uno stato cinematico iniziale (velocità, heading).
    *   **Fly for Duration:** Istruisce il target a mantenere una velocità, un heading e un'altitudine costanti per una durata di tempo specificata.
    *   **Dynamic Maneuver:** Permette di simulare manovre complesse applicando accelerazioni (longitudinali, laterali e verticali) per una data durata.

Quando una simulazione viene avviata, il `SimulationEngine` calcola in anticipo il percorso completo (un elenco di punti `(t, x, y, z)`) per ogni target, interpolando o campionando le manovre definite dai waypoint. Questo percorso pre-calcolato diventa la "ground truth" per la durata della simulazione.

## 2.2. Il Sistema di Coordinate

La gestione corretta dei sistemi di coordinate è l'aspetto tecnicamente più critico dell'applicazione. È fondamentale per garantire che il movimento simulato sia realistico e indipendente dai movimenti dell'ownship (la nostra piattaforma).

### 2.2.1. Il Problema: Un Sistema di Riferimento Relativo

Un approccio ingenuo potrebbe calcolare la posizione dei target sempre in modo relativo alla posizione *corrente* dell'ownship. Questo porterebbe a un comportamento irrealistico: se l'ownship virasse a destra, l'intera scena simulata ruoterebbe solidalmente con esso, come se i target fossero "incollati" a un sistema di riferimento centrato sull'aereo. Questo è fisicamente scorretto, poiché le traiettorie dei target nel mondo reale sono indipendenti dai movimenti dell'osservatore.

### 2.2.2. La Soluzione Adottata: Il "Simulation Frame"

Per risolvere questo problema, abbiamo introdotto il concetto di un **sistema di riferimento fisso per la simulazione**, chiamato "Simulation Frame".

1.  **Snapshot a T=0:** Nel momento esatto in cui l'utente avvia la simulazione, il `SimulationController` cattura lo stato corrente dell'ownship (posizione `(x, y)` e `heading` assoluti nel mondo) fornito dal sistema reale.
2.  **Origine Fissa:** Questo snapshot viene salvato nello `SimulationStateHub` come **"origine della simulazione"**. Questa origine diventa un punto di riferimento immutabile per tutta la durata della sessione.
3.  **Calcolo delle Traiettorie:** Il `SimulationEngine` calcola e aggiorna le posizioni di tutti i target simulati *all'interno di questo Simulation Frame*. Per convenzione, l'origine `(0,0)` del Simulation Frame corrisponde alla posizione dell'ownship a T=0, e il suo asse Y è allineato con l'heading dell'ownship a T=0.
4.  **Trasformazione per la Visualizzazione:** Per disegnare i target sulla PPI, il `ppi_adapter` esegue una trasformazione in tempo reale:
    a.  Prende la posizione di un target nel Simulation Frame.
    b.  La **ruota** e la **trasla** utilizzando i dati dell'origine della simulazione per convertirla in una posizione assoluta nel "mondo".
    c.  Calcola la sua posizione finale **relativa** alla posizione *corrente* dell'ownship per la corretta visualizzazione sulla PPI.

Nota sulla convenzione degli assi: l'allineamento degli assi cartesiani e la convenzione di segno per azimuth/heading seguono la convenzione del server (0° = Nord, angoli positivi in senso antiorario). Eventuali aggiustamenti (ad es. inversione di segno in ingresso) vengono normalizzati dal `ppi_adapter` in fase di trasformazione.

Questo approccio garantisce che le traiettorie simulate si evolvano in un sistema di coordinate stabile e inerziale, mentre l'ownship è libero di muoversi nel mondo come dettato dai dati di navigazione reali.

### 2.2.3. Dati Simulati vs. Dati Reali

Lo `SimulationStateHub` mantiene due storie separate per ogni target ID:
*   **Dati Simulati:** La "ground truth" generata dal `SimulationEngine`, espressa nel Simulation Frame.
*   **Dati Reali:** Le posizioni dei target ricevute dal sistema radar, espresse in coordinate assolute del mondo.

Questa separazione è ciò che permette all'applicazione di confrontare i due flussi di dati e calcolare le metriche di errore di tracciamento.

## 2.3. Modalità di Visualizzazione PPI

Il PPI Display supporta due modalità di visualizzazione standard per orientare l'operatore.

*(Placeholder per l'immagine)*

**Descrizione dell'Immagine:** `modalita_ppi.png`
*Qui ti aspetti di vedere due cerchi PPI affiancati che mostrano la stessa situazione tattica. Per esempio, l'ownship ha un heading di +45° (Nord-Est) e un target si trova a Nord.*
*   **PPI a Sinistra (North-Up):**
    *   La griglia ha lo 0° in alto.
    *   L'icona dell'ownship al centro è ruotata di 45° verso destra.
    *   Il settore di scansione è anch'esso ruotato di 45° a destra.
    *   Il target è disegnato in alto, sulla linea dei 0°.
*   **PPI a Destra (Heading-Up):**
    *   L'icona dell'ownship e il settore di scansione sono fissi e puntati in alto.
    *   La griglia è ruotata di -45° (in senso orario). La tacca dei 0° (Nord) si trova in basso a destra.
    *   Il target è disegnato in alto a sinistra, a un angolo di -45° rispetto alla linea di fede superiore.

---

### 2.3.1. North-Up (Nord in Alto)

Questa è la modalità "mappa". L'orientamento del display è fisso, con la linea dei 0° che punta sempre verso il Nord geografico.

*   **Griglia PPI:** Fissa, con 0° in alto.
*   **Elementi dell'Ownship (Icona, Settore Radar):** Ruotano per riflettere l'heading corrente dell'aereo. Questo permette all'operatore di vedere la propria orientazione rispetto al mondo esterno.
*   **Mondo Esterno (Target, Tracce):** Disegnato a coordinate assolute sulla mappa fissa.

### 2.3.2. Heading-Up (Prua in Alto)

Questa è la modalità "vista dal cockpit". L'orientamento del display è dinamico e allineato con la prua dell'aereo. La linea dei 0° del display rappresenta sempre la direzione in cui l'aereo sta andando.

*   **Griglia PPI:** Ruota in senso opposto alle virate dell'aereo per mantenere l'heading allineato in alto.
*   **Elementi dell'Ownship (Icona, Settore Radar):** Fissi, puntati verso l'alto.
*   **Mondo Esterno (Target, Tracce):** Ruota solidalmente con la griglia.

La corretta implementazione di queste due modalità è fondamentale per fornire all'operatore una consapevolezza situazionale accurata.