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

1. 左右图像必须使用**完全一致**的预处理几何（同 letter-box、同缩放），由检测前端保证；
2. 传入本模块的框必须已映射回**原生分辨率**（视差在原生坐标计算），内参 `fx/fy/cx/cy` 亦对应原生分辨率；
3. 图像对须已完成立体校正（同一目标在两目 y 坐标一致）；校正残留由 `vertical_tau_px` 容错；
4. 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 | 诊断日志节流间隔 |

## 运行

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