VALLONGOL/SXXXXXXX_ControlPanel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
68ac3f6d02
SXXXXXXX_ControlPanel/doc/Italian-Manual.md
VALLONGOL 30be7ea111 update manual
2025-05-07 15:09:00 +02:00

19 KiB
Raw Blame History

Italiano

(La traduzione italiana seguirà la stessa struttura e contenuti della versione inglese, adattando la terminologia tecnica dove appropriato.)

1. Panoramica

Il Pannello di Controllo (Control Panel) è un'applicazione desktop progettata per visualizzare flussi di dati da sensori in tempo reale, specificamente immagini SAR (Radar ad Apertura Sintetica) e MFD (Display Multi-Funzione), ricevuti via UDP utilizzando un protocollo custom SFP (Simple Flexible Protocol). Fornisce strumenti per la regolazione delle immagini, la visualizzazione di informazioni di georeferenziazione, l'integrazione su mappa con capacità di sovrapposizione (overlay), la registrazione dei dati e l'esportazione KML per strumenti di analisi geospaziale come Google Earth.

Questo strumento è primariamente inteso per ingegneri, operatori o sviluppatori che lavorano con lo specifico formato dati SFP e necessitano di visualizzazione, interazione e capacità di analisi di base.

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 configurabile 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, utile per test UI e sviluppo.
  • 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. Guida Rapida

  1. Avvio: Eseguire lo script Python principale o l'eseguibile compilato. Da riga di comando, navigare nella cartella contenente il package controlpanel ed eseguire python -m controlpanel.
  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. Interfaccia Utente (Finestra Control Panel)

La finestra principale è suddivisa in sezioni:

  • Parametri SAR:
    • Checkbox Test Image: Attiva/Disattiva la Modalità Test.
    • Checkbox Record SAR: Attiva/Disattiva la registrazione GeoTIFF SAR.
    • Combobox Size: Seleziona il fattore di riduzione per la visualizzazione SAR (es. "1:2" per metà risoluzione).
    • Combobox Palette: Seleziona la mappa di colori SAR (es. GRAY, JET, HOT).
    • Slider Contrast: Regola il contrasto SAR.
    • Slider Brightness: Regola la luminosità SAR.
    • Checkbox Show SAR Metadata: Mostra/Nasconde il pannello laterale con i metadati SAR grezzi.
  • Parametri MFD:
    • Slider Intensità (per categoria): Regola intensità per categorie simboli MFD (Occlusion, Cat A, ecc.).
    • Button Color (per categoria): Sceglie colore RGB per categorie MFD.
    • Label Anteprima Colore: Mostra il colore di categoria selezionato.
    • Slider Raw Map: Regola intensità massima per pixel mappa grezza MFD.
  • Parametri Mappa (se mappa abilitata):
    • Combobox Map Display Size: Scala la dimensione della finestra mappa.
    • Button Save Map View: Salva la vista mappa corrente (con overlay, barra scala, marker) come PNG.
    • Checkbox Show SAR Overlay on Map: Attiva/Disattiva overlay SAR sulla mappa.
    • Slider SAR Overlay Alpha: Regola trasparenza overlay SAR.
    • Input SAR Shift (deg) (Lat/Lon): Sposta manualmente l'overlay SAR.
    • Button Apply Shift: Applica lo spostamento Lat/Lon inserito.
  • Info Display:
    • SAR Center: Centro georeferenziato immagine SAR (Lat/Lon DMS).
    • Image Orient: Orientamento immagine SAR (gradi).
    • Image Size: Dimensione geografica stimata immagine SAR (km).
    • SAR Mouse: Coordinate geografiche sotto il cursore nella finestra SAR.
    • Map Mouse: Coordinate geografiche sotto il cursore nella finestra Mappa.
    • Button Go (accanto alle coordinate): Apre la posizione in Google Maps.
    • Button GE (accanto alle coordinate): Apre Google Earth sulla posizione con un segnaposto.
    • Stats Drop: Statistiche pacchetti scartati dalle code interne.
    • Incomplete: Statistiche ricezioni incomplete immagini SAR/MFD.
    • Button GE All: Genera un KML composito (punti, impronta SAR, overlay SAR) per Google Earth.
  • Pannello Metadati (Opzionale): Appare quando "Show SAR Metadata" è selezionato. Visualizza metadati grezzi formattati dall'header dell'immagine SAR corrente.
  • Barra di Stato (in basso): Mostra modalità corrente (Network, Test, Local), stato mappa, e FPS stimati MFD/SAR.

5. Funzionalità Dettagliate

  • Ricezione Dati in Tempo Reale: Ascolta pacchetti UDP, riassembla frammenti SFP ed elabora i payload di immagini e metadati.
  • Visualizzazione SAR/MFD: Le immagini vengono elaborate secondo i parametri UI e visualizzate.
  • Interazione Mouse SAR/Mappa: I movimenti del mouse aggiornano le coordinate visualizzate. Click sinistro posiziona un marker (croce rossa) e aggiorna le coordinate.
  • Shift Overlay SAR: Corregge manualmente il disallineamento dell'overlay SAR sulla mappa.
  • KML Composito ("GE All"): Crea un file KML (composite_*.kml in kml_output/) per una vista completa in Google Earth, includendo punti, impronta SAR e l'immagine SAR mappata con precisione usando <gx:LatLonQuad> (se lxml è installato).
  • Registrazione GeoTIFF: Con "Record SAR" attivo, le immagini SAR grezze vengono salvate come GeoTIFF in sar_images/. I file sono nominati con timestamp (es. YYYYMMDD_HHMMSS_ms_SAR_geo_img16.tif) e contengono metadati di georeferenziazione. I file vecchi vengono eliminati automaticamente in base ai limiti di config.py.
  • Visualizzazione Metadati: Ispeziona i valori grezzi dell'header SAR per debug o analisi dettagliata.

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

  • Caso 1: Visualizzazione Base (Modalità Network)
    1. Avviare l'applicazione. Verificare lo stato di ascolto UDP nella Barra di Stato.
    2. Osservare le finestre SAR e MFD popolarsi.
    3. Regolare i parametri SAR (contrasto, luminosità, palette) e MFD (intensità, colori) se necessario.
    4. 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 (vedi config.py).
    2. Attendere il caricamento della mappa iniziale.
    3. Selezionare "Show SAR Overlay on Map".
    4. Regolare "SAR Overlay Alpha" per la trasparenza.
    5. Se disallineato, usare "SAR Shift Lat/Lon" e "Apply Shift".
    6. Muovere il mouse sulla mappa per coordinate; cliccare per marcare.
    7. Usare "Go"/"GE" per visualizzazione esterna.
    8. Premere "Save Map View" per salvare uno snapshot PNG.
  • Caso 3: Analisi Coordinate e Integrazione Google Earth
    1. Identificare punti di interesse tramite mouse SAR/Mappa o display centro SAR.
    2. Usare "Go" per Google Maps o "GE" per una vista Google Earth focalizzata.
    3. Per una vista completa, premere "GE All" per generare e aprire un KML composito.
  • Caso 4: Registrazione Dati SAR per Analisi Offline
    1. Assicurarsi che la libreria tifffile sia installata.
    2. Selezionare "Record SAR".
    3. Le immagini SAR grezze verranno salvate come GeoTIFF in sar_images/.
    4. Deselezionare per interrompere. I file possono essere aperti in software GIS (es. QGIS).
  • Caso 5: Utilizzo della Modalità Test
    1. Selezionare "Test Image".
    2. L'applicazione visualizzerà immagini SAR e MFD generate internamente, a scorrimento.
    3. I parametri SAR/MFD rimangono regolabili. L'overlay mappa userà GeoInfo di default/ultimo valido.
    4. Deselezionare per tornare alla modalità normale.
  • Caso 6: Ispezione Metadati SAR
    1. Selezionare "Show SAR Metadata".
    2. Apparirà un pannello con ImageLeaderData formattata dall'ultima immagine SAR.
    3. Deselezionare per nascondere.

7. Requisiti

  • Python 3.x (sviluppato pensando a 3.10+)
  • Package Python Richiesti (installare tramite pip install -r requirements.txt se un file è fornito, o installare individualmente):
    • numpy
    • opencv-python (cv2)
    • Pillow (PIL)
    • screeninfo
    • requests (per download tiles mappa)
    • mercantile (per calcoli tiles mappa)
    • pyproj (per proiezioni/calcoli mappa)
    • tifffile (per registrazione GeoTIFF)
    • simplekml (opzionale, per generazione KML)
    • lxml (opzionale, per generazione gx:LatLonQuad KML)

8. Esecuzione dell'Applicazione

  1. Naviga: Apri un terminale o prompt dei comandi. Entra nella cartella che contiene la cartella del package controlpanel (es., la radice del tuo repository Git).
  2. Esegui: Lancia il seguente comando: 
    python -m controlpanel
    Questo comando indica a Python di eseguire il package controlpanel come un modulo, il che eseguirà lo script controlpanel/__main__.py.

9. Configurazione

La maggior parte dei parametri operativi può essere regolata modificando il file controlpanel/config.py usando un editor di testo standard.

Applicare le Modifiche:

  1. Apri controlpanel/config.py.
  2. Modifica la/le costante/i desiderata/e (es. DEFAULT_SER_PORT, ENABLE_MAP_OVERLAY, DEBUG_RECEIVER_PACKETS).
  3. Salva il file config.py.
  4. Riavvia l'applicazione Control Panel (chiudila se in esecuzione, poi lancia di nuovo python -m controlpanel) affinché le modifiche abbiano effetto.

Questo file contiene impostazioni per: IP/Porta di rete, visualizzazione SAR/MFD, provider mappa, registrazione SAR, KML, livelli di logging e flag di debug.

10. Configurazione del Debug

L'applicazione usa il modulo logging standard di Python. Regola la verbosità dei log in controlpanel/config.py.

1. Livelli di Logging:

  • LOG_ROOT_LEVEL: Livello minimo che il logger processerà. Per debug con flag, impostare a logging.DEBUG. 
    LOG_ROOT_LEVEL = logging.DEBUG # Raccomandato per debug
  • LOG_HANDLER_LEVEL: Livello minimo emesso sulla console. Per vedere i messaggi DEBUG controllati dai flag, impostare anche questo a logging.DEBUG. 
    LOG_HANDLER_LEVEL = logging.DEBUG # Necessario per vedere messaggi DEBUG

2. Flag di Debug (DEBUG_*):

Flag booleani (True/False) per mostrare categorie di messaggi DEBUG (se i livelli sopra sono logging.DEBUG). Impostare a True per dettagli.

Nome Flag Scopo Default
DEBUG_APP_LIFECYCLE Passi core avvio/arresto app, init stato, setup UI. False
DEBUG_APP_CALLBACKS Ingresso/uscita/valori callback UI generali. False
DEBUG_APP_QUEUE_PROCESSING Elaborazione elementi code app. False
DEBUG_APP_IMG_PROCESSING Passi elaborazione centrale immagini (ImagePipeline). False
DEBUG_APP_TEST_MODE Generazione img test, scheduling, aggiornamenti, cambio modalità. False
DEBUG_APP_GEO_CALC Calcolo coordinate geo mouse e accodamento. False
DEBUG_APP_MFD_PARAMS Callback UI parametri MFD e ricalcolo LUT MFD. False
DEBUG_APP_STATUS Logica aggiornamento barra di stato. False
DEBUG_APP_TRIGGER Log chiamate trigger aggiornamenti interni. False
DEBUG_RECEIVER_LOOP Eventi generali loop receiver UDP. False
DEBUG_RECEIVER_PACKETS (Alto Volume) Log header ogni pacchetto SFP raw ricevuto. False
DEBUG_RECEIVER_REASSEMBLY Logica riassemblaggio frammenti, allocazione buffer, task worker. False
DEBUG_RECEIVER_GEO Dettagli estrazione GeoInfo/Metadati. False
DEBUG_RECEIVER_ACK Dettagli invio ACK SFP. False
DEBUG_RECEIVER_CLEANUP Azioni pulizia transazioni. False
DEBUG_DISPLAY_MANAGER Creazione finestre display (SAR, MFD, Mappa), aggiornamenti, callback. False
DEBUG_UTILS Log da funzioni utility generiche. False
DEBUG_NETWORK Log da funzioni utility rete. False
DEBUG_IMAGE_PROCESSING Log da funzioni elaborazione immagini. False
DEBUG_IMAGE_RECORDER Log dal modulo registrazione GeoTIFF. True
DEBUG_MAP_DETAILS Fetching/caching tiles mappa, calcoli coordinate, operazioni overlay. False

Esempi Pratici di Debug:

  • Nessun dato ricevuto? Imposta LOG_ROOT_LEVEL & LOG_HANDLER_LEVEL a DEBUG. Abilita DEBUG_NETWORK, DEBUG_RECEIVER_LOOP, e temporaneamente DEBUG_RECEIVER_PACKETS.
  • Immagine SAR errata? Abilita DEBUG_IMAGE_PROCESSING, DEBUG_APP_CALLBACKS, DEBUG_APP_IMG_PROCESSING.
  • Problemi overlay mappa? Abilita DEBUG_MAP_DETAILS, DEBUG_DISPLAY_MANAGER, DEBUG_RECEIVER_GEO.
  • Troppi log? Imposta LOG_HANDLER_LEVEL = logging.INFO o flag DEBUG_* specifici a False.

11. FAQ & Risoluzione Problemi

  • D: Nessuna finestra mappa appare, anche se ENABLE_MAP_OVERLAY è True.
    • R:
      1. Controlla Librerie: Assicurati che Pillow, mercantile, pyproj, e requests siano installati. Controlla i log della console all'avvio per messaggi ImportError.
      2. GeoInfo: La mappa richiede informazioni di georeferenziazione valide dai dati SAR (blocco GEO_DATA). Se mancanti o non validi, l'aggiornamento mappa potrebbe essere saltato. Controlla i log per Skipping: Invalid GeoInfo.
      3. Accesso Online: Se le tiles mappa non sono in cache, assicurati che config.ENABLE_ONLINE_MAP_FETCHING = True e che l'applicazione abbia accesso a internet.
      4. Configurazione: Ricontrolla MAP_SERVICE_PROVIDER in config.py (dovrebbe essere "osm" per OpenStreetMap).
      5. Log di Debug: Abilita DEBUG_MAP_DETAILS e DEBUG_DISPLAY_MANAGER per vedere log dettagliati dai componenti mappa.
  • D: La finestra SAR/MFD/Mappa appare brevemente e poi si chiude, o non appare.
    • R: Può succedere per un errore iniziale nel loop di display OpenCV o se un'altra parte dell'applicazione va in crash.
      1. Controlla la console per eccezioni Python subito dopo la scomparsa della finestra.
      2. Abilita DEBUG_DISPLAY_MANAGER per vedere log da creazione finestre e chiamate imshow.
      3. Assicurati che l'installazione OpenCV includa il supporto GUI.
  • D: Le coordinate in "Info Display" sono "N/A" o "Error".
    • R:
      1. Per coordinate SAR (Center, Mouse): Di solito significa che i dati SAR in arrivo non hanno GeoInfo valido, o c'è stato un errore nell'elaborazione. Abilita DEBUG_RECEIVER_GEO e DEBUG_APP_GEO_CALC.
      2. Per Map Mouse: La mappa potrebbe non essersi caricata correttamente, o c'è un problema con la libreria mercantile nella conversione pixel-geo. Abilita DEBUG_MAP_DETAILS.
  • D: I file KML sono generati ma Google Earth non mostra l'overlay SAR correttamente (es. stirato, posizione errata).
    • R:
      1. Assicurati che la libreria lxml sia installata (pip install lxml). Questo abilita il tag KML gx:LatLonQuad, più accurato.
      2. Verifica l'accuratezza di GEO_DATA nei pacchetti SAR, specialmente ORIENTATION, SCALE_X, SCALE_Y, e LATITUDE/LONGITUDE del centro. Errori qui si propagano al KML. Abilita DEBUG_RECEIVER_GEO.
      3. Controlla DEBUG_UTILS per log durante la generazione KML, specificamente relativi al calcolo degli angoli (_calculate_geo_corners_for_kml).
  • D: I file GeoTIFF sono registrati ma non si aprono o la georeferenziazione è errata in software GIS.
    • R:
      1. Assicurati che la libreria tifffile sia installata.
      2. Abilita DEBUG_IMAGE_RECORDER per log dettagliati su creazione tag e scrittura.
      3. Verifica l'accuratezza di GEO_DATA dai pacchetti SAR.
      4. Il calcolo della trasformata affine dipende dalla correttezza di scala, orientamento e punto di riferimento da GEO_DATA.
  • D: L'applicazione è lenta o non risponde.
    • R:
      1. Log di Debug Voluminosi: Se molti flag DEBUG_* sono True (specialmente DEBUG_RECEIVER_PACKETS), il logging sulla console può rallentare l'applicazione. Riduci la verbosità del debug.
      2. Dimensioni Code: Se le code interne (DEFAULT_SAR_QUEUE, DEFAULT_MFD_QUEUE) sono troppo piccole e il rate di arrivo dati è alto, l'elaborazione potrebbe essere in ritardo. Meno probabile che causi irresponsività, ma può portare a frame scartati.
      3. Operazioni Pesanti: Stitching mappa e warping overlay SAR possono essere intensivi per la CPU. Se avvengono molto frequentemente su macchine lente, potrebbe impattare la reattività.

12. Screenshot

13. Licenza

Esempio: Questo progetto è rilasciato sotto Licenza MIT - vedi il file LICENSE.md per dettagli (se ne aggiungi uno).