first commit

2026-09-02 15:13:13 +08:00
commit cb00322a50
107 changed files with 10918 additions and 0 deletions
@@ -0,0 +1,58 @@
+# utils —— reference-c++ 两个子项目的 Python 移植
+
+将 `reference-c++/` 下的 `target_tracker`（多目标追踪过滤器）与
+`visual_track_control`（视觉跟踪控制律）移植为 Python，**两包互不依赖**
+（唯一的数据转换点在胶水层 demo）。
+
+## 目录结构
+
+```
+utils/
+├── target_tracker/            # 包 1：卡尔曼滤波多目标追踪（无第三方硬依赖，仅 numpy）
+│   └── README.md              # 接口清单 + C++ 差异
+├── visual_track_control/      # 包 2：三通道控制律 + MAVSDK offboard 网关
+│   └── README.md              # 接口清单 + C++ 差异
+├── demo_track_control.py      # 胶水层集成演示（模拟检测 → 追踪 → 控制律 → 发送）
+├── config/track_control.json  # 控制律配置（拷贝自 reference-c++）
+├── tests/                     # pytest 测试（对应 C++ 全部 13 个测试文件）
+│   ├── target_tracker/        # 27 条
+│   └── visual_track_control/  # 78 条
+├── conftest.py                # 保证可从任意工作目录导入两包
+└── pytest.ini                 # 收集 *_test.py 命名（与 C++ 测试文件名对齐）
+```
+
+## 环境
+
+conda env `pytorch`（`D:\program file\conda\envs\pytorch`），Python 3.12，
+依赖：numpy、mavsdk、pytest。
+
+## 运行测试
+
+```bash
+cd utils
+"D:/program file/conda/envs/pytorch/python.exe" -m pytest -q
+```
+
+105 条测试全部通过（含 C++ 验收用例的逐条移植：§9.4 六条硬验收、A1/A2/A4
+回归、PID anti-windup C1、超龄 C4、首拍限幅 S6）。
+
+## 运行演示
+
+```bash
+# mock 传输（本地记录指令，无实机）
+python utils/demo_track_control.py --speedup 10
+
+# MAVSDK 实发（需飞控/SITL 在 udp://:14540）
+python utils/demo_track_control.py --transport mavsdk
+```
+
+时间线 13 s（20 Hz）：正常跟踪 6 s（vx 从零渐变 → 逼近限速 3 m/s）→
+目标消失 4 s（Coast 预测，60 帧后轨道判亡）→ 判零速刹车 3 s。
+
+## 移植约定
+
+- MAVLink 部分改为 **MAVSDK 语义映射**（offboard API，非字节透传），三分支
+  映射保留 C++ A2 回归语义，详见包 2 README。
+- 测试逐条移植 C++ gtest 断言（`EXPECT_DOUBLE_EQ` → 精确 `==`，
+  `EXPECT_NEAR` → `pytest.approx`）；MAVSDK 部分因无 SITL/实机，仅 mock 验证。
+- 行为修复项（C1/C2/C4、A1/A2/A4、S6）在测试文件头注释中标注对应章节。