S1005403_RisCC/doc/manual/04_gestione_scenari_e_target.md

Capitolo 4: Gestione di Scenari e Target

Questo capitolo illustra il flusso di lavoro pratico per creare, modificare e gestire gli scenari di simulazione e i target che li compongono. Il cuore di questa attività si svolge attraverso l'Editor di Traiettoria e l'Editor dei Waypoint.

4.1. Creare, Salvare e Caricare uno Scenario

La gestione degli scenari avviene tramite il Pannello di Controllo Scenari (descritto nel Capitolo 3.3). Il flusso tipico è:

1. Creazione: Si preme il pulsante New... e si assegna un nome al nuovo scenario. L'applicazione crea uno scenario vuoto e lo seleziona.
2. Popolamento: Si aggiungono uno o più target utilizzando il pannello "Editing scenario" (vedi sezione successiva).
3. Salvataggio: Le modifiche vengono salvate periodicamente tramite il pulsante Save. Utilizzando Save As... è possibile creare una copia dello scenario corrente con un nuovo nome.
4. Caricamento: Utilizzando il menu a tendina, è possibile passare da uno scenario all'altro. L'applicazione caricherà la configurazione dal file scenarios.json (vedi nota sotto).

Gli scenari sono gestiti centralmente in un file JSON chiamato scenarios.json collocato nella directory principale dell'applicazione. La persistenza è gestita dal ConfigManager e avviene con scritture atomiche per evitare corruzioni in caso di interruzioni di processo.

Il ConfigManager mantiene inoltre backup rotanti (ad es. scenarios.json.bak1, scenarios.json.bak2, …) in modo da poter recuperare versioni precedenti in caso di necessità. Per compatibilità con versioni precedenti, se scenarios.json non è presente viene effettuato un fallback a eventuali definizioni contenute in settings.json.

4.2. L'Editor di Traiettoria (TrajectoryEditorWindow)

Questa finestra di dialogo è il principale strumento per definire il comportamento di un singolo target. Si apre quando si aggiunge un nuovo target o se ne modifica uno esistente.

(Placeholder per l'immagine)

Descrizione dell'Immagine: editor_traiettoria.png Qui ti aspetti uno screenshot della TrajectoryEditorWindow. Evidenzia le due aree principali:

1. Un riquadro a sinistra etichettato "Lista Waypoint e Controlli", che mostra la tabella con le manovre e i pulsanti "Add", "Edit", "Remove".
2. Un riquadro a destra etichettato "Anteprima Traiettoria e Controlli di Playback", che mostra il PPI con la traccia disegnata e i pulsanti Play/Pause/Stop.

---

La finestra è divisa in due sezioni:

• A sinistra: Lista dei Waypoint

  • Questa tabella elenca in sequenza tutte le manovre (waypoint) che compongono la traiettoria del target.
  • I pulsanti Add, Edit, Remove permettono di gestire la lista.
  • L'opzione Use Spline consente di interpolare i punti della traiettoria utilizzando una curva Catmull-Rom per un movimento più fluido (richiede almeno 4 waypoint).

• A destra: Anteprima della Traiettoria

  • Un PPI dedicato mostra un'anteprima statica del percorso completo del target.
  • I controlli di playback (Play, Pause, Stop, Speed) permettono di avviare una simulazione visiva della traiettoria per verificarne il comportamento dinamico prima di salvarla. Lo slider sottostante consente di navigare rapidamente lungo la timeline della simulazione.

Profilazione e parametri di target

L'editor dei target è stato esteso per supportare la profilazione per-target: in fase di creazione o modifica di un target è ora possibile definire, oltre ai parametri cinematici, un profilo di caratteristiche che sarà inviato al server e usato nelle viste di debug/analisi.

Campi aggiunti per ciascun target:

• Nome profilo: stringa identificativa del profilo del target (es. F-16_Profile, Bird_Small).
• Caratteristiche: campo libero strutturato (descrizione sintetica dei parametri ad alto livello: tipo piattaforma, firma radar attesa, note operative).
• RCS (radar cross section): valore numerico opzionale che rappresenta la sezione radar attesa del target; può essere inviato periodicamente nel payload JSON quando abilitato.
• Amplitude: campo numerico opzionale che descrive l'ampiezza del ritorno radar e può essere associato a ciascuna misura trasmessa.

Il profile (riferimento per nome) e le eventuali sovrascritture di rcs/amplitude vengono memorizzate nella definizione del target all'interno di scenarios.json. Le definizioni centralizzate dei profili (valori predefiniti di rcs, amplitude, descrizioni) sono invece conservate nel file target_types.json, gestito dal TargetTypeManager.

Quando il SimulationEngine è configurato per trasmettere il payload JSON, il SimulationController espande il riferimento al profilo applicando i valori predefiniti dal target_types.json e sovrascrivendo i campi con gli eventuali valori specifici del target o del waypoint; i valori risultanti (rcs, amplitude, ecc.) sono poi inseriti nel payload inviato al device sotto test.

Integrazione con l'Editor dei Waypoint

L'Editor dei Waypoint espone ora la possibilità di assegnare ad uno specifico waypoint modificatori sui valori di rcs e amplitude (es. cambi di firma radar durante una manovra). Questo permette di simulare variazioni dinamiche delle caratteristiche radar del target lungo la traiettoria.

Visualizzazione e analisi

I valori di rcs e amplitude sono visibili nella finestra di debug SFP Packet Inspector (scheda RIS / Polar / JSON) quando il server o il simulatore li invia; inoltre possono essere registrati nei CSV di debug se abilitato enable_io_trace.

Mockup TrajectoryEditor con pannello Profiling

(Placeholder: editor_traiettoria_profilazione.png)

Layout consigliato per la TrajectoryEditor:

• Sinistra: Lista Waypoint e Controlli (Add/Edit/Remove, ordine sequenza).
• Centro: Anteprima Traiettoria (PPI) con playback e slider timeline.
• Destra: Profiling / Characteristics Panel:
  • Profile Name (input)
  • Description (multi-line)
  • RCS (dBsm) (numeric)
  • Amplitude (numeric)
  • Override per Waypoint (checkbox + link al Waypoint Editor)
  • Assign To Target (dropdown)
  • Test Profile (button)

Esempio di payload JSON (snippet) che potrebbe essere inviato al server quando il protocollo JSON è abilitato:

{
    "CMD": "tgtset",
    "target_id": 3,
    "timestamp": 1699999999.123,
    "position": { "x_ft": 12345.6, "y_ft": -2345.1, "z_ft": 15000 },
    "velocity": { "vx_fps": 400.0, "vy_fps": 0.0 },
    "rcs": 1.25,
    "amplitude": 0.87,
    "profile": "F-16_Profile"
}

Nota: i nomi dei campi (rcs, amplitude, profile) sono coerenti con le chiavi aspettate dalle viste di debug e dall'archivio; possono variare a seconda dell'implementazione server, pertanto la schermata di Profiling offre un meccanismo di mapping e test per adattarsi a payload differenti.

4.3. L'Editor dei Waypoint e le Manovre (WaypointEditorWindow)

Questa è la finestra modale in cui si definiscono i parametri di una singola manovra. Il contenuto della finestra cambia dinamicamente in base al "Tipo di Manovra" selezionato.

(Placeholder per l'immagine)

Descrizione dell'Immagine: editor_waypoint_dynamic.png Qui ti aspetti uno screenshot della WaypointEditorWindow con la "Dynamic Maneuver" selezionata. Evidenzia le sezioni chiave:

1. Il menu a tendina "Maneuver Type".
2. La sezione "Turn Definition" con le opzioni "By G-Force" e "By Turn Rate".
3. I campi per le accelerazioni longitudinali e verticali.

---

4.3.1. Fly to Point

Questa manovra è obbligatoria come primo waypoint di ogni traiettoria, poiché definisce lo stato iniziale del target.

• Parametri Principali:
  • Target Range, Target Azimuth, Target Altitude: Definiscono la posizione iniziale del target in coordinate polari relative all'origine della simulazione.
  • Initial Velocity, Initial Heading: Definiscono il vettore velocità iniziale del target.
  • Duration to Point: Se usato come waypoint successivo al primo, questo parametro definisce il tempo che il target impiegherà per raggiungere le coordinate specificate. La velocità risultante viene calcolata e mostrata automaticamente.

4.3.2. Fly for Duration

Questa manovra istruisce il target a mantenere uno stato cinematico costante.

• Parametri Principali:
  • Duration: Per quanti secondi mantenere lo stato.
  • Constant Velocity, Constant Heading, Constant Altitude: I valori cinematici da mantenere.

4.3.3. Dynamic Maneuver

Questa è la manovra più complessa e potente, che permette di simulare virate, accelerazioni e cabrate/picchiate. Il movimento viene calcolato integrando le accelerazioni nel tempo.

• Parametri Principali:
  • Duration: La durata della manovra.
  • Maneuver Speed: La velocità di riferimento per il calcolo della virata.
  • Turn Definition: È possibile definire la virata in due modi equivalenti:
    1. By G-Force: Specificando l'accelerazione laterale in 'g'. Questo è il modo più comune in ambito aeronautico.
    2. By Turn Rate: Specificando la velocità angolare in gradi al secondo (°/s).
    • Soluzione Tecnica: I due campi sono sincronizzati. Modificandone uno, l'altro viene ricalcolato automaticamente in base alla velocità di manovra, usando la formula a = v * ω, dove a è l'accelerazione, v è la velocità e ω è la velocità angolare.
  • Longitudinal Accel (g): Accelerazione lungo l'asse di volo del target (per accelerare o decelerare).
  • Vertical Accel (g): Accelerazione lungo l'asse verticale del target (per cabrate o picchiate).

La combinazione di questi waypoint permette di costruire traiettorie estremamente varie e realistiche, adatte a coprire un'ampia gamma di scenari di test.