GrabBag/App/BinocularMark/BinocularMarkApp/CONFIG_README.md

# BinocularMarkApp 配置说明

## 配置文件结构

BinocularMarkApp 使用两个配置文件：

### 1. config.xml（应用配置）

存储应用运行参数，**需要修改**的参数在此文件中配置。

**文件位置**: `BinocularMarkApp/Config/config.xml`

**格式说明**: 使用 XML 格式，与其他项目（WorkpieceProject）保持一致

**配置示例**:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<BinocularMarkConfig>
    <!-- TCP服务器配置 -->
    <ServerConfig port="5901" />

    <!-- 相机配置 -->
    <Cameras>
        <Camera index="0" name="LeftCamera" exposureTime="10000.0" gain="1.0" />
        <Camera index="1" name="RightCamera" exposureTime="10000.0" gain="1.0" />
    </Cameras>

    <!-- 双目标定文件路径 -->
    <CalibrationFile path="../Calib/Mark_13度/StereoCamera.xml" />

    <!-- Mark板参数 -->
    <MarkInfo patternWidth="3" patternHeight="3" checkerSize="60.0" markerSize="45.0" dictType="1" />

    <!-- Board配置 -->
    <BoardInfo totalBoardNum="1" boardIdInterval="8" boardCharucoIdNum="4" />

    <!-- 算法参数 -->
    <AlgorithmParams disparityOffset="0.0" />

    <!-- 调试参数 -->
    <DebugParam enableDebug="true" saveDebugImage="false" printDetailLog="true" debugOutputPath="" />
</BinocularMarkConfig>
```

**参数说明**:

- **ServerConfig**: TCP 服务器配置
  - `port`: 服务器端口（默认5901）

- **Cameras**: 相机配置
  - `index`: 相机索引（0-左相机，1-右相机）
  - `name`: 相机名称
  - `exposureTime`: 曝光时间（微秒）
  - `gain`: 增益

- **CalibrationFile**: 标定文件路径
  - `path`: 相对路径或绝对路径

- **MarkInfo**: Mark 板参数
  - `patternWidth`: Mark板列数
  - `patternHeight`: Mark板行数
  - `checkerSize`: 棋盘格尺寸（mm）
  - `markerSize`: ArUco标记尺寸（mm）
  - `dictType`: ArUco字典类型（1=DICT_6x6）

- **BoardInfo**: Board 配置
  - `totalBoardNum`: Board总数
  - `boardIdInterval`: Board ID间隔
  - `boardCharucoIdNum`: 每个Board的Charuco角点数

- **AlgorithmParams**: 算法参数
  - `disparityOffset`: 视差偏移（用于微调深度计算）

- **DebugParam**: 调试参数
  - `enableDebug`: 是否启用调试模式
  - `saveDebugImage`: 是否保存调试图像
  - `printDetailLog`: 是否打印详细日志
  - `debugOutputPath`: 调试输出路径

### 2. StereoCamera.xml（双目标定参数）

存储双目相机标定参数，**只读文件**，由标定工具生成，不应手动修改。

**默认路径**: `App/BinocularMark/Calib/Mark_13度/StereoCamera.xml`

**文件内容**（OpenCV标准格式）:
- `<LeftCamera>`: 左相机内参、畸变系数、图像尺寸
- `<RightCamera>`: 右相机内参、畸变系数、图像尺寸
- `<Stereo>`: 双目标定参数（旋转矩阵R、平移向量T、基线Baseline等）
- `<Rectification>`: 校正参数（R1, R2, P1, P2, Q矩阵）

## 配置加载流程

1. 程序启动时加载 `config.xml`
2. 使用 QDomDocument 解析 XML 文件
3. 读取应用配置（端口、相机参数、Mark参数等）
4. 从 `<CalibrationFile>` 标签读取标定文件路径（必须配置）
5. 验证标定文件路径是否有效
6. 自动加载双目标定文件 StereoCamera.xml
7. 验证所有标定参数是否完整
8. 输出加载日志

**重要**：`<CalibrationFile>` 标签及其 `path` 属性为必填项，如果缺失或为空，程序将无法启动。

## 标定文件路径配置

必须在 `config.xml` 中明确配置标定文件路径：

```xml
<!-- 相对路径（推荐）：相对于 config.xml 所在目录 -->
<CalibrationFile path="../Calib/Mark_13度/StereoCamera.xml" />

<!-- 或使用绝对路径 -->
<CalibrationFile path="C:/BinocularMark/Calib/Mark_13度/StereoCamera.xml" />
```

**路径规则**：
- 相对路径：相对于 `config.xml` 所在目录解析
- 绝对路径：直接使用完整路径
- 路径中使用正斜杠 `/` 或反斜杠 `\` 均可

## 切换不同角度的标定参数

如果有多个角度的标定文件（如 Mark_13度、Mark_15度），只需修改 `config.xml` 中的 `<CalibrationFile>` 路径：

```xml
<!-- 切换到 Mark_15度 标定文件 -->
<CalibrationFile path="../Calib/Mark_15度/StereoCamera.xml" />
```

## 日志输出示例

成功加载配置后，日志输出：

```
Configuration loaded from .../config.xml
  Server port: 5901
  Camera indices: L=0, R=1
  Mark pattern: 3x3, checker=60.000000mm, marker=45.000000mm
  Board info: total=1, interval=8, charucoNum=4
  Disparity offset: 0.000000

Loading calibration from OpenCV XML file: .../StereoCamera.xml
  Left camera matrix loaded: [4999.02, 2250.30, 4999.26, 2060.09]
  Right camera matrix loaded: [4992.95, 2287.94, 4993.71, 2079.38]
  Stereo baseline: 769.59 mm
  Q matrix loaded: [0.001299, -2214.277710, -2076.116623, 4996.487863]
Calibration loaded successfully from .../StereoCamera.xml
```

## 错误处理

### 缺少标定文件配置

如果 `config.xml` 中缺少 `<CalibrationFile>` 标签：

```
ERROR: Missing <CalibrationFile> element in config file!
ERROR: Please add: <CalibrationFile path="path/to/StereoCamera.xml" />
```

**解决方法**：在 `config.xml` 中添加标定文件路径配置

### 标定文件路径为空

如果 `path` 属性为空：

```
ERROR: CalibrationFile path is empty in config file!
ERROR: Please set path attribute: <CalibrationFile path="../Calib/Mark_13度/StereoCamera.xml" />
```

**解决方法**：设置有效的标定文件路径

### 标定文件不存在

如果指定的标定文件不存在：

```
ERROR: Failed to open calibration file: .../StereoCamera.xml
ERROR: Failed to load calibration file: .../StereoCamera.xml
```

**解决方法**：检查文件路径是否正确，文件是否存在

## 常见问题

### Q1: 标定参数加载失败

检查：
1. 标定文件是否存在于正确路径
2. 文件格式是否正确（OpenCV XML格式）
3. 文件是否包含所有必需的参数节点

### Q2: 需要修改标定参数

不要直接修改 `StereoCamera.xml` 文件，应该：
1. 使用标定工具重新标定
2. 生成新的 `StereoCamera.xml` 文件
3. 替换原文件或修改 `config.xml` 中的路径指向新文件

### Q3: 视差偏移参数的作用

`disparity_offset` 用于微调深度计算，通常用于：
- 补偿环境温度变化导致的基线微小变化
- 微调深度测量精度
- 默认值为 0.0，需要时再调整

### Q4: 标定参数获取方法

使用OpenCV进行双目标定，生成StereoCamera.xml文件：

```cpp
// 1. 棋盘格标定
cv::calibrateCamera(...);  // 单独标定左右相机

// 2. 双目标定
cv::stereoCalibrate(...);  // 获取R, T, E, F

// 3. 双目校正
cv::stereoRectify(
    cameraMatrixL, distCoeffsL,
    cameraMatrixR, distCoeffsR,
    imageSize, R, T,
    R1, R2, P1, P2, Q,  // 输出参数
    ...
);

// 4. 保存到XML文件
cv::FileStorage fs("StereoCamera.xml", cv::FileStorage::WRITE);
fs << "LeftCamera" << "{";
fs << "CameraMatrix" << cameraMatrixL;
fs << "DistCoeffs" << distCoeffsL;
// ...
fs.release();
```