SXXXXXXX_ControlPanel/doc/Italian-Manual.md

Assolutamente! Preparerò un manuale utente chiaro e schematico per la tua applicazione, sia in italiano che in inglese.

---

Manuale Utente - Control Panel Applicazione

(English Version Below)

---

Manuale Utente (Italiano)

1. Introduzione

Questo documento descrive l'utilizzo dell'applicazione "Control Panel", progettata per visualizzare, elaborare e interagire con flussi di dati immagine SAR (Synthetic Aperture Radar) e MFD (Multi-Functional Display) ricevuti tramite rete UDP. L'applicazione permette inoltre l'integrazione con mappe geografiche, la generazione di file KML per Google Earth e la registrazione di immagini SAR.

2. Concetti Chiave

• SAR (Synthetic Aperture Radar): Immagine radar ad alta risoluzione. Tipicamente richiede più elaborazione per la visualizzazione (contrasto, luminosità, palette). Può essere georeferenziata.
• MFD (Multi-Functional Display): Display operativo a bassa risoluzione e alta frequenza di aggiornamento. Utilizza una palette di colori predefinita per rappresentare diverse categorie di simboli o dati radar grezzi.
• Overlay Mappa: Funzionalità che permette di sovrapporre l'immagine SAR (georeferenziata) su una mappa geografica di base (es. OpenStreetMap) per contestualizzazione.
• Modalità Test: Permette di utilizzare l'applicazione senza un flusso dati reale, usando immagini di test generate internamente che simulano i dati SAR e MFD.
• Registrazione SAR: Salva le immagini SAR raw (grezze) ricevute come file GeoTIFF georeferenziati per analisi offline.
• KML (Keyhole Markup Language): Formato file utilizzato da Google Earth per visualizzare dati geografici, inclusi punti, poligoni e overlay di immagini.
• GeoTIFF: Un formato file TIFF standard che include metadati geografici (coordinate, proiezione, scala) incorporati nel file stesso.

3. Avvio e Panoramica Iniziale

1. Avvio: Eseguire lo script Python principale (presumibilmente ControlPanel.py o un eseguibile compilato).
2. Finestre: All'avvio, l'applicazione aprirà diverse finestre:
   • Control Panel: La finestra principale con tutti i controlli utente (Tkinter).
   • SAR: Finestra dedicata alla visualizzazione dell'immagine SAR elaborata (OpenCV).
   • MFD: Finestra dedicata alla visualizzazione dell'immagine MFD elaborata (OpenCV).
   • Map Overlay (Opzionale): Se abilitata nella configurazione, una finestra dedicata alla mappa geografica con l'eventuale overlay SAR (OpenCV).

4. Panoramica dell'Interfaccia Utente (Finestra Control Panel)

La finestra principale è suddivisa in sezioni logiche:

• SAR Parameters:
  • Checkbox Test Image: Attiva/Disattiva la modalità Test.
  • Checkbox Record SAR: Attiva/Disattiva la registrazione dei file GeoTIFF SAR.
  • Combobox Size: Seleziona il fattore di riduzione per la visualizzazione dell'immagine SAR (es. "1:2" mostra l'immagine a metà della sua risoluzione originale).
  • Combobox Palette: Seleziona la palette di colori da applicare all'immagine SAR (es. GRAY, JET, HOT).
  • Slider Contrast: Regola il contrasto dell'immagine SAR.
  • Slider Brightness: Regola la luminosità dell'immagine SAR.
  • Checkbox Show SAR Metadata: Mostra/Nasconde il pannello laterale con i metadati grezzi ricevuti per l'immagine SAR corrente.
• MFD Parameters:
  • Slider Intensità (per categoria): Regola l'intensità (luminosità) di specifiche categorie di simboli MFD (Occlusion, Cat A, Cat B, ecc.).
  • Button Color (per categoria): Apre una finestra di dialogo per scegliere il colore RGB da associare a una specifica categoria MFD.
  • Label Anteprima Colore: Mostra il colore attualmente selezionato per la categoria.
  • Slider Raw Map: Regola l'intensità massima dei pixel della mappa grezza MFD (valori da 32 a 255).
• Map Parameters:
  • Combobox Map Display Size: Seleziona un fattore di scala per ingrandire o ridurre la finestra della mappa rispetto alla sua dimensione base calcolata.
  • Button Save Map View: Salva la vista corrente della finestra "Map Overlay" (inclusi overlay, barra di scala, marker) in un file immagine PNG.
  • Checkbox Show SAR Overlay on Map: Mostra/Nasconde l'immagine SAR sovrapposta alla mappa di base.
  • Slider SAR Overlay Alpha: Regola la trasparenza dell'overlay SAR (0.0 = trasparente, 1.0 = opaco).
  • Input SAR Shift (deg): Campi per inserire uno shift (spostamento) manuale in gradi di latitudine e longitudine da applicare alla posizione dell'overlay SAR sulla mappa.
  • Button Apply Shift: Applica lo shift inserito all'overlay SAR sulla mappa.
• Info Display:
  • SAR Center: Mostra le coordinate geografiche (Lat/Lon DMS) del centro dell'immagine SAR corrente.
  • Image Orient: Mostra l'orientamento (in gradi) dell'immagine SAR corrente.
  • Image Size: Mostra le dimensioni geografiche stimate (km) dell'immagine SAR corrente.
  • SAR Mouse: Mostra le coordinate geografiche (Lat/Lon DMS) corrispondenti alla posizione del cursore sulla finestra SAR.
  • Map Mouse: Mostra le coordinate geografiche (Lat/Lon DMS) corrispondenti alla posizione del cursore sulla finestra Map Overlay.
  • Button Go (accanto alle coordinate): Apre la posizione corrispondente in Google Maps nel browser web predefinito.
  • Button GE (accanto alle coordinate): Apre Google Earth Pro (se installato) centrato sulla posizione corrispondente e con un segnaposto.
  • Stats Drop: Mostra le statistiche sui pacchetti scartati dalle varie code interne.
  • Incomplete: Mostra le statistiche sulle ricezioni incomplete di immagini SAR/MFD.
  • Button GE All: Genera un file KML composito che include i punti (Centro SAR, Mouse SAR, Mouse Mappa), il contorno del footprint SAR e l'overlay dell'immagine SAR processata; quindi tenta di aprirlo con Google Earth Pro.
• Pannello Metadata (Opzionale):
  • Un pannello separato che appare/scompare a destra del pannello di controllo principale quando si seleziona/deseleziona "Show SAR Metadata".
  • Visualizza i metadati grezzi contenuti nell'header dell'immagine SAR corrente, formattati per leggibilità.
• Status Bar (in basso):
  • Mostra lo stato corrente (es. "Network", "Test Mode", "Local Mode"), l'eventuale stato della mappa ("MapOn"), e gli FPS (Frame Per Second) stimati per MFD e SAR.

5. Funzionalità Dettagliate

• Visualizzazione SAR/MFD: Le immagini ricevute (o di test) vengono elaborate e mostrate nelle rispettive finestre OpenCV.
• Regolazione SAR: Modificando contrasto, luminosità e palette si altera l'aspetto dell'immagine nella finestra SAR in tempo reale. Cambiando la dimensione si aggiorna la risoluzione della finestra SAR.
• Regolazione MFD: Modificando intensità e colore delle categorie si altera l'aspetto dei simboli nella finestra MFD in tempo reale.
• Interazione Mouse SAR/Mappa: Muovendo il mouse sulle finestre SAR o Map Overlay, le coordinate geografiche corrispondenti vengono calcolate e mostrate nel pannello "Info Display". Un click sinistro sulla finestra SAR o Mappa posiziona un marker rosso (croce) e aggiorna le coordinate.
• Shift Overlay SAR: Utile per correggere manualmente disallineamenti tra l'immagine SAR e la mappa base dovuti a imprecisioni nei dati di georeferenziazione ricevuti. Inserire i valori in gradi decimali e premere "Apply Shift".
• Link Esterni (Go/GE): Permettono una rapida visualizzazione di punti specifici (centro immagine, posizione mouse) su Google Maps o Google Earth.
• KML Composito (GE All): Crea un singolo file KML per Google Earth che mostra contemporaneamente i punti di interesse, il contorno geografico dell'immagine SAR e l'immagine SAR stessa sovrapposta al terreno 3D. Utilizza <gx:LatLonQuad> (se lxml è installato) per una mappatura precisa dell'immagine.
• Registrazione GeoTIFF: Quando "Record SAR" è attivo, ogni immagine SAR grezza ricevuta viene salvata in background come file .tif nella sottocartella sar_images. Questi file contengono i dati pixel originali e metadati georeferenziati (richiede tifffile). I file più vecchi vengono eliminati automaticamente oltre un limite configurato.
• Visualizzazione Metadati: Permette di ispezionare i valori grezzi contenuti nell'header dell'immagine SAR, utile per debugging o analisi approfondita.

6. Flussi di Lavoro Comuni (Casi d'Uso)

• Caso 1: Visualizzazione Base (Modalità Network)
  1. Avviare l'applicazione. Assicurarsi che il ricevitore UDP sia in ascolto sull'IP/porta corretta (visibile nella Status Bar).
  2. Osservare le finestre SAR e MFD popolarsi con i dati ricevuti.
  3. Regolare i parametri SAR (contrasto, luminosità, palette) per ottimizzare la visualizzazione SAR.
  4. Regolare i parametri MFD (intensità, colori) se necessario.
  5. Se l'integrazione mappa è attiva, osservare la finestra Map Overlay.
• Caso 2: Utilizzo della Mappa e Overlay SAR
  1. Assicurarsi che l'integrazione mappa sia abilitata (se non lo è, modificare config.py e riavviare).
  2. Attendere il caricamento della mappa iniziale nella finestra Map Overlay.
  3. Abilitare "Show SAR Overlay on Map" nel pannello "Map Parameters".
  4. Osservare l'immagine SAR apparire sovrapposta alla mappa.
  5. Regolare lo slider "SAR Overlay Alpha" per modificare la trasparenza dell'overlay.
  6. Se l'overlay non è perfettamente allineato con le feature della mappa, inserire piccoli valori (gradi decimali) nei campi "SAR Shift Lat/Lon" e premere "Apply Shift" finché l'allineamento è soddisfacente.
  7. Muovere il mouse sulla finestra Map Overlay per vedere le coordinate geografiche corrispondenti nel pannello Info.
  8. Cliccare sulla mappa per posizionare un marker e usare i bottoni "Go"/"GE" per visualizzare quel punto esternamente.
  9. Premere "Save Map View" per salvare un'istantanea PNG della finestra mappa.
• Caso 3: Analisi Coordinate e Integrazione Google Earth
  1. Osservare le coordinate del centro SAR o muovere il mouse sulle finestre SAR/Map per trovare un punto di interesse.
  2. Usare i bottoni "Go" per aprire rapidamente la posizione in Google Maps nel browser.
  3. Usare i bottoni "GE" per aprire Google Earth focalizzato su quel punto specifico.
  4. Per una vista d'insieme, premere "GE All". Questo genera un KML (composite_*.kml) nella cartella kml_output contenente i punti, il contorno SAR e l'immagine SAR sovrapposta al terreno 3D, e tenta di aprirlo in Google Earth.
• Caso 4: Registrazione Dati SAR per Analisi Offline
  1. Assicurarsi che la libreria tifffile sia installata.
  2. Attivare la checkbox "Record SAR" nel pannello "SAR Parameters".
  3. L'applicazione inizierà a salvare ogni immagine SAR grezza ricevuta come file GeoTIFF nella sottocartella sar_images.
  4. I file avranno nomi basati sul timestamp (es. YYYYMMDD_HHMMSS_ms_SAR_geo_img16.tif).
  5. Per interrompere la registrazione, deselezionare la checkbox "Record SAR".
  6. I file GeoTIFF possono essere aperti con software GIS (es. QGIS) per analisi successive.
• Caso 5: Utilizzo della Modalità Test
  1. Attivare la checkbox "Test Image" nel pannello "SAR Parameters".
  2. L'applicazione smetterà di processare i dati di rete (se presenti) e inizierà a visualizzare immagini SAR e MFD generate internamente.
  3. Le immagini di test scorreranno orizzontalmente.
  4. È ancora possibile modificare i parametri SAR (contrasto, luminosità, palette, dimensione) e MFD (intensità, colore) per vedere il loro effetto sulle immagini di test. L'overlay mappa non sarà significativo in modalità test (userà GeoInfo di default o l'ultimo valido).
  5. Per tornare alla modalità normale (Network o Local), deselezionare "Test Image".
• Caso 6: Ispezione Metadati SAR
  1. Attivare la checkbox "Show SAR Metadata" nel pannello "SAR Parameters".
  2. Un pannello aggiuntivo apparirà alla destra dei controlli principali.
  3. Questo pannello mostrerà una rappresentazione testuale formattata dell'intera struttura ImageLeaderData ricevuta con l'immagine SAR più recente. I valori sono mostrati con le loro unità (dove note, es. radianti e gradi).
  4. Utile per verificare i valori grezzi di georeferenziazione, dimensioni, contatori, ecc.
  5. Deselezionare la checkbox per nascondere il pannello.