SXXXXXXX_ControlPanel/.github/copilot-instructions.md

Control Panel — AI coding assistant quick guide

This file gives focused, actionable guidance for an AI coding agent to be immediately productive in this repository.

• Big picture: Desktop Tkinter app that receives SAR/MFD image streams via UDP (custom SFP), processes images, displays them in separate windows, optionally overlays SAR on a stitched map, records GeoTIFFs, and can export KML for Google Earth. See README.md for full feature list.

• Key entrypoints:

  • Start app: python -m controlpanel (runs controlpanel/main.py).
  • Main orchestrator: ControlPanelApp in controlpanel/app_main.py.

• State & patterns:

  • Centralized shared state lives in AppState (controlpanel/app_state.py). Prefer reading/updating via the provided methods (update_map_scale_factor, update_sar_overlay_shift, update_sar_parameters, etc.) rather than mutating attributes directly.
  • Inter-thread communication uses bounded queue.Queue instances created in ControlPanelApp (SAR, MFD, mouse, tkinter). Producers must use put_queue helpers in controlpanel/utils to avoid drops; consumers must handle full/drop counts tracked in AppState.
  • UI callbacks should schedule UI updates with root.after_idle(...) or push to tkinter_queue to avoid Tkinter thread issues.

• Network / payload flow:

  • Transport layer: SfpTransport (controlpanel/core/sfp_transport.py) receives UDP fragments.
  • Payload processing: ImagePayloadProcessor (controlpanel/core/receiver.py) reassembles and calls payload callbacks.
  • App registers handlers in _setup_network_receiver() mapping ord('S') -> SAR handler and ord('M') -> MFD handler. Example: see payload_handlers in controlpanel/app_main.py.

• Image pipeline & display:

  • Image normalization, palette application and LUT updates are coordinated in ImagePipeline and DisplayManager modules (controlpanel/core and controlpanel/gui/display.py). When adjusting visual params, call ControlPanelApp.update_brightness_contrast_lut() and update_mfd_lut() then trigger _trigger_sar_update() / _trigger_mfd_update().
  • MFD LUTs are created from state.mfd_params (see _initialize_mfd_params() in controlpanel/app_state.py).

• Map & geospatial integration:

  • Map features are optional and gated by config.ENABLE_MAP_OVERLAY and the presence of mercantile, pyproj, and Pillow. If map libs are missing the app will log and disable map modules (see MAP_MODULES_LOADED in controlpanel/app_main.py).
  • GeoElevation integration is dynamic: set GEOELEVATION_PROJECT_ROOT_PATH in controlpanel/config.py to point to a local GeoElevation project; the code will temporarily add the path to sys.path and import get_point_elevation.

• Configuration & logging:

  • Primary config lives in controlpanel/config.py. Many debug flags (e.g., DEBUG_RECEIVER_PACKETS, DEBUG_IMAGE_RECORDER) control filtered logging. LOG_ROOT_LEVEL and LOG_HANDLER_LEVEL control overall and handler levels; adjust flags for targeted verbosity.

• Developer workflows / run & debug tips:

  • Run locally: python -m controlpanel from repo root.
  • If using maps, ensure mercantile, pyproj, and Pillow are installed (check requirements.txt or wheel folder _req_packages). Missing map libs will result in graceful fallback with logs.
  • To reproduce image flows during development without a live UDP source, enable config.USE_LOCAL_IMAGES or ENABLE_TEST_MODE; the TestModeManager produces synthetic frames. Inspect controlpanel/core/test_mode_manager.py.
  • To debug import/runtime failures during startup, inspect console output: __main__.py prints critical errors before exiting.

• Project-specific conventions:

  • Prefer using controlpanel.utils helper functions (put_queue, decimal_to_dms, generate_sar_kml, open_google_maps) rather than reimplementing parsing/formatting logic.
  • Respect BGR ordering used widely for colors (OpenCV convention) — state and LUTs use BGR tuples.
  • Sizes: SAR raw shape is config.SAR_WIDTH x config.SAR_HEIGHT (2048x2048 by default) and MFD is 484x484 — many buffers assume these constants.

• Where to change common behaviors:

  • Network port/IP defaults: controlpanel/config.py (DEFAULT_SER_IP, DEFAULT_SER_PORT).
  • Map provider and caching: MAP_SERVICE_PROVIDER, MAP_CACHE_DIRECTORY in config.py and implementations in controlpanel/map/*.
  • SAR recording & KML output locations: DEFAULT_SAR_RECORDING_DIRECTORY and KML_OUTPUT_DIRECTORY in config.py.

• Files and modules to inspect first (quick tour):

  • controlpanel/app_main.py — lifecycle, wiring, queues, and callbacks.
  • controlpanel/app_state.py — canonical state and LUT logic.
  • controlpanel/config.py — toggles, sizes, debug flags, paths.
  • controlpanel/core/ (SFP transport, receiver, pipeline, recorder, test manager).
  • controlpanel/gui/ (UI widgets, display manager, status bar).

If anything is unclear or you want additional examples (e.g., sample unit tests, a focused walkthrough on the SFP reassembly or map stitching), tell me which area and I will expand this file with specific code snippets and references.