双目测距方案重构与其他小修改

utils/README.md

@@ -1,9 +1,12 @@
-# utils —— reference-c++ 两个子项目的 Python 移植
+# utils —— reference-c++ 的 Python 移植 + 双目测距新实现
 
 将 `reference-c++/` 下的 `target_tracker`（多目标追踪过滤器）与
 `visual_track_control`（视觉跟踪控制律）移植为 Python，**两包互不依赖**
 （唯一的数据转换点在胶水层 demo）。
 
+另有 `stereo_ranger`（双目稀疏目标测距）：**按规格新实现**（非 C++ 移植），
+规格 `docs/双目测距技术路线.md`；同样与既有两包互不依赖。
+
 ## 目录结构
 
 ```
@@ -12,19 +15,24 @@ utils/
 │   └── README.md              # 接口清单 + C++ 差异
 ├── visual_track_control/      # 包 2：三通道控制律 + MAVSDK offboard 网关
 │   └── README.md              # 接口清单 + C++ 差异
+├── stereo_ranger/             # 包 3：双目稀疏目标测距（纯标准库，无第三方依赖）
+│   └── README.md              # 接口清单 + 与规格的偏差
 ├── demo_track_control.py      # 胶水层集成演示（模拟检测 → 追踪 → 控制律 → 发送）
+├── demo_stereo_ranger.py      # 双目测距演示（合成框对，六场景，无硬件）
 ├── config/track_control.json  # 控制律配置（拷贝自 reference-c++）
-├── tests/                     # pytest 测试（对应 C++ 全部 13 个测试文件）
-│   ├── target_tracker/        # 27 条
-│   └── visual_track_control/  # 78 条
-├── conftest.py                # 保证可从任意工作目录导入两包
+├── config/stereo_ranger.json  # 双目测距配置（占位值，待标定回填）
+├── tests/                     # pytest 测试
+│   ├── target_tracker/        # 28 条（对应 C++ 测试文件）
+│   ├── visual_track_control/  # 81 条（对应 C++ 测试文件）
+│   └── stereo_ranger/         # 111 条（规格 §11.4 构件级 + 全流程）
+├── conftest.py                # 保证可从任意工作目录导入三包
 └── pytest.ini                 # 收集 *_test.py 命名（与 C++ 测试文件名对齐）
 ```
 
 ## 环境
 
 conda env `pytorch`（`D:\program file\conda\envs\pytorch`），Python 3.12，
-依赖：numpy、mavsdk、pytest。
+依赖：numpy、mavsdk、pytest（stereo_ranger 仅标准库）。
 
 ## 运行测试
 
@@ -33,8 +41,9 @@ 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）。
+220 条测试全部通过：109 条 C++ 移植用例（含 §9.4 六条硬验收、A1/A2/A4
+回归、PID anti-windup C1、超龄 C4、首拍限幅 S6）+ 111 条 stereo_ranger
+（合成框对驱动，无需真实图像/硬件）。
 
 ## 运行演示
 
@@ -44,11 +53,17 @@ python utils/demo_track_control.py --speedup 10
 
 # MAVSDK 实发（需飞控/SITL 在 udp://:14540）
 python utils/demo_track_control.py --transport mavsdk
+
+# 双目测距（合成框对，离线，无相机/飞控）
+python utils/demo_stereo_ranger.py
 ```
 
-时间线 13 s（20 Hz）：正常跟踪 6 s（vx 从零渐变 → 逼近限速 3 m/s）→
+控制链路时间线 13 s（20 Hz）：正常跟踪 6 s（vx 从零渐变 → 逼近限速 3 m/s）→
 目标消失 4 s（Coast 预测，60 帧后轨道判亡）→ 判零速刹车 3 s。
 
+双目演示六场景：逼近（三道有效性门 + 滤波）→ 远场域外（方位仍发布）→
+单目退化 → 非同帧拒收 → 一致性降级/判无效 → 多目标贪心配对。
+
 ## 移植约定
 
 - MAVLink 部分改为 **MAVSDK 语义映射**（offboard API，非字节透传），三分支
@@ -56,3 +71,6 @@ python utils/demo_track_control.py --transport mavsdk
 - 测试逐条移植 C++ gtest 断言（`EXPECT_DOUBLE_EQ` → 精确 `==`，
   `EXPECT_NEAR` → `pytest.approx`）；MAVSDK 部分因无 SITL/实机，仅 mock 验证。
 - 行为修复项（C1/C2/C4、A1/A2/A4、S6）在测试文件头注释中标注对应章节。
+- `stereo_ranger` 不是移植：按规格五步流程新实现，与规格的偏差（越界=有效性门、
+  视差域权威、补充 consistency_jump_px/isolation_gate_px 等）见其包 README；
+  ⚠ 全部数值为占位值，标定完成前不得作为飞行控制决策依据。