# 传感器标定算法模板合同

本文档固定传感器内参、外参和手眼标定算法与车间系统之间的输入、输出和交接边界。具体相机、IMU、LiDAR、手眼求解算法由算法工程师实现；本仓库只提供模板、数据输入合同和车间电脑侧交接流程。

## 运行边界

- 车间电脑负责创建会话、下发传感器标定任务、采集或接入数据、运行标定算法和生成参数交接包。
- 车端 Windows agent 只负责按现场需要执行采集动作、回传数据或回传采集结果。
- 外部真值定位来自车间四角 LiDAR + 车端标定球系统，可作为外参和 IMU 外参的辅助输入。
- 参数写入车辆这一步当前只生成交接包，不直接调用车端写参接口。

## C++ 模板入口

算法实现者主要修改这些文件：

- `src/core/agv_calib_core/sensor_calibration_service/src/camera_intrinsic_calibration_algorithm.cpp`
- `src/core/agv_calib_core/sensor_calibration_service/src/imu_intrinsic_calibration_algorithm.cpp`
- `src/core/agv_calib_core/sensor_calibration_service/src/sensor_to_base_extrinsic_calibration_algorithm.cpp`
- `src/core/agv_calib_core/sensor_calibration_service/src/hand_eye_calibration_algorithm.cpp`

不要修改 node 层、gateway、orchestrator、report 或现场采集工具，除非明确需要扩展模板输入字段。

## 任务类型

当前固定的任务子类型：

- 相机内参：`front_camera_intrinsic`、`downward_camera_intrinsic`。
- IMU 内参：`imu_intrinsic`。
- 传感器外参：`front_camera_extrinsic`、`downward_camera_extrinsic`、`imu_extrinsic`、`lidar_2d_extrinsic`、`lidar_3d_extrinsic`。
- 手眼：`eye_in_hand`、`eye_to_hand`。

现场任务 profile：

```bash
src/site_deployment/workshop_sensor_calibration_real/config/sensor_calibration_profile.yaml
```

## 数据输入

算法应读取 `SensorCalibrationInput` 中的字段，或读取 `dataset_index.yaml` 转换出的 `data_input.*` 参数。

主要输入：

- `input.request`
- `input.task_type`
- `input.task_subtype`
- `input.target_sensor_id`
- `input.target_sensor_type`
- `input.camera_intrinsic_task`
- `input.imu_intrinsic_task`
- `input.sensor_to_base_extrinsic_task`
- `input.hand_eye_task`
- `input.image_sample_files`
- `input.imu_sample_files`
- `input.pointcloud_sample_files`
- `input.laser_scan_sample_files`
- `input.target_detection_files`
- `input.robot_pose_sample_files`
- `input.synchronized_dataset_files`

现场数据合同：

```bash
src/site_deployment/workshop_sensor_calibration_real/sensor_data_contract.md
```

数据格式样例：

```bash
src/site_deployment/workshop_sensor_calibration_real/config/data_examples/
```

车间电脑侧数据校验和索引写入工具：

```bash
src/site_deployment/workshop_sensor_calibration_real/sensor_dataset_manifest.py
```

车间电脑侧预处理和检测入口：

```bash
src/site_deployment/workshop_sensor_calibration_real/sensor_preprocess_pipeline.py
```

该入口负责生成预处理质量报告，并可在安装 OpenCV 时从图像生成棋盘格或 ChArUco 检测结果。没有 OpenCV 或检测算法由其他团队提供时，只要外部程序按数据合同输出 `target_detections.json` 即可。

## 算法输出

算法输出文件建议固定为：

```bash
<session_dir>/sensor/estimated_params.yaml
```

模板：

```bash
src/site_deployment/workshop_sensor_calibration_real/config/sensor_estimated_params_template.yaml
```

核心字段：

- `session_id`：本次会话 ID。
- `vehicle_id`：车辆 ID，必须与 `dataset_index.session.vehicle_id` 一致。
- `sensor_id`：目标传感器 ID。
- `selected_task`：`camera_intrinsic`、`imu_intrinsic`、`sensor_extrinsic` 或 `hand_eye`。
- `task_subtype`：具体子类型。
- `parameter_version`：本轮参数版本。
- `estimated_params`：算法估计出的参数。
- `quality.data_quality_passed`：数据质量是否达标。
- `quality.suitable_for_commit`：是否允许进入待审批包。
- `quality.validation_summary.auto_acceptance_passed`：自动验收是否通过。

只有以上质量字段为 true 的输出，才允许生成待审批包。

## 参数交接

生成待审批包：

```bash
python3 src/site_deployment/workshop_sensor_calibration_real/stage_sensor_parameter_commit.py \
  --dataset-index /data/agv_calib/site_a/session_001/dataset_index.yaml \
  --estimated-params /data/agv_calib/site_a/session_001/sensor/estimated_params.yaml
```

审批交接：

```bash
python3 src/site_deployment/workshop_sensor_calibration_real/approve_sensor_pending_parameters.py \
  /data/agv_calib/site_a/session_001/sensor/pending_sensor_commit.yaml \
  --operator-id operator_001
```

`dataset_index.yaml` 的 `metadata` 会记录传感器算法输出、待审批包、审批状态和交接包路径。总控 report 会把这些文件加入 `report_files`。

车间电脑侧导出车辆侧参数配置：

```bash
python3 src/site_deployment/workshop_sensor_calibration_real/apply_sensor_parameter_handoff.py \
  /data/agv_calib/site_a/session_001/sensor/approved_sensor_parameter_handoff.yaml \
  --operator-id operator_001
```

该工具只生成可交给车端适配器消费的配置文件和回执，不直接调用 Windows 车端或厂商 SDK。

## 本地回放 smoke

传感器本地回放 smoke：

```bash
python3 src/site_deployment/workshop_sensor_calibration_real/smoke_test_sensor_calibration_real.py
```

它会用仓库内示例数据验证 `sensor_intrinsic -> sensor_extrinsic -> hand_eye` 三类传感器参数的车间电脑侧数据、交接和应用落盘链路。

## 验收建议

真实算法至少应在 `quality.validation_summary` 写入：

- 重投影误差。
- 平移残差。
- 旋转残差。
- 平面或点云配准残差。
- 重复性误差。
- 有效样本数量。
- 自动验收是否通过。

模板不会替算法做通过判定。算法工程师需要根据现场工艺要求设置阈值，并明确写出 `suitable_for_commit`。
