257 lines
18 KiB
Markdown
257 lines
18 KiB
Markdown
# 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: -->
|
|
<!--  -->
|
|
<!--  -->
|
|
|
|
### 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).
|
|
|