# Capitolo 3: Creare e Gestire uno Scenario

Uno "scenario" è il file che contiene tutti i target e le loro traiettorie per una specifica sessione di test. Questa guida ti mostrerà come creare e modificare gli scenari.

## 3.1. Gestire i File di Scenario

Tutti i controlli per la gestione dei file si trovano nel **Pannello di Controllo Scenari** in alto a destra.

> Nota importante: a partire dalle ultime versioni, gli scenari non sono più salvati come singoli file sparsi nella cartella del progetto. Tutti gli scenari sono conservati in un file centrale chiamato `scenarios.json` nella root del progetto. Le operazioni di salvataggio sono atomiche e il sistema mantiene più backup rotativi (es. `scenarios.json.bak1`, `scenarios.json.bak2`) per prevenire perdita di dati in caso di interruzioni.

Se necessario, l'interfaccia offre la possibilità di esportare un singolo scenario in un file JSON separato (funzione `Export`) e di importare scenari da file esterni (`Import`). Queste funzioni creano o leggono file JSON di scenario standalone ma non cambiano il comportamento predefinito di `Save` che aggiorna `scenarios.json`.

![Pannello di Controllo Scenari](<percorso/relativo/a/pannello_scenari.png>)
*(Nota: Qui puoi usare un crop dello screenshot principale che mostra solo il pannello "Scenario Controls")*

*   **Per caricare uno scenario esistente:** Selezionalo dal menu a tendina.
*   **Per creare un nuovo scenario:**
    1.  Clicca su `New...`.
    2.  Inserisci un nome per il tuo nuovo scenario e clicca `OK`.
*   **Per salvare il tuo lavoro:**
    *   Clicca `Save` per salvare le modifiche allo scenario corrente.
    *   Clicca `Save As...` per salvare lo scenario con un nuovo nome.
*   **Per cancellare uno scenario:**
    1.  Carica lo scenario che vuoi cancellare usando il menu a tendina.
    2.  Clicca `Delete` e conferma l'operazione.

## 3.4. Esportare / Importare scenari

Se devi condividere uno scenario con un collega o mantenerne una copia separata, usa i comandi `Export` e `Import` dal `Pannello di Controllo Scenari`:

- **Export:** salva il singolo scenario selezionato in un file JSON indipendente.
- **Import:** carica un file JSON di scenario esterno e lo aggiunge (o lo sovrascrive) all'elenco interno gestito in `scenarios.json`.

Questi file esportati seguono la stessa struttura JSON usata internamente (target list, traiettorie, parametri di profilazione per target quando presenti).

## 3.5. Profili Target (Target Profiles)

L'applicazione supporta profili target riutilizzabili che permettono di definire proprietà fisiche e di presentazione di un target (es. `rcs`, `amplitude`, `description`, `profile_name`) e di applicarli ai target nello scenario. Questo semplifica la gestione di insiemi di target con caratteristiche simili e garantisce coerenza nell'invio dei payload al server.

### Dove si gestiscono

- I profili possono essere creati e modificati dall'**Editor di Traiettoria** quando si crea o si modifica un target:
    - Nella scheda `Profile` dell'editor è possibile: creare un nuovo profilo, selezionarne uno esistente o applicare un profilo al target corrente.
    - I campi tipici sono: `Profile Name`, `Description`, `RCS (m^2)`, `Amplitude` (unità interne), e campi opzionali per metadata.

In alternativa, le definizioni dei profili sono persistite centralmente nel file `target_types.json` (vedi `target_simulator/utils/target_type_manager.py`). Il gestore dei profili (`TargetTypeManager`) mantiene una libreria riutilizzabile di profili (es. `F-16`, `B-747`) che possono essere assegnati ai target per nome.

### Come si usano nelle traiettorie e nei payload

- Quando un target è associato a un `profile` (riferito per nome), il `SimulationController` usa i valori del profilo come predefiniti durante la generazione dei payload inviati al server. È comunque possibile sovrascrivere singoli campi (ad es. `rcs` o `amplitude`) a livello di target o di singolo waypoint; tali sovrascritture sono memorizzate nella definizione del target dentro `scenarios.json`.
- Al momento dell'invio dello scenario (`Start Live` o `Send Init`), il `SimulationController` espande il riferimento al profilo applicando i valori ereditati e le eventuali sovrascritture, e include i campi di profilazione pertinenti nei payload JSON inviati al server (es. `tgtinit`/`tgtset`).

### Esempio: profili in `target_types.json` e target che li referenzia

Esempio di estratto da `target_types.json` (file centralizzato dei profili):

```json
{
    "F-16": { "rcs": 5.0, "amplitude": 100.0, "notes": "Fighter jet" },
    "B-747": { "rcs": 100.0, "amplitude": 500.0 }
}
```

Esempio di target nello scenario che fa riferimento a un profilo per nome (memorizzato in `scenarios.json` come parte della definizione del target):

```json
{
    "id": 101,
    "label": "TGT-101",
    "profile": "F-16",
    "rcs": 0.9,            // valore sovrascritto a livello target (opzionale)
    "trajectory": [ /* waypoints... */ ]
}
```

Nel caso precedente il sistema applicherà i valori dal profilo `F-16` al target `TGT-101` ma userà `rcs=0.9` perché il valore è stato sovrascritto per quel target.

### Consigli pratici

- Definire profili standard (es. `small_plane`, `helicopter`, `drone`, `ship`) e riutilizzarli per i target simili.
- Usare la funzione `Export` per condividere profili con colleghi o per conservarne una copia di backup.
- Quando si sospetta un problema di correlazione tra target simulati e tracciati, verificare che il `rcs` e l'`amplitude` applicati siano quelli attesi (controllare la scheda `Profile` nell'Editor di Traiettoria e il payload JSON inviato dal `SfpDebugWindow`).

## 3.2. Aggiungere e Modificare un Target

Una volta caricato o creato uno scenario, puoi popolarlo con i target nella scheda **"Editing scenario"**.

1.  **Aggiungere un Target:**
    *   Clicca sul pulsante `Add` sotto la tabella "Target List".
    *   Si aprirà l'**Editor di Traiettoria**.

2.  **Modificare un Target:**
    *   Seleziona un target dalla lista cliccandoci sopra.
    *   Clicca sul pulsante `Edit Trajectory...` (oppure fai semplicemente doppio click sulla riga del target).
    *   Si aprirà l'**Editor di Traiettoria** con i dati del target selezionato.

3.  **Rimuovere un Target:**
    *   Seleziona un target dalla lista.
    *   Clicca sul pulsante `Remove`.

## 3.3. Definire una Traiettoria (Waypoint e Manovre)

L'**Editor di Traiettoria** è la finestra dove costruisci il percorso di un target, un pezzo alla volta. Ogni "pezzo" è chiamato **Waypoint** o manovra.

![Editor di Traiettoria](<percorso/relativo/a/editor_traiettoria.png>)
*(Nota: Usa lo screenshot `editor_traiettoria.png` definito nel manuale tecnico)*

### Flusso di Lavoro

1.  **Punto di Partenza (Obbligatorio):** Il primo waypoint di ogni target **deve** essere di tipo `Fly to Point`. Questo definisce dove il target appare all'inizio della simulazione. Quando aggiungi il primo waypoint, la finestra si aprirà già configurata per questo.
    *   Imposta `Range`, `Azimuth` e `Altitude` per la posizione iniziale.
    *   Imposta `Initial Velocity` e `Initial Heading` per definire la sua rotta e velocità di partenza.

2.  **Aggiungere Manovre Successive:**
    *   Clicca sul pulsante `Add` all'interno dell'Editor di Traiettoria.
    *   Si aprirà l'**Editor dei Waypoint**. Seleziona il `Maneuver Type` che desideri.

### Tipi di Manovra Comuni

![Editor dei Waypoint](<percorso/relativo/a/editor_waypoint_dynamic.png>)
*(Nota: Usa lo screenshot `editor_waypoint_dynamic.png` definito nel manuale tecnico)*

*   **`Fly for Duration` (Volo Rettilineo):**
    *   Usa questa manovra per far volare il target in linea retta.
    *   **Imposta:**
        *   `Duration`: Per quanti secondi deve mantenere la rotta.
        *   `Constant Velocity`: La nuova velocità in nodi.
        *   `Constant Heading`: La nuova direzione in gradi.

*   **`Dynamic Maneuver` (Virata o Accelerazione):**
    *   Usa questa manovra per simulare virate o cambi di velocità.
    *   **Imposta:**
        *   `Duration`: La durata della manovra.
        *   `Turn Definition`: Scegli come definire la virata:
            *   **By G-Force:** Inserisci l'accelerazione laterale in 'g' (es. `2.0` per una virata a 2g). **Questo è il metodo più comune.**
            *   **By Turn Rate:** Inserisci la velocità di virata in gradi al secondo.
        *   `Direction`: Scegli se la virata è a destra (`Right`) o a sinistra (`Left`).
        *   `Longitudinal Accel`: Inserisci un valore positivo per accelerare, negativo per decelerare.

### Anteprima della Traiettoria

Mentre costruisci la traiettoria, il display PPI sulla destra ti mostrerà un'anteprima del percorso. Usa i pulsanti `Play`, `Pause` e `Stop` per vedere una simulazione animata del movimento del target e verificare che si comporti come previsto.

Una volta che sei soddisfatto della traiettoria, clicca `OK` nell'Editor di Traiettoria per salvare il target nello scenario. Ricorda di cliccare `Save` nella finestra principale per salvare le modifiche allo scenario su file.