SXXXXXXX_RadarDataReader/doc/Italian-manual.md

Italiano

Manuale Utente - Radar Data Reader & Processor

1. Introduzione

Questo manuale fornisce una guida completa all'utilizzo dell'applicazione Radar Data Reader & Processor. L'applicazione è progettata per risolvere due problemi principali:

1. Fornire un'interfaccia controllata e user-friendly per eseguire l'utility a riga di comando g_reconvert.exe.
2. Offrire un potente strumento per ispezionare, analizzare ed estrarre dati dai file binari .out generati.

2. Requisiti di Sistema

• Un ambiente Python 3 installato.
• Le librerie Python richieste (principalmente numpy).
• L'eseguibile g_reconvert.exe deve essere accessibile dal sistema. L'applicazione è un wrapper e dipende da questo file per la funzionalità di conversione.

3. Configurazione Iniziale

Al primo avvio, l'applicazione crea un file config/config.json nella sua directory. È fondamentale configurare correttamente l'applicazione prima dell'uso.

1. Avvia l'applicazione.
2. Vai alla scheda "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".

Senza questo passaggio, la funzione di conversione non funzionerà.

4. Guida all'Interfaccia

L'interfaccia principale è composta da:

• Menu Bar: Contiene opzioni per gestire i profili di esportazione e per uscire.
• Schede (Tabs):
  • OUT Processor: Per analizzare ed esportare dati da file .out.
  • REC to OUT Converter: Per convertire file .rec in .out.
• Log Console: Mostra in tempo reale i messaggi di stato, di errore e di debug dall'applicazione e dal processo C++.
• Status Bar: Indica lo stato corrente dell'applicazione (es. "Ready", "Processing...").

5. Caso d'Uso 1: Convertire una sequenza .rec in un file .out

Questo processo utilizza la scheda "REC to OUT Converter".

1. Seleziona File di Input: Clicca su "Browse..." accanto a "First .rec File" e seleziona il primo file della tua sequenza (es. data_001.rec).
2. Imposta Numero di File: Nel campo "Number of Files (/n)", imposta il numero totale di file .rec che compongono la sequenza.
3. Scegli Directory di Output: In "Output Directory", seleziona la cartella dove vuoi che il file .out venga salvato. Puoi usare "Browse..." per cercarla o "Open..." per aprire la cartella selezionata in Esplora File.
4. Verifica Nome File Generato: Il campo "Generated Filename" mostrerà automaticamente il nome del file .out che verrà creato.
5. (Opzionale) Configurazione Avanzata: Se necessario, clicca su "g_reconverter Advanced Config..." per modificare i parametri passati a g_reconvert.exe. Per il significato di ogni opzione, fare riferimento alla documentazione specifica di g_reconvert.exe.
6. Avvia Conversione: Clicca su "Convert REC to OUT". Il processo inizierà e la Log Console mostrerà l'output di g_reconvert.exe. La barra di stato indicherà "Processing...".
7. Risultato: Al termine, se la conversione ha avuto successo, il pulsante "Process Generated .out File ->" diventerà attivo. Cliccandolo, l'applicazione passerà automaticamente alla scheda "OUT Processor" e caricherà il file appena creato, pronto per l'analisi.

6. Caso d'Uso 2: Analizzare un file .out ed Esportare i Dati

Questo processo utilizza la scheda "OUT Processor".

1. Seleziona File di Input: Clicca su "Browse..." e seleziona il file .out che vuoi analizzare.
2. Configura Output:
   • Output Directory: Scegli la cartella dove salvare i file esportati (CSV/JSON).
   • Base Filename: Inserisci un nome base per i file di output (es. analisi_volo_1). L'estensione verrà aggiunta automaticamente.
3. Scegli Formati e Profili:
   • Spunta "Generate .csv file" e/o "Generate .json file" per abilitare i formati desiderati.
   • Per ogni formato, seleziona un Profilo di Esportazione dal menu a tendina. Il profilo "Default" è disponibile inizialmente. Per creare profili personalizzati, vedi la sezione 7.
4. Avvia Processo: Clicca su "Process .out File". L'applicazione inizierà a leggere e analizzare il file.
5. Monitora il Progresso:
   • La barra di progresso e i campi "Progress" e "Batches Found" nella sezione "Live Data & Progress" si aggiorneranno in tempo reale.
   • Puoi interrompere il processo in qualsiasi momento cliccando su "Stop".
6. Risultato: Al termine, nella directory di output specificata, troverai i file esportati (es. analisi_volo_1.csv e/o analisi_volo_1.json).

7. Gestione Avanzata: L'Editor dei Profili di Esportazione

Per accedere all'editor, vai su File -> Manage Export Profiles....

• Pannello Sinistro (Profiles):

  • Usa il menu a tendina per selezionare un profilo esistente.
  • New: Crea un nuovo profilo vuoto.
  • Delete: Elimina il profilo attualmente selezionato.

• Pannello Centrale (Available Fields):

  • Mostra un albero di tutti i campi dati che l'applicazione è in grado di estrarre, rispecchiando la struttura dati del file .out.
  • I campi contrassegnati con (Enum) possono essere tradotti.
  • Per aggiungere un campo, selezionalo qui e clicca il pulsante >>.

• Pannello Destro (Selected Fields for Profile):

  • Mostra i campi selezionati per il profilo corrente.
  • >>: Aggiunge il campo selezionato dall'albero di sinistra.
  • <<: Rimuove il campo selezionato da questo elenco.
  • Up/Down: Sposta un campo selezionato su o giù nell'ordine di esportazione.
  • Colonna "Translate": Questa colonna è la chiave per la leggibilità dei dati. Se un campo può essere tradotto (es. una modalità operativa), vedrai un'icona a forma di checkbox (☐ o ☑). Cliccando direttamente su questa cella, puoi attivare/disattivare la traduzione.
    • ☑ (Attiva): Nel file esportato, il valore numerico sarà sostituito dal suo nome (es. 15 -> STT_MASTER_MODE).
    • ☐ (Disattiva): Verrà esportato il valore numerico grezzo.

• Salvataggio: Clicca su "Save & Close" per salvare tutte le modifiche. Se chiudi la finestra senza salvare, ti verrà chiesto se vuoi salvare le modifiche non salvate.

8. Domande Frequenti (FAQ)

• D: Perché il pulsante "Convert REC to OUT" è disabilitato o non funziona?

  • R: Molto probabilmente non hai impostato il percorso corretto per g_reconvert.exe. Segui le istruzioni nella sezione "Configurazione Iniziale".

• D: L'applicazione dà un errore "Failed to parse block" nella console. Cosa significa?

  • R: Indica che il file .out potrebbe essere corrotto, incompleto o in un formato leggermente diverso da quello che il parser si aspetta. Il processo continuerà tentando di analizzare i blocchi successivi.

• D: Come posso aggiungere un campo che non vedo nell'albero "Available Fields"?

  • R: Questo richiede una modifica al codice sorgente. Dovrai:
    1. Aggiungere la struttura corrispondente nel file radar_data_reader/core/data_structures.py.
    2. Implementare la logica di parsing per quella struttura in radar_data_reader/core/struct_parser.py.

• D: Cosa significano tutte le opzioni nella finestra "g_reconverter Advanced Configuration"?

  • R: Quelle opzioni corrispondono direttamente agli argomenti a riga di comando di g_reconvert.exe. Questa GUI funge solo da wrapper per costruirli. Per una spiegazione dettagliata di ogni flag, consulta la documentazione ufficiale di g_reconvert.exe.