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）。

4.1 KiB Raw Blame History Unescape Escape