VALLONGOL/SXXXXXXX_ControlPanel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
9bf91200de
SXXXXXXX_ControlPanel/doc/English-Manual.md
VALLONGOL 30be7ea111 update manual
2025-05-07 15:09:00 +02:00

18 KiB
Raw Blame History

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: 
    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. 
    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. 
    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

13. License

Example: This project is licensed under the MIT License - see the LICENSE.md file for details (if you add one).