解决标定工具问题

docs/tool_usage_guide.md

@@ -0,0 +1,85 @@
+# 图像采集工具指南 (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) 以验证算法行为。
+
+**使用场景**:
+当您需要调整检测灵敏度，或调试差异检测逻辑中的误报/漏报时使用。