hkustenterprize/rm2025-radar-algorithm

1. System purpose and top-level shape

This repository implements a RoboMaster “radar station” perception-and-tracking system. The core loop is: acquire camera frames, detect robots and armor plates, classify identities, project detections into 3D field coordinates, track targets over time, and emit battle-state data for downstream use.

2. Entry points and runtime modes

The main runtime starts from main.py, with main_event_loop.py handling the operational inference loop after the UI/calibration phase. The README indicates two source modes controlled by config/params.yaml: recorded video inference or live camera streaming.

3. Human-in-the-loop UI and calibration boundary

interface/ contains the calibration and display layer. This subsystem is responsible for interactive setup, selecting/validating parameters, and likely triggering the transition into inference. It acts as the boundary between operator actions and the autonomous perception loop.

4. Camera acquisition subsystem

driver/hik_camera/ is the hardware interface for Hikrobot industrial cameras. It includes the vendor SDK bindings (MvImport/), a real camera driver (hik.py), and a mock driver (mock_hik.py) for offline development. This boundary isolates device-specific capture logic from the rest of the pipeline.

5. Perception models are split into multiple stages

model/ contains the detection/classification stack. The repo supports YOLO-based detectors (model/yolov12/, model/pfa_yolov5/) and a dedicated armor pipeline (model/armor_detector.py). The README describes a coarse-to-fine flow: vehicle detection, armor detection, then digit/pattern classification in model/digit_classifier/.

6. Detection and classification data flow

The perception pipeline first finds candidate robot regions in the full frame, then crops region-of-interest images for armor detection, and finally classifies the armor pattern to infer robot type/team. This staged design trades a larger global detector for smaller specialized models to keep latency manageable.

7. Tracking subsystem

tracker/CascadeMatchTracker/ implements the multi-target tracker. It combines detection fusion, Hungarian matching, Kalman filtering, and a target state machine. The tracker is the boundary between raw frame-level detections and persistent object identities across time.

8. Guessing and occlusion handling

The tracker includes guess_pts.py and associated logic for “guess points,” which the README describes as predicting likely target locations during short occlusions or missed detections. This is important because the system is designed for competitive scenes with frequent blocking and partial visibility.

9. 3D geometry and field mapping

transform/ contains the geometric calibration and projection layer. solvepnp.py handles camera pose/extrinsic calibration, ray_renderer.py implements the ray-casting-based 3D localization demo, and solidwork2uwb.py converts field coordinates into the radar/UWB coordinate frame used by the competition workflow.

10. Field model assets

field/ stores the 3D meshes for different RoboMaster arenas (.PLY files) and is a key dependency for the ray-based projection method. Unlike a planar homography pipeline, this repo’s localization depends on an explicit field mesh and calibrated camera parameters.

11. Referee/serial communications

driver/referee/ is a separate hardware communication stack for the referee system, including serial protocol, CRC, and USB/serial transport. This suggests the application can exchange competition state with external devices or use referee data as another input/output boundary.

12. Configuration and deployment

config/ centralizes runtime behavior: device settings, detector/tracker parameters, training configs, and calibration points. utils/config.py likely normalizes YAML into runtime args. run_scripts/ provides operational entry points for camera testing, serial loopback debugging, and full system launch.

13. Model conversion and deployment optimization

utils/convert_pt2tensorrt.py converts trained YOLO weights into TensorRT, which matters because the README emphasizes real-time inference on NVIDIA GPUs. This indicates the deployment path is optimized for low-latency edge execution rather than cloud inference.

14. Key architectural boundary

The cleanest diagram boundary is:

hardware inputs (camera, referee system) → perception models → tracking/state estimation → geometric projection into field coordinates → UI/output. The system is modular, with each stage isolated by config and adapter layers so the same core logic can run against real hardware or mocks/offline inputs.