74 lines
2.9 KiB
Python
74 lines
2.9 KiB
Python
"""视差取点器（§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
|