# 图像采集工具指南 (Image Capture Tools Guide)

本文档对位于 `image_capture/src/tools` 目录下的辅助工具进行了概述。这些工具旨在辅助料箱存储检测系统的相机配置、标定以及算法调优工作。

## 工具概览与使用顺序

在新系统或新相机设置过程中，建议的使用顺序如下：

1.  **[intrinsic_dumper](#1-intrinsic_dumper)** - 提取相机出厂参数。
2.  **[calibration_tool](#2-calibration_tool)** - 标定相机相对于环境的位姿。
3.  **[generate_reference](#3-generate_reference)** - (可选) 创建托盘检测的基准数据。
4.  **[slot_algo_tuner](#4-slot_algo_tuner)** - (按需) 离线调试算法参数。

---

### 1. intrinsic_dumper (内参导出工具)
**路径**: `src/tools/intrinsic_dumper`

**用途**:
这是设置流程的 **第一步**。它是一个命令行工具，能够自动与连接的 Percipio 相机通信，提取其出厂标定的内参、畸变系数以及内部外参（RGB 与 Depth 传感器之间）。

**主要功能**:
*   自动扫描连接的设备。
*   同时提取 Depth (深度) 和 Color (彩色) 传感器的参数。
*   输出标准格式的 JSON 文件，供其他工具和主程序使用。

**输出**:
*   文件名: `intrinsics_<序列号>.json`
*   包含内容: `fx`, `fy`, `cx`, `cy`, 畸变系数等。

---

### 2. calibration_tool (标定工具)
**路径**: `src/tools/calibration_tool`

**用途**:
这是 **第二步**。这是一个 GUI 应用程序，用于计算相机相对于现实世界中特定参考平面（例如地面或货架表面）的“外参”。简单来说，它告知系统相机在安装环境中的位置和角度。

**主要功能**:
*   加载由第一步生成的 `intrinsics_<SN>.json` 参数。
*   允许用户在图像上选择一个平坦区域 (ROI)。
*   拟合深度数据所在的平面，计算旋转和平移矩阵。
*   在彩色图和深度图上可视化标定过程。

**输出**:
*   文件名: `calibration_result_<序列号>.json`
*   包含内容: 一个 4x4 的 `transformation_matrix`，用于将相机坐标系转换到世界/参考坐标系。

---

### 3. generate_reference (基准生成工具)
**路径**: `src/tools/generate_reference`

**用途**:
此工具专门用于 **托盘偏移检测 (Pallet Offset Detection)** 算法。它允许您定义托盘的“标准”或“基准”位置。检测算法随后会将实时采集的托盘与此基准进行对比，以确定偏移量。

**主要功能**:
*   加载 16-bit 深度图像。
*   交互式选择托盘插孔区域 (ROI)。
*   运行 `PalletOffsetAlgorithm` 以查找托盘的精确 3D 位置。
*   (可选) 使用第二步生成的标定矩阵提供真实世界坐标。

**输出**:
*   文件名: `reference_pallet.json`
*   包含内容: 基准 `x`, `y`, `z` 坐标和 `reference_angle` (基准角度)。

---

### 4. slot_algo_tuner (算法调优工具)
**路径**: `src/tools/slot_algo_tuner`

**用途**:
这是一个 **离线调试和调优工具**，主要用于 **横梁/货架变形检测** 或类似的基于图像比对的算法。它允许开发人员在不连接即时相机的情况下微调图像处理参数。

**主要功能**:
*   并排对比“基准”图像和“输入”图像。
*   实时调整参数:
    *   ROI (感兴趣区域)
    *   Thresholds (二值化阈值)
    *   Blur Kernel Size (模糊核大小)
    *   Area Filters (面积过滤)
*   可视化差异图 (Difference Map) 和二值掩膜 (Binary Mask) 以验证算法行为。

**使用场景**:
当您需要调整检测灵敏度，或调试差异检测逻辑中的误报/漏报时使用。