code-test-drone/legacy/docs/双目相机模组到位作业指导.md

双目相机模组到位作业指导

定位：docs/ 下三份规格（《双目测距技术路线》《双目YOLO目标识别需求说明》 《视觉跟踪控制律技术路线》）回答"应该怎样、判据是什么"；本文回答"相机模组到货 之后按什么顺序做什么、每步怎么判通过、结果回填到哪里"。本文不新立判据—— 所有通过标准一律引用规格原文并注明章节。

适用范围：双目相机模组（含厂商标定数据）到货起，至《测距路线》§12.3 四条 红线解除为止。飞控/机载平台到位后的工作属《视觉跟踪控制律技术路线》§8 阶段 4~6， 本文只在阶段 6 交接。

编写状态（2026-09-14）：仓库内几何参数全部为占位值 （utils/config/stereo_ranger.json）、demo 素材为 AI 合成图，本文判据尚未在 任何真实设备上执行过。首次执行后请把实测偏差与踩坑回填本文，并去掉本行。

---

0. 一页速览

阶段	内容	出口判据（出处）	解除的阻塞
P0	开箱登记与数据清点	登记表（附录 A.1）填满；缺失项有替代方案	厂商数据可用性未知
P1	几何参数回填	fail-fast 校验通过 + 新有效域覆盖任务包线（§9.1/§11.2）	几何参数为占位
P2	校正质量核验	静态场景 |Δy| P95 ≤ 1 px（§12.1）	极线对齐不可信
P3	真实素材采集入库	覆盖 5/10/15/20/25 m 档、元数据齐（§2.3）	素材只有合成图
P4	测距真值验证	有效域内 δZ ≤ 2 m、趋势 ∝ Z²（§12.1）	数值从未对过真值
P5	阈值整定	§9 各表 ⚠ 全部替换为实测值（§12.2）	阈值全部占位
P6	台架/SITL 联动 → 解禁评审	控制联动场景全覆盖（§12.1）；§12.3 四条逐条勾选	红线未解除

依赖顺序：P0 → P1 → P2 → P3 → P4 → P5 → P6。P2 必须在 P1 之后（校正质量要在 正确内参下判读），P4 必须在 P3 之后（没有真实素材就没有真值比对）。

---

1. 阶段 0：开箱登记与数据清点

1.1 向厂商索取的清单

数据	用途	缺失时的替代方案	落位
校正后内参 fx_px/fy_px/cx_px/cy_px	§9.1 几何组，Z = F·B/D 的分母来源	自标定（张正友）；P2 判据不达标时本就要提前做	utils/config/stereo_ranger.json
基线 baseline_m（标称 + 实测公差）	§9.1；F·B 常量	卡尺/塞规实测，记录不确定度	同上
畸变系数与校正映射（remap maps）或"已做校正"的书面确认	§2.2 第 4 条：前端输出的是校正后图上的框	自标定 + 自建 remap 表	采集预处理（不在本仓）
出厂标定报告与不确定度	P1/P2 的判据依据，要存档	无报告 = 按未标定处理，走自标定	本文附录 A.1
分辨率 / 帧率 / 像素格式 / 位深	原生坐标系与算力预算（《需求说明》§5）	—	附录 A.1 + stereo_yolo.json 复核
同步方式与触发接口（sbs / 双流 / 硬触发）	§2.3 同帧契约的形态选择	sbs 优先（天然同曝光，§2.3）	采集端设计
机械图纸（安装接口、两目光轴平行度要求）	安装外参、换机型（P6）	—	附录 A.1

1.2 到货当天建议实测

1. 基线复核：卡尺/图纸比对标称值，偏差 >1% 时以实测为准并记录（F·B 直接决定距离标定）；
2. 同帧性验证：拍快速横向移动的手/笔，sbs 形态应为同一时刻；双流形态量化两路时间窗抖动并记录（§2.3 要求"残余时序抖动应记录供误差评估"）；
3. 分辨率与帧率实测：跑满声称帧率，记录实际值与丢帧情况（供 P5/P6 的算力预算）；
4. 图像质量目测：左右目曝光/增益是否一致（不一致会让同一目标两目置信度与框边缘不对称，污染视差取点）。

---

2. 阶段 1：几何参数回填

2.1 改哪些字段

只动 utils/config/stereo_ranger.json 的 5 个几何项：

fx_px, fy_px, cx_px, cy_px   ← 厂商校正后内参（注意：fx=fy=F 是校正后口径）
baseline_m                    ← 实测基线

utils/config/stereo_yolo.json 不含几何参数（输出框天然位于输入图的原生 坐标系，§4 配置一致性要求）——前端无需回填，只需复核 imgsz 与真实分辨率匹配。

视差域 disparity_min_px / disparity_max_px 不是标定数据，是任务决策项： 按任务近界 Z_near 反推 disparity_max_px = F·B / Z_near，按可测远界定 disparity_min_px。回填内参后 F·B 变化，两者的距离语义会平移，必须重算。

2.2 回填后必算的派生量（写进记录表）

派生量	公式（代码属性）	用途
F·B	fx_px × baseline_m（focal_baseline_px_m）	距离解算常量
z_min_m	F·B / disparity_max_px	近界（只读派生）
z_max_m	F·B / disparity_min_px	远界（只读派生）
z_error_budget_max_m	sqrt(max_delta_z_m × F·B)	误差预算门对应的最远距离（§7.2，δD 基准固定 1 px）

以上四项不是配置项，由 StereoConfig 只读派生（v1.0 冻结：视差域权威， 距离域派生，避免两处冗余互推舍入不一致，§6.4）。回填后手算一遍与程序输出比对， 作为回填正确性的一次交叉验证。

2.3 判据

1. fail-fast 校验通过：JSON 必须含全部 17 个键、无未知键、类型正确 （consistency_N_frames / consistency_M_frames / filter_reset_frames 必须是整数，3.5 或 true 会被拒）；取值约束：0 < disparity_min_px < disparity_max_px、 consistency_M_frames ≥ consistency_N_frames、0 < smooth_alpha ≤ 1、 cx_px/cy_px 非负、其余数值项一律为正（以 stereo_ranger/config.py 为准）；
2. 有效域覆盖任务包线：新的 z_min_m / z_max_m / z_error_budget_max_m 与任务的距离区间逐项比对，不达标时先改视差域/基线/机型（P6），不要迁就旧数值；
3. 记录回填前后的 diff 与批准人（附录 A.2）。

2.4 连带修改清单（容易漏，会导致测试变红）

受影响处	现象	处置
utils/tests/stereo_ranger/config_test.py::test_load_from_json_matches_defaults	必失败：该用例断言 JSON 内容与 StereoConfig() 占位默认值逐字段相等	改为"语义一致性"断言（域关系、派生恒等式、取值约束），或维护一份"当前标定值"副本单独比对；不要为了过测试而改 dataclass 默认值——默认值是单测的占位基准
utils/tests/stereo_yolo/config_test.py::test_load_from_json_matches_defaults	同上（仅当改动 stereo_yolo.json 时）	同上
docs/双目测距技术路线.md §9 各表的 ⚠ 标记	表格仍写占位值	回填为实测值并标注日期与来源（保持"以规格为准"）
utils/stereo_ranger/README.md、utils/stereo_yolo/README.md 的占位值表	同上	同步，并撤掉"占位红线"字样（或改为"已标定"）
utils/demo_stereo_ranger.py 的注释（F·B=57.6 px·m）	注释过时	同步数值

---

3. 阶段 2：校正质量核验

判据（§12.1 校正质量）：静态场景下，左右匹配框的 |Δy| 分布 P95 ≤ 1 px（⚠占位）。 不达标 → 触发自标定提前（§7 风险表第 7 项、《需求说明》§6）。

3.1 建议方法

1. 静态标靶（棋盘格或随机纹理板）摆在近/中/远 3 档（如 3 / 8 / 15 m），每档在画面 中心与四角共 5 个区域成像；
2. 每处采 ≥50 帧，用检测链路本身（前端 → 两目框）统计 |y1_L − y1_R| 与 |cy_L − cy_R| 双口径的 P95；
3. 交叉验证：若统计值接近 1 px，改用角点/纹理匹配口径（不依赖检测框边缘）复核， 避免把"检测边缘抖动"误判成"校正误差"。参考量级：本仓合成对（已知零校正误差） 在 1080p 下实测 |Δy| ≈ 0.2 px，即检测链路自身就贡献约 0.2 px 噪声。

3.2 不达标时的排查顺序

1. 内参/remap 是否张冠李戴（最常见：用原始图内参解释校正图）；
2. 校正映射是否按原生分辨率生成（缩放过的 map 会引入亚像素偏置）；
3. 两目光轴平行度/安装（机械问题，需厂商介入）；
4. 仍不达标 → 自标定（P2 不达标即 v1.1 自标定提前，§7 风险表）。

⚠ 工具缺口：仓库目前没有该统计脚本，需新增（建议 utils/tools/calib_check.py， 输入左右目图像目录，输出 |Δy| 直方图与 P95）。

---

4. 阶段 3：真实素材采集与入库

4.1 采集清单

档位	内容	用途
5 / 10 / 15 / 20 m	静态标靶（或无人机目标静置），每档 ≥50 帧，手持激光测距仪同步记录真值	P4 测距精度（§12.1）
≥25 m（域外档）	同上	验证"域外不撒谎"：valid=false 且方位照常发布（§12.3 第 3 条）
横向快速移动	目标在画面内快速平移	帧同步核验（§12.1：无系统性虚假视差）
多目标	同画面 2 个同类目标 + 1 个非目标干扰	P5 的 isolation_gate_px 整定
丢失-恢复	目标被遮挡 ≥ filter_reset_frames 帧后重现	P5 的 filter_reset_frames / smooth_alpha 整定

4.2 命名与落位（建议）

utils/assets/stereo_yolo/<YYYYMMDD>/z05m_01_L.png
                                      z05m_01_R.png    # 双流形态
                                      z05m_01_sbs.png  # sbs 形态（推荐，§2.3）
                                      z05m_01.json     # 元数据

元数据必填字段：拍摄时间、距离真值 + 测距仪型号、目标类型、光照/天气、曝光与增益、 同步形态、分辨率、帧号范围、操作人。

4.3 注意

• 素材必须是校正后的图（或同时保存原始图 + 本次使用的 remap 表）——否则 P4 的 误差里混进校正误差，无法归因（§2.2 第 4 条）；
• 替换 utils/assets/stereo_yolo/drone_sky.png 只能换"单图冒烟"的输入；上面这套 目录结构需要配回放脚本（见 P4 工具缺口）。

---

5. 阶段 4：测距真值验证

判据（§12.1 测距精度）：以地面手持激光测距仪为真值（D8：测距方向与 Z 一致，不是斜距 R）；有效域内 δZ ≤ 2 m（⚠占位）；误差趋势符合 δZ ∝ Z²（§7.1）。

5.1 方法与产物

1. 每档 ≥50 组"前端 → StereoRanger.update()"输出，与真值比对，输出误差-距离曲线；
2. 由曲线拟合实测 δD（视差噪声基准，当前固定 1 px 是占位，§12.2）， 并用 Z_budget = sqrt(max_delta_z_m × F·B / δD_meas) 反推"预算门"应落在哪；
3. 单独跑域外档，确认 valid=false 且 center_mid_px 仍发布（§7.3 域外不撒谎， 也不丢方位）；
4. 结果记入附录 A.4。

5.2 不通过时的归因顺序

现象	首先怀疑	处置
全档系统性偏置	内参/基线错、取点规则	复核 P1 回填值；复核 x1 取点（§6.1 同侧边缘）
误差随 Z² 放大且系数偏大	实测 δD 大于既定基准	收紧 max_delta_z_m 或缩小有效域；把实测 δD 写回规格（§12.2）
远场随机跳变	检测边缘抖动 + 小视差放大	属预期（§7.2），确认降级/门限按 §6.4 生效即可
横向移动时出现虚假视差	帧同步	回到 P3 复核同步形态（§2.3）

⚠ 工具缺口：仓库目前没有"真实素材回放"脚本（现 demo 的合成对是解析构造的）， 需新增（建议 utils/tools/replay_stereo.py，输入 4.2 的目录结构，输出逐帧记录 与误差表）。

---

6. 阶段 5：阈值整定清单

§9 表中每个 ⚠ 都要在本阶段被实测值替换。整定依据与建议方法：

参数	占位值	整定输入	建议方法
tau_y_px	2.0	P2 的 |Δy| 分布	取 P95 的 1.5~2 倍留余量
tau_h_ratio	0.25	真实框高相对差分布	同上口径
disparity_min_px	3.0	可测远界需求	由任务远界反推（P1 已重算）
disparity_max_px	57.6	任务近界	由 Z_near 反推（P1 已重算）
max_delta_z_m	2.0	P4 的误差曲线	由可接受的最大距离误差定；与 δD 实测联动（P4 第 2 步）
consistency_jump_px	3.0	静态场景视差噪声 P95	取噪声峰值的数倍：太小误判、太大漏检（§6.7）
consistency_N_frames	3	安全需求 + 误报率	N/M 决定"异常后多久降级/判无效"（3/5 ≈ 0.17 s @30 fps），与消费侧的降级时延一起定
consistency_M_frames	5	同上	必须 ≥ N
smooth_alpha	0.3	P4 数据离线拟合	在"噪声抑制"与"群延迟"间取平衡（0.3 ≈ 3.3 帧群延迟）
jump_reset_m	5.0	真实跳变幅度观测	用目标切换/大机动场景标定
filter_reset_frames	5	丢失-恢复场景	与消费侧 coast 策略配合（§6.5）
isolation_gate_px	50.0	多目标场景	由"同帧不同目标的最小像素间距"定，取小于该值的门限

前端侧同步复核：conf_threshold / iou_threshold 与真实素材上的漏检/误检权衡； imgsz 与平台算力（P7）——这两项不随标定变化，但要与检测质量一起整定。

---

7. 阶段 6：台架/SITL 联动与解禁评审

7.1 台架联动（判据见 §12.1 控制联动）

回放/SITL 下跑通：距离闭环 ↔ 定速接近切换、invalid 持续降级路径、 远场"方位闭环 + 定速接近"（D4）——场景覆盖要求见《视觉跟踪控制律技术路线》第 7 章。

7.2 解禁检查表（§12.3 四条逐条勾选）

• 红线 1：§7/§9 中所有 ⚠ 数值已由实测/厂商数据确认，替换记录已归档（附录 A.2/A.3/A.4）；
• 红线 2：相机参数与阈值全部在配置文件中，代码内无写死（含 demo/工具脚本复核）；
• 红线 3：域外/失配确实输出 valid = false——合成回归（pytest -q）+ 真实素材（P4 域外档）两轮都有证据；
• 红线 4：地面真值验证完成并归档（P4 全档通过）。

7.3 解禁之后仍未解禁的

本文解除的是测距/检测链路的红线。实飞还要求控制律侧完成 《视觉跟踪控制律技术路线》§8 阶段 6 的增益与限幅整定——两者都满足才可实飞。

---

附录 A：记录表模板

A.1 开箱登记

项	值
型号 / 序列号
分辨率 / 帧率 / 像素格式
标称基线 / 实测基线（工具、公差）
校正后内参（fx, fy, cx, cy）
畸变系数 / remap 表版本
出厂标定报告编号与日期
同步形态（sbs / 双流 / 硬触发）
到货日期 / 登记人

A.2 参数回填记录

字段	回填前	回填后	来源	日期 / 批准

派生量复核（手算 vs 程序）：F·B = ＿＿＿，z_min_m = ＿＿＿，z_max_m = ＿＿＿， z_error_budget_max_m = ＿＿＿。

A.3 校正质量核验

档位	区域	样本数	|Δy| P95	判据 ≤1 px	备注

A.4 测距真值验证

距离真值	样本数	Z 均值	δZ	判据 ≤2 m	valid 率	备注

---

附录 B：判据来源索引

本文阶段	规格出处
P1 回填与派生量	《测距路线》§9.1、§6.4、§11.2
P1 连带修改	utils/stereo_ranger/config.py（fail-fast 规则）、两份 config_test.py
P2 校正质量	《测距路线》§12.1、§7 风险表第 7 项；《需求说明》§6
P3 采集与同步	《需求说明》§2.3；《测距路线》§12.1 帧同步
P4 真值验证	《测距路线》§12.1、§7.1、§7.2、§7.3（D8 真值方向）
P5 阈值整定	《测距路线》§9 全表、§12.2；《需求说明》§4
P6 联动与解禁	《测距路线》§12.1、§12.3；《视觉跟踪控制律技术路线》§7/§8

附录 C：已知缺口（执行前需补齐）

1. 工具脚本缺三件（本文标注 ⚠）：校正质量统计（P2）、真实素材回放（P4）、 真值-误差曲线拟合（P4）。在它们就位前，P2/P4 只能手工抽样，判据不可复现；
2. 外部参考文档缺档：《测距路线》§12.2 把开放问题（P1 焦距规格、P2 出厂标定、 P3 帧同步形态、P6 换机型、P7 性能实测、P8 避障激光去留）的权威清单指向 《双目深度估计思路》第 15 章，该文档当前不在仓库中——需要它才能核对问题编号与 结论，请补回或改引他处；
3. P7（性能实测）不在本文范围：它依赖机载/边缘平台，属平台工程文档。