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