### **User Manual (English)**

#### 1. Introduction

This document describes the usage of the "Control Panel" application, designed to visualize, process, and interact with SAR (Synthetic Aperture Radar) and MFD (Multi-Functional Display) image data streams received via UDP network. The application also allows integration with geographic maps, generation of KML files for Google Earth, and recording of SAR images.

#### 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 predefined 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.
*   **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 and Initial Overview

1.  **Launch:** Execute the main Python script (presumably `ControlPanel.py` or a compiled executable).
2.  **Windows:** Upon launch, the application will open several windows:
    *   **Control Panel:** The main window containing 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 Overview (Control Panel Window)

The main window is divided into logical sections:

*   **SAR Parameters:**
    *   `Test Image Checkbox:` Toggles Test Mode on/off.
    *   `Record SAR Checkbox:` Toggles SAR GeoTIFF file recording on/off.
    *   `Size Combobox:` Selects the downscaling factor for SAR image display (e.g., "1:2" shows the image at half its original resolution).
    *   `Palette Combobox:` Selects the color map to apply to the SAR image (e.g., GRAY, JET, HOT).
    *   `Contrast Slider:` Adjusts the contrast of the SAR image.
    *   `Brightness Slider:` Adjusts the brightness of the SAR image.
    *   `Show SAR Metadata Checkbox:` Shows/Hides the side panel displaying raw metadata received for the current SAR image.
*   **MFD Parameters:**
    *   `Intensity Slider (per category):` Adjusts the intensity (brightness) of specific MFD symbol categories (Occlusion, Cat A, Cat B, etc.).
    *   `Color Button (per category):` Opens a dialog to choose the RGB color associated with a specific MFD category.
    *   `Color Preview Label:` Shows the currently selected color for the category.
    *   `Raw Map Slider:` Adjusts the maximum intensity of MFD raw map pixels (values 32 to 255).
*   **Map Parameters:**
    *   `Map Display Size Combobox:` Selects a scaling factor to enlarge or shrink the map window relative to its calculated base size.
    *   `Save Map View Button:` Saves the current view of the "Map Overlay" window (including overlays, scale bar, marker) to a PNG image file.
    *   `Show SAR Overlay on Map Checkbox:` Shows/Hides the SAR image superimposed on the base map.
    *   `SAR Overlay Alpha Slider:` Adjusts the transparency of the SAR overlay (0.0 = transparent, 1.0 = opaque).
    *   `SAR Shift (deg) Inputs:` Fields to enter a manual shift (offset) in decimal degrees of latitude and longitude to apply to the SAR overlay's position on the map.
    *   `Apply Shift Button:` Applies the entered shift to the SAR overlay on the map.
*   **Info Display:**
    *   `SAR Center:` Displays the geographic coordinates (Lat/Lon DMS) of the current SAR image center.
    *   `Image Orient:` Displays the orientation (in degrees) of the current SAR image.
    *   `Image Size:` Displays the estimated geographic dimensions (km) of the current SAR image.
    *   `SAR Mouse:` Displays the geographic coordinates (Lat/Lon DMS) corresponding to the cursor's position over the SAR window.
    *   `Map Mouse:` Displays the geographic coordinates (Lat/Lon DMS) corresponding to the cursor's position over the Map Overlay window.
    *   `Go Button (next to coordinates):` Opens the corresponding location in Google Maps in the default web browser.
    *   `GE Button (next to coordinates):` Opens Google Earth Pro (if installed) centered on the corresponding location with a placemark.
    *   `Stats Drop:` Shows statistics about packets dropped from various internal queues.
    *   `Incomplete:` Shows statistics about incomplete SAR/MFD image receptions.
    *   `GE All Button:` Generates a composite KML file including points (SAR Center, SAR Mouse, Map Mouse), the SAR footprint boundary, and the processed SAR image overlayed on the 3D terrain; then attempts to open it with Google Earth Pro.
*   **Metadata Panel (Optional):**
    *   A separate panel that appears/disappears to the right of the main control panel when "Show SAR Metadata" is checked/unchecked.
    *   Displays a formatted textual representation of the raw metadata contained in the header of the current SAR image.
*   **Status Bar (Bottom):**
    *   Shows the current mode (e.g., "Network", "Test Mode", "Local Mode"), map status ("MapOn"), and estimated FPS (Frames Per Second) for MFD and SAR.

#### 5. Detailed Functionalities

*   **SAR/MFD Visualization:** Received (or test) images are processed and displayed in their respective OpenCV windows.
*   **SAR Adjustment:** Modifying contrast, brightness, and palette alters the appearance of the image in the SAR window in real-time. Changing the size updates the resolution of the SAR window.
*   **MFD Adjustment:** Modifying category intensity and color alters the appearance of symbols in the MFD window in real-time.
*   **SAR/Map Mouse Interaction:** Moving the mouse over the SAR or Map Overlay windows displays the corresponding geographic coordinates in the "Info Display" panel. A left-click on the SAR or Map window places a red cross marker and updates the coordinates.
*   **SAR Overlay Shift:** Useful for manually correcting misalignments between the SAR image and the base map due to inaccuracies in the received georeferencing data. Enter values in decimal degrees and press "Apply Shift".
*   **External Links (Go/GE):** Allow quick visualization of specific points (image center, mouse location) on Google Maps or Google Earth.
*   **Composite KML (GE All):** Creates a single KML file for Google Earth showing points of interest, the SAR geographic footprint, and the SAR image itself overlayed on the 3D terrain. Uses `<gx:LatLonQuad>` (if `lxml` is installed) for precise image mapping.
*   **GeoTIFF Recording:** When "Record SAR" is active, every received *raw* SAR image is saved in the background as a `.tif` file in the `sar_images` subfolder. These files contain original pixel data and georeferencing metadata (requires `tifffile`). Older files are automatically deleted beyond a configured limit.
*   **Metadata Viewing:** Allows inspection of the raw values contained in the SAR image header, useful for debugging or in-depth analysis.

#### 6. Common Workflows (Use Cases)

*   **Use Case 1: Basic Viewing (Network Mode)**
    1.  Launch the application. Ensure the UDP receiver is listening on the correct IP/port (visible in the Status Bar).
    2.  Observe the SAR and MFD windows populating with received data.
    3.  Adjust SAR parameters (contrast, brightness, palette) to optimize SAR visualization.
    4.  Adjust MFD parameters (intensity, colors) if needed.
    5.  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 (if not, modify `config.py` and restart).
    2.  Wait for the initial map to load in the Map Overlay window.
    3.  Enable "Show SAR Overlay on Map" in the "Map Parameters" panel.
    4.  Observe the SAR image appear superimposed on the map.
    5.  Adjust the "SAR Overlay Alpha" slider to change the overlay's transparency.
    6.  If the overlay is not perfectly aligned with map features, enter small values (decimal degrees) in the "SAR Shift Lat/Lon" fields and press "Apply Shift" until alignment is satisfactory.
    7.  Move the mouse over the Map Overlay window to see the corresponding geographic coordinates in the Info panel.
    8.  Click on the map to place a marker and use the "Go"/"GE" buttons to view that point externally.
    9.  Press "Save Map View" to save a PNG snapshot of the map window.
*   **Use Case 3: Coordinate Analysis and Google Earth Integration**
    1.  Observe the SAR center coordinates or move the mouse over the SAR/Map windows to find a point of interest.
    2.  Use the "Go" buttons for a quick look at the location in Google Maps in your browser.
    3.  Use the "GE" buttons to open Google Earth focused on that specific point.
    4.  For a comprehensive view, press "GE All". This generates a KML file (`composite_*.kml`) in the `kml_output` folder containing points, the SAR footprint, and the SAR image overlayed on 3D terrain, then attempts to open it in Google Earth.
*   **Use Case 4: Recording SAR Data for Offline Analysis**
    1.  Ensure the `tifffile` library is installed.
    2.  Activate the "Record SAR" checkbox in the "SAR Parameters" panel.
    3.  The application will start saving every received raw SAR image as a GeoTIFF file in the `sar_images` subfolder.
    4.  Filenames will be timestamp-based (e.g., `YYYYMMDD_HHMMSS_ms_SAR_geo_img16.tif`).
    5.  To stop recording, uncheck the "Record SAR" checkbox.
    6.  GeoTIFF files can be opened with GIS software (e.g., QGIS) for later analysis.
*   **Use Case 5: Using Test Mode**
    1.  Activate the "Test Image" checkbox in the "SAR Parameters" panel.
    2.  The application will stop processing network data (if any) and start displaying internally generated SAR and MFD images.
    3.  The test images will scroll horizontally.
    4.  You can still adjust SAR (contrast, brightness, palette, size) and MFD (intensity, color) parameters to see their effect on the test images. The map overlay will not be meaningful in test mode (using default or last valid GeoInfo).
    5.  To return to normal mode (Network or Local), uncheck "Test Image".
*   **Use Case 6: Inspecting SAR Metadata**
    1.  Activate the "Show SAR Metadata" checkbox in the "SAR Parameters" panel.
    2.  An additional panel will appear to the right of the main controls.
    3.  This panel will display a formatted textual representation of the entire `ImageLeaderData` structure received with the most recent SAR image. Values are shown with units where known (e.g., radians and degrees).
    4.  Useful for verifying raw georeferencing values, dimensions, counters, etc.
    5.  Uncheck the checkbox to hide the panel.