## **Manuale Utente - Radar Data Reader & Processor (v2.0)**

### **1. Introduzione: Un Flusso di Lavoro Completo**

Benvenuto nel Radar Data Reader & Processor. Questo strumento è stato progettato per guidarti in un flusso di lavoro completo per l'analisi dei dati radar, trasformando le registrazioni grezze di un intero volo in dati strutturati e pronti per l'analisi.

L'applicazione è organizzata per seguire un percorso logico in tre fasi principali:

1.  **Fase 1: Analisi del Volo (Flight Analysis)**: Si parte da un'intera cartella di file `.rec` per identificare e riassumere automaticamente i segmenti operativi significativi del volo.
2.  **Fase 2: Esportazione dei Segmenti**: Una volta identificati i segmenti di interesse, questa fase li estrae, creando i dati grezzi (`.out`, video, etc.) per ciascuno di essi.
3.  **Fase 3: Processamento dei Dati (Data Processing)**: L'ultimo passo consiste nell'analizzare in blocco i segmenti esportati per estrarre i valori numerici desiderati in formati standard (CSV, JSON) utilizzando profili personalizzati.

Questo manuale ti guiderà attraverso ogni fase.

#### **2. Configurazione Iniziale (Passo Obbligatorio)**

Prima di utilizzare l'applicazione, è **fondamentale** indicare dove si trova l'eseguibile `g_reconvert.exe`, da cui l'applicazione dipende.

1.  Avvia l'applicazione.
2.  Vai alla scheda **"4. REC to OUT Converter"**.
3.  Clicca sul pulsante **"g_reconverter Advanced Config..."**.
4.  Nella finestra che si apre, il primo campo è **"Executable Path"**. Clicca su **"Browse..."** e seleziona la posizione esatta del tuo file `g_reconvert.exe`.
5.  Clicca su **"Save & Close"**. La configurazione verrà salvata per gli usi futuri.

**Senza questo passaggio, le funzioni principali dell'applicazione non funzioneranno.**

---

# **Guida al Flusso di Lavoro Principale**

Questa sezione descrive il caso d'uso più comune e potente dell'applicazione.

## **3. Fase 1 & 2: Analisi del Volo ed Esportazione Segmenti (Tab `1. Flight Analyzer`)**

Questa è la tua centrale di comando per iniziare una nuova analisi. Qui identificherai ed esporterai i momenti salienti del volo.

**Obiettivo**: Trasformare una cartella piena di file `.rec` in un elenco di segmenti operativi e generare i dati grezzi per quelli che ti interessano.

**Passaggi:**
1.  **Seleziona Cartella del Volo**: Clicca su **"Browse..."** e seleziona la cartella contenente la sequenza completa di file `.rec`.
2.  **Dai un Nome al Volo**: Inserisci un nome unico per il volo (es. `VoloTest_25Maggio`). Questo nome verrà usato per creare una cartella di lavoro dedicata (`flight_workspace/VoloTest_25Maggio`) dove verranno salvati tutti i risultati.
3.  **Avvia Analisi Preliminare**: Clicca su **"Start Flight Analysis"**. L'applicazione eseguirà `g_reconvert.exe` in background per analizzare l'intero volo, generare un report testuale e creare un video completo della missione. Questo processo può richiedere diversi minuti.
4.  **Visualizza i Segmenti**: Al termine, la tabella "Flight Summary & Segments" si popolerà con un riepilogo di tutti i segmenti operativi trovati (cambi di modalità, scala, etc.).
5.  **Esporta i Segmenti di Interesse**:
    *   Seleziona dalla tabella uno o più segmenti che desideri analizzare in dettaglio.
    *   Clicca su **"Export Selected Segment(s)"**.
    *   L'applicazione creerà una sottocartella per ogni segmento selezionato all'interno della cartella di lavoro del volo. Ogni sottocartella conterrà un file `.out` con i dati grezzi di quel segmento e altri file ausiliari (video del segmento, traccia GPS, etc.).

**Risultato di questa fase**: Hai una cartella di lavoro ben organizzata, con un sommario del volo e sottocartelle contenenti i dati grezzi pronti per l'estrazione.

#### **4. Fase 3: Estrazione Dati dai Segmenti (Tab `2. Segment Processor`)**

Ora che hai i segmenti esportati, è il momento di estrarre i dati numerici che ti servono.

**Obiettivo**: Processare in blocco i file `.out` dei segmenti esportati per generare file CSV o JSON basati su profili personalizzati.

**Passaggi:**
1.  **Carica Segmenti Esportati**: Clicca su **"Load Exported Segments from Current Flight"**. La tabella si popolerà con i segmenti trovati nella cartella di lavoro del volo attuale.
    *   I segmenti pronti per l'analisi avranno lo stato **"Ready"** (in verde).
    *   I segmenti che hai visto nella tab precedente ma che non hai ancora esportato avranno lo stato **"Not Exported"** (in grigio) e non saranno selezionabili.
2.  **Configura l'Output**:
    *   **Output Directory**: Scegli una cartella di destinazione **dedicata** per i file di dati finali (es. `C:/Analisi_Finali/VoloTest_25Maggio`).
    *   **Profili di Esportazione**: Seleziona dai menu a tendina i profili CSV e/o JSON che definiscono quali dati estrarre. (Vedi sezione 6 per la creazione dei profili).
    *   **Struttura Cartelle**: Spunta **"Create a separate folder for each segment's analysis"** se vuoi che ogni file di analisi (es. `segmento_A.csv`) venga salvato in una sua sottocartella. Lascialo deselezionato per avere tutti i file di analisi nella stessa directory.
3.  **Seleziona e Avvia**:
    *   Seleziona dalla tabella i segmenti con stato "Ready" che vuoi processare.
    *   Clicca su **"Process Selected Segments"**.
4.  **Visualizza i Risultati**: L'applicazione processerà ogni segmento, generando i file CSV/JSON nella cartella di output che hai specificato. Puoi monitorare l'avanzamento dalla barra di progresso e dalla console.

**Risultato di questa fase**: Hai ottenuto i file di dati puliti e strutturati, pronti per essere importati in MATLAB, Python, Excel o altri strumenti di analisi.

---

### **Funzionalità di Supporto e Avanzate**

#### **5. Analisi di un Singolo File `.out` (Tab `3. Single OUT Processor`)**

Usa questa tab quando hai un singolo file `.out` che vuoi analizzare rapidamente, al di fuori di un'analisi di volo completa. Il funzionamento è identico alla Fase 3, ma applicato a un solo file.

#### **6. Creare e Gestire i Profili di Esportazione**

L'Editor dei Profili (`File -> Manage Export Profiles...`) è il cuore della personalizzazione dell'estrazione dati.

*   **Pannello Sinistro (Profiles)**: Crea nuovi profili (es. "Analisi_Termica", "Tracking_Performance") o elimina quelli vecchi.
*   **Pannello Centrale (Available Fields)**: Esplora l'albero di tutte le strutture dati e i campi che l'applicazione è in grado di leggere. I campi marcati con `(Enum)` possono essere tradotti in testo leggibile. Seleziona un campo e clicca **`>>`** per aggiungerlo al profilo corrente.
*   **Pannello Destro (Selected Fields for Profile)**:
    *   Visualizza e riordina i campi del profilo selezionato con i bottoni **Up/Down**.
    *   **Colonna "Translate"**: Questa è una funzione potente. Cliccando sulla casella, puoi decidere se un campo `(Enum)` debba essere esportato come il suo valore numerico grezzo (es. `15`) o come la sua rappresentazione testuale (es. `STT_MASTER_MODE`), rendendo i tuoi file CSV immediatamente leggibili.

#### **7. Conversione Manuale (Tab `4. REC to OUT Converter`)**

Questa tab è un semplice frontend per `g_reconvert.exe`, utile per conversioni rapide o per testare specifiche combinazioni di parametri senza passare per l'intero workflow di analisi.

#### **8. Troubleshooting e Domande Frequenti (FAQ)**

*   **D: L'applicazione si avvia ma nessuna funzione sembra partire. Cosa devo fare?**
    *   **R**: Quasi certamente non hai configurato il percorso di `g_reconvert.exe`. Segui attentamente i passaggi della sezione "Configurazione Iniziale".

*   **D: Perché l'esportazione di un segmento sembra non funzionare o crashare?**
    *   **R**: `g_reconvert.exe` può essere sensibile ai parametri passati. La logica di esportazione attuale si basa sull'indicazione del numero di file `.rec` da processare. Se il problema persiste, assicurati che i file `.rec` non siano corrotti.

*   **D: Quando avvio un'analisi, si apre una seconda finestra della mia applicazione. È normale?**
    *   **R**: Questo è un comportamento noto quando si esegue l'applicazione da un eseguibile creato con PyInstaller. Sebbene il codice attuale dovrebbe prevenire questo problema tramite `multiprocessing.freeze_support()`, se dovesse verificarsi, è un'indicazione che il nuovo processo non è stato gestito correttamente.

*   **D: Posso aggiungere un campo dati che non vedo nell'Editor dei Profili?**
    *   **R**: Sì, ma richiede una modifica al codice sorgente. Dovrai definire la nuova struttura dati C-style nel package `radar_data_reader/core/structures` e insegnare al `struct_parser.py` come leggerla dal file binario.