stereo_ranger（Python）
双目稀疏目标测距（规格：docs/双目测距方案.md）。输入左右目各自、校正后原生坐标系下的检测框，输出目标的 (Z, X, Y, R) 与方位。不做目标识别（YOLO）、不做图像采集与立体校正——对应规格 §10 中可独立替换的检测前端与采集预处理模块。
仅依赖标准库（math/logging），不 import 本仓库任何其他模块。
接口清单
| 名称 | 说明 |
|---|---|
Detection(x1, y1, x2, y2, conf=1.0, cls_id=0, track_id=0) |
输入检测框（px，左上/右下角） |
StereoConfig(...) |
配置（默认值 = 规格示例值，见下） |
load_from_json(path) |
从 JSON 构建配置（缺字段/未知字段/非法值抛 ValueError） |
StereoRanger(config=None) |
测距器主类 |
.update(left_dets, right_dets, frame_sequence=0, timestamp_s=None) -> list[RangeReport] |
单帧主流程（返回记录数与左目检测数一致、顺序一致） |
.reset() / .config |
清空滤波状态 / 当前配置 |
RangeReport |
输出记录（字段见 types.py） |
focal_from_hfov(w_px, hfov_deg) / range_error_abs(z, fx, B, δD=1) / range_error_rel(...) |
工具函数（§5.2/§5.3） |
与检测器的约定（规格 §4.3）
- 左右图像必须使用完全一致的预处理几何（同 letter-box、同缩放），由检测前端保证；
- 传入本模块的框必须已映射回原生分辨率（视差在原生坐标计算），内参
fx/fy/cx/cy亦对应原生分辨率； - 图像对须已完成立体校正（同一目标在两目 y 坐标一致）；校正残留由
vertical_tau_px容错； - YOLO 推理及左右目并行执行由调用方负责，本模块只收检测结果。
单帧流程（对照规格）
硬约束过滤（类别一致、|Δy| ≤ τy、高度比 ≤ τh、视差落在 FB/z_max ~ FB/z_min 区间）→ 代价 |Δy|/τy + |Δh|/(τh·max(hL,hR)) 升序贪心一一配对（严格 cost < 1；同 track_id 优先）→ 主取同侧左边缘视差，越出关联窗口时按配置回退中心视差（节流警告）→ Z=FB/D、X=(xL−cx)Z/F、Y=(yL−cy)Z/F、R=√(X²+Y²+Z²) → 有效性 D ≥ D_min 且 δZ ≤ Z_tol → 可选一阶低通滤波（按 (cls, track) 分键，跳变超门限重置；track_id=0 不过滤）。
输出语义
matched=True, valid=True：有效测距；matched=True, valid=False：已配对但超出有效工作域（§5.4），距离/坐标仍发布供诊断，方位可用；matched=False, valid=False：左目检测本帧未配对（§6 失败处理），仅单目方位回退。
方位源 centre_pixel_x_mid 为基线中点虚拟相机投影（§11.3）；注意 X 属左目坐标系（§4.2），二者相差 B/2，勿混用。
StereoConfig 关键项
| 字段 | 默认 | 说明 |
|---|---|---|
fx_px/fy_px/cx_px/cy_px |
960/960/960/540 | 校正后内参（原生分辨率） |
baseline_m |
0.06 | 基线 B |
z_min_m / z_max_m |
1.0 / 50.0 | 距离窗口（派生视差关联区间） |
vertical_tau_px / height_ratio_tau |
2.0 / 0.25 | 关联阈值 τy / τh |
disparity_min_px / range_tol_m |
3.0 / 2.0 | 有效性判据 D_min / Z_tol |
disp_noise_px |
1.0 | 误差模型 δD（用于 δZ 估计与有效性） |
use_center_fallback |
true | 边缘视差越窗时回退中心 |
filter_enabled / filter_alpha / filter_jump_ratio |
false / 0.3 / 0.2 | 时间滤波 |
warn_interval_s |
5.0 | 诊断日志节流间隔 |
运行
cd utils
"D:/program file/conda/envs/pytorch/python.exe" -m pytest -q # 全部测试（149 条）
"D:/program file/conda/envs/pytorch/python.exe" demo_stereo_ranger.py # 合成场景 demo
未覆盖边界（属其他模块/后续版本）
- 图像采集、立体校正 remap、帧同步、side-by-side 裁切（规格 §3）；
- YOLO/检测器及其预处理（由调用方按上文约定接入）；
- 亚像素边缘精化、跨帧跟踪（
track_id由外部追踪器提供后，时间滤波即可用）、与主测距传感器融合（§5.5/§11）。