# Control Panel Application

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

---

## English

### 1. 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, interaction, and basic analysis capabilities.

### 2. Key Concepts

*   **SAR (Synthetic Aperture Radar):** High-resolution radar imagery. Typically requires more processing for visualization (contrast, brightness, palette). Can be georeferenced.
*   **MFD (Multi-Functional Display):** Low-resolution, high-frame-rate operational display. Uses a configurable color palette to represent different symbol categories or raw radar data.
*   **Map Overlay:** Feature allowing the superposition of the georeferenced SAR image onto a base geographic map (e.g., OpenStreetMap) for contextualization.
*   **Test Mode:** Allows using the application without a live data stream by utilizing internally generated test images that simulate SAR and MFD data, useful for UI testing and development.
*   **SAR Recording:** Saves the received *raw* SAR images as georeferenced GeoTIFF files for offline analysis.
*   **KML (Keyhole Markup Language):** File format used by Google Earth to display geographic data, including points, polygons, and image overlays.
*   **GeoTIFF:** A standard TIFF file format that includes geographic metadata (coordinates, projection, scale) embedded within the file itself.

### 3. Getting Started

1.  **Launch:** Execute the main Python script or the compiled executable. From the command line, navigate to the directory containing the `controlpanel` package and run `python -m controlpanel`.
2.  **Windows:** Upon launch, the application will open several windows:
    *   **Control Panel:** The main window with all user controls (Tkinter).
    *   **SAR:** Dedicated window for displaying the processed SAR image (OpenCV).
    *   **MFD:** Dedicated window for displaying the processed MFD image (OpenCV).
    *   **Map Overlay (Optional):** If enabled in the configuration, a dedicated window for the geographic map with the potential SAR overlay (OpenCV).

### 4. User Interface (Control Panel Window)

The main window is divided into sections:

*   **SAR Parameters:**
    *   `Test Image Checkbox:` Toggles Test Mode.
    *   `Record SAR Checkbox:` Toggles SAR GeoTIFF recording.
    *   `Size Combobox:` Selects SAR display downscaling factor (e.g., "1:2" for half resolution).
    *   `Palette Combobox:` Selects SAR color map (e.g., GRAY, JET, HOT).
    *   `Contrast Slider:` Adjusts SAR image contrast.
    *   `Brightness Slider:` Adjusts SAR image brightness.
    *   `Show SAR Metadata Checkbox:` Shows/Hides a side panel with raw SAR metadata.
*   **MFD Parameters:**
    *   `Intensity Slider (per category):` Adjusts intensity for MFD symbol categories (Occlusion, Cat A, etc.).
    *   `Color Button (per category):` Choose RGB color for MFD categories.
    *   `Color Preview Label:` Shows the selected category color.
    *   `Raw Map Slider:` Adjusts max intensity for MFD raw map pixels.
*   **Map Parameters (if map enabled):**
    *   `Map Display Size Combobox:` Scales the map window size.
    *   `Save Map View Button:` Saves the current map view (with overlays, scale bar, markers) as a PNG.
    *   `Show SAR Overlay on Map Checkbox:` Toggles SAR image overlay on the map.
    *   `SAR Overlay Alpha Slider:` Adjusts SAR overlay transparency.
    *   `SAR Shift (deg) Inputs (Lat/Lon):` Manually shift the SAR overlay.
    *   `Apply Shift Button:` Applies the entered Lat/Lon shift.
*   **Info Display:**
    *   `SAR Center:` Georeferenced center of SAR image (Lat/Lon DMS).
    *   `Image Orient:` SAR image orientation (degrees).
    *   `Image Size:` Estimated geographic size of SAR image (km).
    *   `SAR Mouse:` Geographic coordinates under the mouse cursor in the SAR window.
    *   `Map Mouse:` Geographic coordinates under the mouse cursor in the Map Overlay window.
    *   `Go Button (next to coordinates):` Opens the location in Google Maps.
    *   `GE Button (next to coordinates):` Opens Google Earth to the location with a placemark.
    *   `Stats Drop:` Packet drop statistics for internal queues.
    *   `Incomplete:` Incomplete SAR/MFD image reception statistics.
    *   `GE All Button:` Generates a composite KML (points, SAR footprint, SAR overlay) for Google Earth.
*   **Metadata Panel (Optional):** Appears when "Show SAR Metadata" is checked. Displays formatted raw metadata from the current SAR image header.
*   **Status Bar (Bottom):** Shows current mode (Network, Test, Local), map status, and estimated MFD/SAR FPS.

### 5. Detailed Functionalities

*   **Real-time Data Reception:** Listens for UDP packets, reassembles SFP fragments, and parses image and metadata payloads.
*   **SAR/MFD Visualization:** Images are processed according to UI parameters and displayed.
*   **SAR/Map Mouse Interaction:** Mouse movements update coordinate displays. Left-clicks place a marker (red cross) and update coordinates.
*   **SAR Overlay Shift:** Manually correct SAR overlay alignment on the map.
*   **KML Composite ("GE All"):** Creates a KML file (`composite_*.kml` in `kml_output/`) for a comprehensive Google Earth view, including points, SAR footprint, and the precisely mapped SAR image using `<gx:LatLonQuad>` (if `lxml` is installed).
*   **GeoTIFF Recording:** When "Record SAR" is active, raw SAR images are saved as GeoTIFFs in `sar_images/`. Files are timestamped (e.g., `YYYYMMDD_HHMMSS_ms_SAR_geo_img16.tif`) and contain georeferencing metadata. Old files are auto-deleted based on `config.py` limits.
*   **Metadata Viewing:** Inspect raw SAR header values for debugging or detailed analysis.

### 6. Common Workflows (Use Cases)

*   **Use Case 1: Basic Viewing (Network Mode)**
    1.  Launch the application. Verify UDP listening status in the Status Bar.
    2.  Observe SAR and MFD windows populate.
    3.  Adjust SAR (contrast, brightness, palette) and MFD (intensity, colors) parameters as needed.
    4.  If map integration is active, observe the Map Overlay window.
*   **Use Case 2: Using the Map and SAR Overlay**
    1.  Ensure map integration is enabled (see `config.py`).
    2.  Wait for the initial map to load.
    3.  Check "Show SAR Overlay on Map".
    4.  Adjust "SAR Overlay Alpha" for transparency.
    5.  If misaligned, use "SAR Shift Lat/Lon" and "Apply Shift".
    6.  Move the mouse over the map for coordinates; click to mark.
    7.  Use "Go"/"GE" for external viewing.
    8.  Press "Save Map View" to save a PNG snapshot.
*   **Use Case 3: Coordinate Analysis and Google Earth Integration**
    1.  Identify points of interest via SAR/Map mouse or SAR center display.
    2.  Use "Go" for Google Maps or "GE" for a focused Google Earth view.
    3.  For a comprehensive view, press "GE All" to generate and open a composite KML.
*   **Use Case 4: Recording SAR Data for Offline Analysis**
    1.  Ensure `tifffile` library is installed.
    2.  Check "Record SAR".
    3.  Raw SAR images will be saved as GeoTIFFs in `sar_images/`.
    4.  Uncheck to stop recording. Files can be opened in GIS software (e.g., QGIS).
*   **Use Case 5: Using Test Mode**
    1.  Check "Test Image".
    2.  The application will display internally generated, scrolling SAR and MFD images.
    3.  SAR/MFD parameters remain adjustable. The map overlay will use default/last valid GeoInfo.
    4.  Uncheck to return to normal mode.
*   **Use Case 6: Inspecting SAR Metadata**
    1.  Check "Show SAR Metadata".
    2.  A panel will appear displaying formatted `ImageLeaderData` from the latest SAR image.
    3.  Uncheck to hide.

### 7. Requirements

*   Python 3.x (developed with 3.10+ in mind)
*   Required Python Packages (install via `pip install -r requirements.txt` if a file is 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)

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

### 9. Configuration

Most operational parameters can be adjusted by editing the `controlpanel/config.py` file using a standard text editor.

**Applying Changes:**

1.  Open `controlpanel/config.py`.
2.  Modify the desired constant(s) (e.g., `DEFAULT_SER_PORT`, `ENABLE_MAP_OVERLAY`, `DEBUG_RECEIVER_PACKETS`).
3.  Save the `config.py` file.
4.  **Restart the Control Panel application** (close it if running, then run `python -m controlpanel` again) for the changes to take effect.

This file contains settings for:
*   Network IP address and Port.
*   Default SAR/MFD display settings.
*   Map provider settings (service name, API key, cache, etc.).
*   SAR recording path and limits.
*   KML generation options.
*   Logging levels and detailed debug flags (see next section).

### 10. Debugging Configuration

The application uses Python's standard `logging` module. You can control the verbosity and focus of the logs by adjusting settings in `controlpanel/config.py`.

**1. Logging Levels:**

*   `LOG_ROOT_LEVEL`: Sets the *minimum level* the logger will **process**. Messages below this level are ignored. For debugging with flags, this **must** be set to `logging.DEBUG`.
    ```python
    LOG_ROOT_LEVEL = logging.DEBUG # Recommended for debugging
    ```
*   `LOG_HANDLER_LEVEL`: Sets the *minimum level* that will be **output** to the console. To allow the debug flags below to work, set this also to `logging.DEBUG`.
    ```python
    LOG_HANDLER_LEVEL = logging.DEBUG # Required to see DEBUG messages controlled by flags
    ```

**2. Debug Flags (`DEBUG_*`):**

These boolean flags (`True` or `False`) control whether specific categories of `DEBUG`-level messages are shown *if both `LOG_ROOT_LEVEL` and `LOG_HANDLER_LEVEL` are set to `logging.DEBUG`*. Set a flag to `True` to see detailed messages from that part of the application.

| Flag Name                  | Purpose                                                                 | Default |
| :------------------------- | :---------------------------------------------------------------------- | :------ |
| `DEBUG_APP_LIFECYCLE`      | Core application start/stop steps, state init, UI setup.                | `False` |
| `DEBUG_APP_CALLBACKS`      | Entry/exit/values for general UI callbacks (sliders, buttons).          | `False` |
| `DEBUG_APP_QUEUE_PROCESSING` | When items are dequeued and processed by app queue handlers.            | `False` |
| `DEBUG_APP_IMG_PROCESSING` | Steps within central image processing (in ImagePipeline).               | `False` |
| `DEBUG_APP_TEST_MODE`      | Test image generation, scheduling, updates, mode switching logic.       | `False` |
| `DEBUG_APP_GEO_CALC`       | Mouse geo-coordinate calculation steps and queueing.                    | `False` |
| `DEBUG_APP_MFD_PARAMS`     | MFD parameter UI callbacks and MFD LUT recalculation.                   | `False` |
| `DEBUG_APP_STATUS`         | Status bar update logic and formatting details.                         | `False` |
| `DEBUG_APP_TRIGGER`        | Logs when internal update triggers are called.                          | `False` |
| `DEBUG_RECEIVER_LOOP`      | General events in the main UDP receiver loop.                           | `False` |
| `DEBUG_RECEIVER_PACKETS`   | **(High Volume)** Logs header info for every raw SFP packet received.     | `False` |
| `DEBUG_RECEIVER_REASSEMBLY`| Fragment reassembly logic, buffer allocation, worker task steps.        | `False` |
| `DEBUG_RECEIVER_GEO`       | Raw GeoInfo/Metadata extraction details.                                | `False` |
| `DEBUG_RECEIVER_ACK`       | Details of sending SFP ACK packets.                                     | `False` |
| `DEBUG_RECEIVER_CLEANUP`   | Transaction cleanup actions.                                            | `False` |
| `DEBUG_DISPLAY_MANAGER`    | Display window (SAR, MFD, Map) creation, updates, callbacks.            | `False` |
| `DEBUG_UTILS`              | Logs from general utility functions.                                    | `False` |
| `DEBUG_NETWORK`            | Logs from network utility functions.                                    | `False` |
| `DEBUG_IMAGE_PROCESSING`   | Logs from image processing functions.                                 | `False` |
| `DEBUG_IMAGE_RECORDER`     | Logs from the GeoTIFF recording module.                                 | `True`  |
| `DEBUG_MAP_DETAILS`        | Map tile fetching/caching, coordinate calculations, overlay operations. | `False` |

**Practical Debugging Examples:**

*   **No data received?** Set `LOG_ROOT_LEVEL` & `LOG_HANDLER_LEVEL` to `DEBUG`. Enable `DEBUG_NETWORK`, `DEBUG_RECEIVER_LOOP`, and temporarily `DEBUG_RECEIVER_PACKETS`.
*   **SAR image looks wrong?** Enable `DEBUG_IMAGE_PROCESSING`, `DEBUG_APP_CALLBACKS`, `DEBUG_APP_IMG_PROCESSING`.
*   **Map overlay issues?** Enable `DEBUG_MAP_DETAILS`, `DEBUG_DISPLAY_MANAGER`, `DEBUG_RECEIVER_GEO`.
*   **Too much log output?** Set `LOG_HANDLER_LEVEL = logging.INFO` or specific `DEBUG_*` flags to `False`.

### 11. FAQ & Troubleshooting

*   **Q: No map window appears, even if `ENABLE_MAP_OVERLAY` is `True`.**
    *   **A:**
        1.  **Check Libraries:** Ensure `Pillow`, `mercantile`, `pyproj`, and `requests` are installed. Check console logs at startup for `ImportError` messages related to these.
        2.  **GeoInfo:** The map requires valid georeferencing information from the SAR data (`GEO_DATA` block). If this is missing or invalid, the map update might be skipped. Check logs for `Skipping: Invalid GeoInfo`.
        3.  **Online Access:** If map tiles are not cached, ensure `config.ENABLE_ONLINE_MAP_FETCHING = True` and the application has internet access.
        4.  **Configuration:** Double-check `MAP_SERVICE_PROVIDER` in `config.py` (should be `"osm"` for OpenStreetMap).
        5.  **Debug Logs:** Enable `DEBUG_MAP_DETAILS` and `DEBUG_DISPLAY_MANAGER` to see detailed logs from map components.
*   **Q: The SAR/MFD/Map window appears briefly and then closes, or doesn't appear.**
    *   **A:** This can happen if there's an early error in the OpenCV display loop or if another part of the application crashes.
        1.  Check the console for any Python exceptions immediately after the window disappears.
        2.  Enable `DEBUG_DISPLAY_MANAGER` to see logs from window creation and `imshow` calls.
        3.  Ensure your OpenCV installation includes GUI support (it usually does with `opencv-python`).
*   **Q: Coordinates displayed in "Info Display" are "N/A" or "Error".**
    *   **A:**
        1.  For SAR-related coordinates (Center, Mouse): This usually means the incoming SAR data does not have valid georeferencing information, or there was an error during its processing. Enable `DEBUG_RECEIVER_GEO` and `DEBUG_APP_GEO_CALC`.
        2.  For Map Mouse: The map itself might not have loaded correctly, or there's an issue with the `mercantile` library converting pixel to geo. Enable `DEBUG_MAP_DETAILS`.
*   **Q: KML files are generated but Google Earth doesn't show the SAR image overlay correctly (e.g., stretched, wrong place).**
    *   **A:**
        1.  Ensure the `lxml` library is installed (`pip install lxml`). This enables the more accurate `gx:LatLonQuad` KML tag.
        2.  Verify that the `GEO_DATA` in the incoming SAR packets is accurate, especially the `ORIENTATION`, `SCALE_X`, `SCALE_Y`, and center `LATITUDE`/`LONGITUDE`. Errors here propagate to KML. Enable `DEBUG_RECEIVER_GEO`.
        3.  Check `DEBUG_UTILS` for logs during KML generation, specifically related to corner calculation (`_calculate_geo_corners_for_kml`).
*   **Q: GeoTIFF files are recorded but cannot be opened or georeferencing is incorrect in GIS software.**
    *   **A:**
        1.  Ensure `tifffile` library is installed.
        2.  Enable `DEBUG_IMAGE_RECORDER` to see detailed logs about tag creation and writing.
        3.  Verify the accuracy of `GEO_DATA` from the SAR packets.
        4.  The affine transform calculation relies on the correctness of scale, orientation, and reference point from `GEO_DATA`.
*   **Q: Application is slow or unresponsive.**
    *   **A:**
        1.  **High Volume Debug Logs:** If many `DEBUG_*` flags are `True` (especially `DEBUG_RECEIVER_PACKETS`), logging to the console can slow down the application. Reduce debug verbosity.
        2.  **Queue Sizes:** If internal queues (`DEFAULT_SAR_QUEUE`, `DEFAULT_MFD_QUEUE`) are too small and data arrival rate is high, processing might lag. This is less likely to cause unresponsiveness but can lead to dropped frames.
        3.  **Resource Intensive Operations:** Map stitching and SAR overlay warping can be CPU-intensive. If these happen very frequently on a slow machine, it might impact responsiveness.

### 12. Screenshots

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

### 13. License

<!-- Specify your chosen license here. Based on the "AS IS" disclaimer, MIT or Apache 2.0 might be suitable. -->
Example: This project is licensed under the MIT License - see the LICENSE.md file for details (if you add one).