247 lines
19 KiB
Markdown
247 lines
19 KiB
Markdown
## 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:
|
|
```bash
|
|
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`.
|
|
```python
|
|
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`.
|
|
```python
|
|
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
|
|
|
|
<!-- Aggiungere screenshot qui se desiderato -->
|
|
<!-- Esempio: -->
|
|
<!--  -->
|
|
<!--  -->
|
|
|
|
### 13. Licenza
|
|
|
|
<!-- Specificare la licenza scelta qui. Basandosi sul disclaimer "AS IS", MIT o Apache 2.0 potrebbero essere adatte. -->
|
|
Esempio: Questo progetto è rilasciato sotto Licenza MIT - vedi il file LICENSE.md per dettagli (se ne aggiungi uno).
|
|
|