相机工具

相关源文件

生成此 wiki 页面时使用了以下文件作为上下文：

dataset_tools 包提供一组工具，用于保证不同机器人本体和数据采集会话之间的传感器一致性。这些工具聚焦两个主要方向：使用 ArUco 标记进行几何对齐，以及通过硬件图像信号处理器（ISP）流水线进行光度对齐。

1. 相机对齐工具（camera_alignment）

camera_alignment 工具用于将相机的物理视角恢复到“golden”参考位置。它使用 ArUco markers（具体为 DICT_4X4_50 family）计算像素级位移误差 src/dataset_tools/docs/tools/camera_alignment.md:1-3。

实现与数据流

该工具直接从 V4L2 设备或 OpenCV 索引读取 src/dataset_tools/dataset_tools/camera_alignment.py:102-104。它计算检测到的 markers 角点与已保存 reference payload 之间的平均欧氏距离 src/dataset_tools/dataset_tools/camera_alignment.py:51-76。

对齐数据流

        graph TD
    V4L["V4L2 Device /dev/videoX"] --> OCV["OpenCVFrameSource"]
    OCV --> DET["ArUco Detector (DICT_4X4_50)"]
    DET --> ERR["compute_alignment_error()"]
    REF["Reference JSON (image_width, image_height, markers)"] --> ERR
    ERR --> HUD["OpenCV GUI HUD (Green < 3px, Red >= 3px)"]
    
    subgraph "Logic Entities"
        OCV
        DET
        ERR
    end

来源: src/dataset_tools/dataset_tools/camera_alignment.py:51-76, src/dataset_tools/docs/tools/camera_alignment.md:94-100

关键函数

2. Camera ISP Calibrator（camera_isp_calibrator）

camera_isp_calibrator 是一个高级工具，用于将实时相机画面的视觉特性（曝光、色彩平衡、对比度）匹配到参考图像。它主要面向 UVC 兼容相机的硬件 ISP registers src/dataset_tools/dataset_tools/camera_isp_calibrator.py:1-25。

硬件 ISP 流水线

标定遵循 hw_pipeline.py 中定义的 4 阶段顺序状态机 src/dataset_tools/dataset_tools/camera_isp/hw_pipeline.py:1-15：

Stage

Logic Entity

Purpose

Stage 1

propose_exposure

使用过曝保护将 Y_mean 推向 128（50% code value）src/dataset_tools/dataset_tools/camera_isp/hw_stages.py:153-161。

Stage 2

evaluate_gain_step_b

必要时提高 gain，但验证 SNR ≥ 20 dB。如果触及噪声底，则回退到 brightness offset src/dataset_tools/dataset_tools/camera_isp/hw_stages.py:63-70。

Stage 3

propose_sat_con

根据参考统计量缩放 saturation 和 contrast，并裁剪到驱动默认值的 ±30% src/dataset_tools/dataset_tools/camera_isp/hw_stages.py:71-72。

Stage 4

solve_kelvin_only

使用 McCamy 公式和 Planckian locus 投影，将 chromaticity 映射到 Kelvin src/dataset_tools/dataset_tools/camera_isp/solver.py:6-33。

系统架构（ISP 标定）

该工具通过 bridge pattern 连接高层 GUI 交互和低层 V4L2 控制。

ISP 控制架构

        graph LR
    GUI["CalibratorWindow (OpenCV GUI)"] -->|"Triggers"| PIPE["hw_pipeline.run_full_pipeline"]
    PIPE -->|"Proposes"| STAGES["hw_stages.py (Pure Functions)"]
    PIPE -->|"Writes via"| BRIDGE["CameraBridge / StageBridge"]
    BRIDGE -->|"Executes"| V4L2["v4l2_ctl.py (Shell Wrapper)"]
    V4L2 -->|"IO"| DEV["/dev/videoX"]
    
    subgraph "Logic Entities"
        PIPE
        STAGES
        V4L2
    end

来源: src/dataset_tools/dataset_tools/camera_isp/hw_pipeline.py:7-23, src/dataset_tools/dataset_tools/camera_isp/v4l2_ctl.py:1-17

V4L2 控制集成

v4l2_ctl.py 模块处理 Linux UVC 驱动的复杂性，并为重命名 controls 提供回退，例如 white_balance_automatic vs white_balance_temperature_auto src/dataset_tools/dataset_tools/camera_isp/v4l2_ctl.py:1-17。它确保 solver 尝试写入参数前，手动模式已经启用 src/dataset_tools/dataset_tools/camera_isp/v4l2_ctl.py:141-159。

统一颜色搜索（KCS）

对于高级颜色匹配，该工具实现了 “Unified K/C/Sat Search”（color_search.py）。它在 Kelvin、Contrast 和 Saturation 上执行坐标下降，以最小化代价函数（ΔE2000）src/dataset_tools/dataset_tools/camera_isp/color_search.py:1-38。

配置与持久化

标定结果会作为 JSON overrides 保存到 ~/.ros/ibrobot/camera_isp_overrides/{camera}.json src/dataset_tools/dataset_tools/camera_isp_calibrator.py:118-121。这些 overrides 会被 robot_config 中的 perception.py launcher 自动检测并应用，保证一致性，同时不修改中心 YAML 单一事实源 src/dataset_tools/README.md:191-193。

来源：