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

utils/stereo_ranger/sampling.py

@@ -0,0 +1,73 @@
+"""视差取点器（§6.1）：同侧（左）边缘为主方案，边缘视差越窗时回退框中心。
+
+纯函数、无状态（§4 构件表）。为什么用同侧边缘：同一物理目标在两目中的
+检测框宽并不严格相等，框中心视差会混入框宽差的一半，同侧边缘视差可抵消
+框宽项。
+
+注：§6.1 的"左右两边缘各算一次视差取中值"精化在数学上恒等于框中心视差
+（两支的 median = 均值），与"中心视差混入框宽差"的理由矛盾，属原文笔误，
+v1.0 不实现；规格 §6.1 已删除该项并注明（见包 README「实现决策」）。
+"""
+
+import math
+from dataclasses import dataclass
+
+from .config import StereoConfig
+from .types import Detection, DisparitySource
+
+
+@dataclass(frozen=True)
+class SamplePoint:
+    """单目单框取点结果：同侧边缘候选与框中心（§6.1/§6.6）。
+
+    finite=False 表示坐标非有限值：该框不可参与解算，由调用方丢弃并告警。
+    """
+
+    box: Detection
+    edge_x: float     # 同侧（左）边缘 x = box.x1
+    center_x: float
+    center_y: float
+    finite: bool
+
+
+@dataclass(frozen=True)
+class Disparity:
+    """配对后的视差取点结果。"""
+
+    d_px: float
+    source: DisparitySource
+    fallback_used: bool  # 边缘视差越窗、回退中心（需告警节流，§6.1）
+    in_domain: bool      # d ∈ [D_min, D_max]（含边界，§11.2）
+    positive: bool       # d > 0（正视差是物理前提，§6.3）
+
+
+def sample_point(detection: Detection) -> SamplePoint:
+    """逐框取点（§5 第 ② 步，每目每框一次）。"""
+    finite = all(math.isfinite(value) for value in (detection.x1, detection.y1, detection.x2, detection.y2))
+    return SamplePoint(
+        box=detection,
+        edge_x=detection.x1,
+        center_x=detection.cx,
+        center_y=detection.cy,
+        finite=finite,
+    )
+
+
+def select_disparity(left: SamplePoint, right: SamplePoint, config: StereoConfig) -> Disparity:
+    """在同侧边缘视差与框中心视差之间选择（§6.1 主取点 + 越窗回退）。
+
+    规则：边缘视差在域内取边缘；否则若中心视差在域内则回退中心（告警节流）；
+    两者均越窗时保留边缘值（供诊断与违例告警），由有效性门判无效。
+    """
+    d_edge = left.edge_x - right.edge_x
+    if _in_domain(d_edge, config):
+        return Disparity(d_edge, DisparitySource.LEFT_EDGE, False, True, d_edge > 0.0)
+    d_center = left.center_x - right.center_x
+    if _in_domain(d_center, config):
+        return Disparity(d_center, DisparitySource.CENTER_FALLBACK, True, True, d_center > 0.0)
+    d = d_edge if math.isfinite(d_edge) else d_center
+    return Disparity(d, DisparitySource.LEFT_EDGE, False, False, d > 0.0)
+
+
+def _in_domain(d_px: float, config: StereoConfig) -> bool:
+    return config.disparity_min_px <= d_px <= config.disparity_max_px