# Control Panel Application

This README provides an overview of the Control Panel application, its features, and how to use it.

---

## English

### Overview

The Control Panel is a desktop application designed for visualizing real-time sensor data streams, specifically SAR (Synthetic Aperture Radar) and MFD (Multi-Function Display) images, received via UDP using a custom SFP (Simple Flexible Protocol). It provides tools for image adjustment, georeferencing display, map integration with overlay capabilities, data recording, and KML export for geospatial analysis tools like Google Earth.

This tool is primarily intended for engineers, operators, or developers working with the specific SFP data format and requiring visualization and basic interaction capabilities.

### Key Features

*   **Real-time Data Reception:** Listens for UDP packets, reassembles SFP fragments, and parses image and metadata payloads.
*   **SAR Image Display:**
    *   Displays SAR imagery received via UDP.
    *   Adjustable Brightness, Contrast, and Color Palettes (Gray, Jet, Hot, etc.).
    *   Supports image rotation based on received orientation metadata.
    *   Adjustable display size (zoom factor).
    *   Displays georeferenced center coordinates, orientation, and image size.
    *   Shows geographic coordinates corresponding to mouse cursor position over the image.
    *   Click-to-mark functionality on the SAR image.
*   **MFD Image Display:**
    *   Displays MFD imagery based on received index data.
    *   Configurable color and intensity mapping for different MFD categories via `config.py`.
*   **Map Integration (Optional):**
    *   Displays a background map (default: OpenStreetMap).
    *   Overlays the georeferenced SAR image onto the map.
    *   Adjustable SAR overlay transparency (alpha blending).
    *   Manual Latitude/Longitude shifting for SAR overlay alignment.
    *   Shows geographic coordinates corresponding to mouse cursor position over the map.
    *   Click-to-mark functionality on the Map view.
    *   Scale bar display.
*   **Geospatial Interaction:**
    *   Direct links to open displayed coordinates (SAR Center, SAR Mouse, Map Mouse) in Google Maps or Google Earth.
    *   "GE All" feature generates a composite KML file including points, SAR footprint, and SAR image ground overlay (using `gx:LatLonQuad` for accuracy) for viewing in Google Earth.
*   **SAR Recording:** Saves incoming raw SAR images as GeoTIFF files, embedding georeferencing information. Automatically cleans up old recordings based on configuration.
*   **Test Mode:** Allows running the application using pre-generated or locally stored test images for development and debugging without a live data feed.
*   **Configuration:** Key parameters (Network IP/Port, Map Provider, API Keys, Debug Flags, Recording Paths, KML options, etc.) are configurable via `controlpanel/config.py`.
*   **Logging:** Detailed logging with configurable levels and specific debug flags for granular troubleshooting.

### Requirements

*   Python 3.x (developed with 3.10+ in mind)
*   Required Python Packages (install via `pip install -r requirements.txt` if provided, or install individually):
    *   `numpy`
    *   `opencv-python` (cv2)
    *   `Pillow` (PIL)
    *   `screeninfo`
    *   `requests` (for map tile download)
    *   `mercantile` (for map tile calculations)
    *   `pyproj` (for map projections/calculations)
    *   `tifffile` (for GeoTIFF recording)
    *   `simplekml` (optional, for KML generation)
    *   `lxml` (optional, for KML `gx:LatLonQuad` generation)

### Running the Application

1.  **Navigate:** Open a terminal or command prompt. Change directory to the folder *containing* the `controlpanel` package directory (e.g., the root of your Git repository).
2.  **Run:** Execute the following command:
    ```bash
    python -m controlpanel
    ```
    This command tells Python to run the `controlpanel` package as a module, which will execute the `controlpanel/__main__.py` script.

### Configuration

Most operational parameters can be adjusted by editing the `controlpanel/config.py` file. This includes:

*   Network IP address and Port for UDP listening.
*   Default SAR/MFD display settings (palette, contrast, size).
*   Map provider settings (service name, API key if needed, cache location, online fetching).
*   SAR recording path and file limits.
*   KML generation options and output path.
*   Various debug flags (`DEBUG_*`) to control logging verbosity for different modules.

### Screenshots

<!-- Add screenshots here if desired -->
<!-- Example: -->
<!-- ![SAR Window](docs/images/sar_window.png) -->
<!-- ![Map Overlay](docs/images/map_overlay.png) -->

### License

<!-- Specify your chosen license here. Based on the "AS IS" disclaimer, MIT or Apache 2.0 might be suitable. -->
TBD

---

## Italiano

### 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 e capacità di interazione di base.

### Funzionalità Principali

*   **Ricezione Dati in Tempo Reale:** Ascolta pacchetti UDP, riassembla frammenti SFP ed elabora (parsing) i payload di immagini e metadati.
*   **Visualizzazione Immagini SAR:**
    *   Mostra le immagini SAR ricevute via UDP.
    *   Luminosità, Contrasto e Palette di Colori regolabili (Gray, Jet, Hot, ecc.).
    *   Supporta la rotazione dell'immagine basata sui metadati di orientamento ricevuti.
    *   Dimensione di visualizzazione (fattore di zoom) regolabile.
    *   Mostra coordinate georeferenziate del centro, orientamento e dimensione dell'immagine.
    *   Mostra le coordinate geografiche corrispondenti alla posizione del cursore del mouse sull'immagine.
    *   Funzionalità di marcatura tramite click sull'immagine SAR.
*   **Visualizzazione Immagini MFD:**
    *   Mostra le immagini MFD basate sui dati indice ricevuti.
    *   Mappatura configurabile di colori e intensità per diverse categorie MFD tramite `config.py`.
*   **Integrazione Mappa (Opzionale):**
    *   Mostra una mappa di sfondo (default: OpenStreetMap).
    *   Sovrappone l'immagine SAR georeferenziata sulla mappa.
    *   Trasparenza (alpha blending) dell'overlay SAR regolabile.
    *   Spostamento (shifting) manuale in Latitudine/Longitudine per l'allineamento dell'overlay SAR.
    *   Mostra le coordinate geografiche corrispondenti alla posizione del cursore del mouse sulla mappa.
    *   Funzionalità di marcatura tramite click sulla vista Mappa.
    *   Visualizzazione della barra di scala.
*   **Interazione Geospaziale:**
    *   Link diretti per aprire le coordinate visualizzate (Centro SAR, Mouse SAR, Mouse Mappa) in Google Maps o Google Earth.
    *   Funzionalità "GE All" che genera un file KML composito includendo punti, impronta SAR (footprint) e l'immagine SAR come ground overlay (usando `gx:LatLonQuad` per accuratezza) per la visualizzazione in Google Earth.
*   **Registrazione SAR:** Salva le immagini SAR grezze (raw) in arrivo come file GeoTIFF, incorporando le informazioni di georeferenziazione. Pulisce automaticamente le registrazioni vecchie in base alla configurazione.
*   **Modalità Test:** Permette di eseguire l'applicazione usando immagini di test pre-generate o memorizzate localmente per lo sviluppo e il debug senza un flusso dati live.
*   **Configurazione:** Parametri chiave (IP/Porta di rete, Provider Mappa, Chiavi API, Flag di Debug, Percorsi Registrazione, Opzioni KML, ecc.) sono configurabili tramite `controlpanel/config.py`.
*   **Logging:** Log dettagliato con livelli configurabili e flag di debug specifici per troubleshooting granulare.

### Requisiti

*   Python 3.x (sviluppato pensando a 3.10+)
*   Package Python Richiesti (installare tramite `pip install -r requirements.txt` se 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)

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

### Configurazione

La maggior parte dei parametri operativi può essere regolata modificando il file `controlpanel/config.py`. Questo include:

*   Indirizzo IP e Porta per l'ascolto UDP.
*   Impostazioni di default per la visualizzazione SAR/MFD (palette, contrasto, dimensione).
*   Impostazioni del provider della mappa (nome servizio, chiave API se richiesta, locazione cache, download online).
*   Percorso di registrazione SAR e limiti dei file.
*   Opzioni di generazione KML e percorso di output.
*   Vari flag di debug (`DEBUG_*`) per controllare la verbosità del logging per diversi moduli.

### Screenshot

<!-- Aggiungere screenshot qui se desiderato -->
<!-- Esempio: -->
<!-- ![Finestra SAR](docs/images/sar_window.png) -->
<!-- ![Overlay Mappa](docs/images/map_overlay.png) -->

### Licenza

<!-- Specificare la licenza scelta qui. Basandosi sul disclaimer "AS IS", MIT o Apache 2.0 potrebbero essere adatte. -->
TBD

---