# 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](README.md) for full feature list. - **Key entrypoints:** - Start app: `python -m controlpanel` (runs [controlpanel/__main__.py](controlpanel/__main__.py)). - Main orchestrator: `ControlPanelApp` in [controlpanel/app_main.py](controlpanel/app_main.py). - **State & patterns:** - Centralized shared state lives in `AppState` ([controlpanel/app_state.py](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](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](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](controlpanel/app_main.py)). - GeoElevation integration is dynamic: set `GEOELEVATION_PROJECT_ROOT_PATH` in [controlpanel/config.py](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](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](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](controlpanel/app_main.py) — lifecycle, wiring, queues, and callbacks. - [controlpanel/app_state.py](controlpanel/app_state.py) — canonical state and LUT logic. - [controlpanel/config.py](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.