# hkustenterprize/rm2025-radar-algorithm architecture

> Architecture diagram of the GitHub repository hkustenterprize/rm2025-radar-algorithm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hkustenterprize/rm2025-radar-algorithm
- Repository: https://github.com/hkustenterprize/rm2025-radar-algorithm

## Overview

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.

Main entry points: [`main_event_loop.py`](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/main_event_loop.py) (Event Loop), [`config`](https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/config) (Config), [`tracker/CascadeMatchTracker/tracker.py`](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/tracker/CascadeMatchTracker/tracker.py) (Cascade Tracker), [`transform/ray_renderer.py`](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/transform/ray_renderer.py) (Ray Renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["Main<br/>entrypoint<br/>[main.py]"]
  node_event_loop["Event Loop<br/>orchestrator<br/>[main_event_loop.py]"]
  node_ui["Interface<br/>ui/calibration"]
  node_config["Config<br/>runtime settings"]
end

subgraph group_hardware["Hardware"]
  node_camera["Hik Camera<br/>camera driver"]
  node_mock_camera["Mock Camera<br/>camera mock<br/>[mock_hik.py]"]
  node_referee["Referee IO<br/>serial protocol"]
end

subgraph group_perception["Perception"]
  node_vehicle_model["Vehicle Model<br/>detector"]
  node_armor_model["Armor Model<br/>detector<br/>[armor_detector.py]"]
  node_digit_model["Digit Classifier"]
  node_armor_light["Light Classifier"]
  node_pfa_yolo["PFA YOLOv5<br/>detector framework"]
end

subgraph group_tracking["Tracking"]
  node_cascade_tracker["Cascade Tracker<br/>multi-target tracker<br/>[tracker.py]"]
  node_tracker_kalman(("Kalman<br/>motion filter<br/>[kalman.py]"))
  node_guess_pts(("Guess Points<br/>occlusion logic<br/>[guess_pts.py]"))
end

subgraph group_geometry["Geometry"]
  node_solvepnp["SolvePnP<br/>extrinsics<br/>[solvepnp.py]"]
  node_ray_renderer["Ray Renderer<br/>3d localization<br/>[ray_renderer.py]"]
  node_solidwork2uwb["Field Transform<br/>coordinate transform<br/>[solidwork2uwb.py]"]
  node_field_mesh[("Field Mesh<br/>arena asset")]
end

node_main -->|"launches"| node_ui
node_ui -->|"hands off"| node_event_loop
node_event_loop -->|"captures"| node_camera
node_event_loop -.->|"or mocks"| node_mock_camera
node_event_loop -->|"detects"| node_vehicle_model
node_vehicle_model -->|"crops"| node_armor_model
node_armor_model -->|"features"| node_armor_light
node_armor_light -->|"identifies"| node_digit_model
node_event_loop -.->|"alt path"| node_pfa_yolo
node_event_loop -->|"tracks"| node_cascade_tracker
node_cascade_tracker -->|"predicts"| node_tracker_kalman
node_cascade_tracker -->|"recovers"| node_guess_pts
node_event_loop -->|"calibrates"| node_solvepnp
node_solvepnp -->|"feeds"| node_ray_renderer
node_ray_renderer -->|"casts on"| node_field_mesh
node_ray_renderer -->|"maps to"| node_solidwork2uwb
node_event_loop -->|"exchanges"| node_referee
node_config -->|"drives"| node_main
node_config -->|"tunes"| node_event_loop
node_config -->|"selects"| node_camera

click node_main "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/main.py"
click node_event_loop "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/main_event_loop.py"
click node_ui "https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/interface"
click node_camera "https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/driver/hik_camera"
click node_mock_camera "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/driver/hik_camera/mock_hik.py"
click node_referee "https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/driver/referee"
click node_vehicle_model "https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/model/yolov12"
click node_armor_model "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/model/armor_detector.py"
click node_digit_model "https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/model/digit_classifier"
click node_armor_light "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/model/armor_light_classifier.py"
click node_pfa_yolo "https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/model/pfa_yolov5"
click node_cascade_tracker "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/tracker/CascadeMatchTracker/tracker.py"
click node_tracker_kalman "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/tracker/CascadeMatchTracker/kalman.py"
click node_guess_pts "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/tracker/CascadeMatchTracker/guess_pts.py"
click node_solvepnp "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/transform/solvepnp.py"
click node_ray_renderer "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/transform/ray_renderer.py"
click node_solidwork2uwb "https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/transform/solidwork2uwb.py"
click node_field_mesh "https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/field"
click node_config "https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/config"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_event_loop,node_ui,node_config toneBlue
class node_camera,node_mock_camera,node_referee toneAmber
class node_vehicle_model,node_armor_model,node_digit_model,node_armor_light,node_pfa_yolo toneMint
class node_cascade_tracker,node_tracker_kalman,node_guess_pts toneRose
class node_solvepnp,node_ray_renderer,node_solidwork2uwb,node_field_mesh toneIndigo
```

## Components

### Runtime

Operator entrypoints and orchestration

- [Main](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/main.py): entrypoint · Starts UI then inference · `main.py`
- [Event Loop](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/main_event_loop.py): orchestrator · Runs the operational inference loop · `main_event_loop.py`
- [Interface](https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/interface): ui/calibration · Interactive setup and display boundary · `interface`
- [Config](https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/config): runtime settings · Central YAML-driven parameters and device settings · `config`

### Hardware

Camera and referee device interfaces

- [Hik Camera](https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/driver/hik_camera): camera driver · Hardware capture adapter for industrial cameras · `driver/hik_camera`
- [Mock Camera](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/driver/hik_camera/mock_hik.py): camera mock · Offline capture substitute · `driver/hik_camera/mock_hik.py`
- [Referee IO](https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/driver/referee): serial protocol · Referee system transport and CRC stack · `driver/referee`

### Perception

Detection and classification models

- [Vehicle Model](https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/model/yolov12): detector · Primary robot detection stage · `model/yolov12`
- [Armor Model](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/model/armor_detector.py): detector · Armor region detector · `model/armor_detector.py`
- [Digit Classifier](https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/model/digit_classifier): classifier · Armor digit and pattern recognition · `model/digit_classifier`
- [Light Classifier](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/model/armor_light_classifier.py): classifier · Specialized armor feature classifier · `model/armor_light_classifier.py`
- [PFA YOLOv5](https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/model/pfa_yolov5): detector framework · Alternate YOLO detector implementation · `model/pfa_yolov5`

### Tracking

Multi-target association and state estimation

- [Cascade Tracker](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/tracker/CascadeMatchTracker/tracker.py): multi-target tracker · Associates detections into persistent targets · `tracker/CascadeMatchTracker/tracker.py`
- [Kalman](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/tracker/CascadeMatchTracker/kalman.py): motion filter · Tracks target motion over time · `tracker/CascadeMatchTracker/kalman.py`
- [Guess Points](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/tracker/CascadeMatchTracker/guess_pts.py): occlusion logic · Predicts likely positions during missed detections · `tracker/CascadeMatchTracker/guess_pts.py`

### Geometry

Calibration and field projection

- [SolvePnP](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/transform/solvepnp.py): extrinsics · Camera pose and calibration solving · `transform/solvepnp.py`
- [Ray Renderer](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/transform/ray_renderer.py): 3d localization · Ray-casting based field localization · `transform/ray_renderer.py`
- [Field Transform](https://github.com/hkustenterprize/rm2025-radar-algorithm/blob/main/transform/solidwork2uwb.py): coordinate transform · Maps field coordinates to radar/UWB frame · `transform/solidwork2uwb.py`
- [Field Mesh](https://github.com/hkustenterprize/rm2025-radar-algorithm/tree/main/field): arena asset · Arena geometry used for projection and localization · `field`

## Connections

- Main → Interface: launches · Main starts the operator-facing setup layer
- Interface → Event Loop: hands off · Calibration phase transitions into inference
- Event Loop → Hik Camera: captures · Live camera mode feeds frames into the loop
- Event Loop → Mock Camera: or mocks · Offline mode can substitute recorded or mock input
- Event Loop → Vehicle Model: detects · Full-frame robot candidates are detected first
- Vehicle Model → Armor Model: crops · Vehicle ROIs are refined into armor candidates
- Armor Model → Light Classifier: features · Armor appearance is classified further
- Light Classifier → Digit Classifier: identifies · Digit classifier infers robot identity/team
- Event Loop → PFA YOLOv5: alt path · Alternate YOLO stack supports detection workflows
- Event Loop → Cascade Tracker: tracks · Frame detections are fused into persistent targets
- Cascade Tracker → Kalman: predicts · Kalman filtering estimates target motion
- Cascade Tracker → Guess Points: recovers · Guess points bridge short occlusions
- Event Loop → SolvePnP: calibrates · Camera pose is estimated for 3D mapping
- SolvePnP → Ray Renderer: feeds · Pose parameters drive ray-based localization
- Ray Renderer → Field Mesh: casts on · Field geometry constrains localization rays
- Ray Renderer → Field Transform: maps to · Localized points are converted to competition coordinates
- Event Loop → Referee IO: exchanges · Battle-state or referee data can be sent/received
- Config → Main: drives · Startup and runtime mode selection are configuration-driven
- Config → Event Loop: tunes · Detector, tracker, and device parameters are centralized here
- Config → Hik Camera: selects · Device settings determine capture backend behavior