# 真实车间传感器标定

这个目录只处理传感器标定的车间电脑侧边界。真实采集程序负责把相机、LiDAR、IMU、机械臂或平台位姿数据落盘；算法服务或离线算法只读取 `data_input.*` 和 `dataset_index.yaml`。

## 数据流

```text
车间电脑总控
  -> 车端传感器 agent 或车间采集程序采集图像/点云/IMU/位姿
  -> 采集程序写入 sensor/* 数据文件
  -> dataset_index_to_site_data_input.py 生成 site_data_input.yaml
  -> sensor_calibration_service 或离线算法读取 data_input.*
  -> 算法输出 sensor/estimated_params.yaml
  -> stage_sensor_parameter_commit.py 生成 pending_sensor_commit.yaml
  -> approve_sensor_pending_parameters.py 生成 approved_sensor_parameter_handoff.yaml
```

## 任务 profile

现场推荐任务固化在：

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

校验并查看摘要：

```bash
python3 src/site_deployment/workshop_sensor_calibration_real/sensor_calibration_profile.py \
  --profile src/site_deployment/workshop_sensor_calibration_real/config/sensor_calibration_profile.yaml
```

导出总控 `requested_tasks`：

```bash
python3 src/site_deployment/workshop_sensor_calibration_real/sensor_calibration_profile.py \
  --profile src/site_deployment/workshop_sensor_calibration_real/config/sensor_calibration_profile.yaml \
  --tasks sensor_intrinsic,sensor_extrinsic,hand_eye \
  --format requested_tasks
```

## 数据输入

数据字段协议见：

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

字段样例见：

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

车间电脑侧如果已经拿到了相机、LiDAR、IMU、机械臂或平台位姿文件，可以先用本目录工具校验这些文件，并写入 `dataset_index.yaml`：

```bash
python3 src/site_deployment/workshop_sensor_calibration_real/sensor_dataset_manifest.py \
  --dataset-root /data/agv_calib/site_a/session_001 \
  --dataset-index /data/agv_calib/site_a/session_001/dataset_index.yaml \
  --session-id session_001 \
  --site-id site_a \
  --vehicle-id agv_001 \
  --image-index sensor/front_camera/images.yaml \
  --target-detections sensor/front_camera/charuco_detections.json \
  --imu-samples sensor/imu/imu_samples.csv \
  --imu-segments sensor/imu/imu_segments.yaml \
  --pointcloud-index sensor/lidar_3d/pointclouds.yaml \
  --laser-scan-index sensor/lidar_2d/laser_scans.yaml \
  --robot-poses sensor/hand_eye/robot_poses.csv
```

这个工具只做车间电脑侧的数据整理和格式校验，不负责连接车端 Windows 采集驱动。

车间电脑侧预处理和检测质量报告：

```bash
python3 src/site_deployment/workshop_sensor_calibration_real/sensor_preprocess_pipeline.py \
  --dataset-root /data/agv_calib/site_a/session_001 \
  --dataset-index /data/agv_calib/site_a/session_001/dataset_index.yaml \
  --image-index sensor/front_camera/images.yaml \
  --target-detections sensor/front_camera/charuco_detections.json \
  --imu-samples sensor/imu/imu_samples.csv \
  --imu-segments sensor/imu/imu_segments.yaml \
  --pointcloud-index sensor/lidar_3d/pointclouds.yaml \
  --laser-scan-index sensor/lidar_2d/laser_scans.yaml \
  --robot-poses sensor/hand_eye/robot_poses.csv
```

如果现场车间电脑安装了 OpenCV，也可以用同一个工具从图像生成棋盘格或 ChArUco 检测结果。没有 OpenCV 时，车端或其他视觉程序只要按 `sensor_data_contract.md` 输出 `target_detections.json` 即可。

真实采集或 ingest 写入索引：

```bash
python3 src/site_deployment/workshop_sensor_ingest_real/site_session_capture.py \
  --site-profile src/deployment/profiles/site_template.yaml \
  --session-dir /data/agv_calib/site_a/session_001 \
  --site-id site_a \
  --vehicle-id agv_001 \
  --file sensor.image_sample_files=sensor/front_camera/images.yaml \
  --file sensor.target_detection_files=sensor/front_camera/charuco_detections.json \
  --finalize
```

校验索引：

```bash
python3 src/deployment/tools/validate_dataset_index.py \
  /data/agv_calib/site_a/session_001/dataset_index.yaml \
  --tasks sensor_intrinsic,sensor_extrinsic,hand_eye
```

## 参数结果交接

算法工程师应输出：

```bash
/data/agv_calib/site_a/session_001/sensor/estimated_params.yaml
```

格式模板：

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

生成待审批包：

```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
```

当前交接包只表示“车间电脑侧已经审批通过，等待车端写参适配器处理”。车端写参实现暂不在本目录内处理。

车间电脑侧可以先把已审批交接包转换成车辆侧导入配置：

```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
```

该步骤会生成 `sensor/applied_parameters/*` 下的导入配置和回执，并把结果写回 `dataset_index.yaml` metadata。真正把配置导入 Windows 车端或厂商配置文件的步骤仍由车端适配器处理。

## 本地 smoke

不依赖 ROS 和 Isaac 的传感器本地 smoke：

```bash
python3 src/site_deployment/workshop_sensor_calibration_real/smoke_test_sensor_calibration_real.py \
  --keep-session-dir
```

这个 smoke 会验证：

- 示例数据格式校验。
- `dataset_index.yaml` 写入。
- 预处理质量报告生成。
- `site_data_input.yaml` 生成。
- `sensor_intrinsic`、`sensor_extrinsic`、`hand_eye` 三类参数输出的待提交、审批、应用落盘链路。
