calibration/README.md

# 车辆多传感器外参标定

本仓库同时维护两条独立的外参标定链路：LiDAR–IMU 与 RTK–IMU。两条链路共享通用的几何和 IMU 预积分基础能力，但各自的观测模型、求解器、工具入口和验收结论独立管理。

## 当前应如何使用

| 目标 | 推荐链路 | 当前可交付状态 |
| --- | --- | --- |
| LiDAR 与 IMU 的旋转、时间对齐 | LiDAR–IMU | 旋转与主机桥接时间对齐可冻结；完整平移不可交付。 |
| RTK 天线相位中心与 IMU 的工程外参 | RTK–IMU | 机械杆臂经动态数据一致性验证；data-only 平移及正式 engineering 放行尚未通过。 |
| 需要完整 RTK–IMU 工程候选和复现方式 | RTK–IMU | 先阅读 [README_RTK_IMU.md](README_RTK_IMU.md)。 |

不要把任何一条链路未通过的平移结果当作已标定的 6DoF 外参。结果的接受状态以对应 JSON 中的 gate 为准。

## 为什么同时保留两条链路

LiDAR–IMU 链路通过点云相对运动与 IMU 预积分求手眼外参，适合旋转与时间对齐；但当前实车数据的加速度预积分位移，尤其 Z 分量，不足以支持可靠平移求解，且主要采集运动缺乏竖直激励。因此它的 `full_se3` 门禁未通过。

RTK–IMU 链路直接利用双天线基线、GNSS 位置和 Doppler 速度，并以机械测量给出天线相位中心相对 IMU 的绝对杆臂。它不是“用 RTK 替代 LiDAR”，而是针对 LiDAR–IMU 平移不可观的问题，采用更直接的天线位置/速度观测做工程外参验证。

完整理由、两条模型的差异及当前结果见 [LiDAR→RTK–IMU 决策说明](docs/lidar_imu_to_rtk_imu.md)。

## 仓库结构

```text
calibration/
├─ imu_lidar/                 LiDAR–IMU 专用流程，以及双方共用基础模块
├─ rtk_imu/                   RTK–IMU 专用算法包
├─ tools/                     两条链路的命令入口、导出和审计工具
├─ tests/                     自动化测试
├─ docs/                      详细方法、状态、采集与决策说明
├─ artifacts/                 受审核的结果快照；大过程文件仅保留本地
├─ config/                    车辆安装与流程配置
├─ README.md                  本页：仓库总览
└─ README_RTK_IMU.md          RTK–IMU 当前工程流程、结果与复现
```

`rtk_imu/` 只依赖下列 `imu_lidar/` 通用模块：

- `contracts.py`：数据契约。
- `geometry.py`：SO(3)、变换和坐标运算。
- `geodesy.py`：地理坐标到 ENU。
- `imu_io.py`：IMU 读取。
- `imu_preintegration.py`：IMU 预积分、bias 修正与 whitening。
- `rotation_handeye.py`：通用旋转手眼初值器。

RTK–IMU 不得依赖 LiDAR 专用的 `lidar_io.py`、`lidar_deskew.py`、`registration.py`、`pipeline.py`、`phase_a.py` 或 `joint_optimizer.py`。

## 文档入口

| 文档 | 内容 |
| --- | --- |
| [README_RTK_IMU.md](README_RTK_IMU.md) | RTK–IMU 当前候选、状态、流程、审核证据和复现命令。 |
| [docs/lidar_imu_to_rtk_imu.md](docs/lidar_imu_to_rtk_imu.md) | 为什么 LiDAR–IMU 暂不能交平移、为什么引入 RTK–IMU、两者边界与共享代码。 |
| [rtk_imu/README.md](rtk_imu/README.md) | RTK–IMU 包的代码职责与 import 边界。 |
| [docs/rtk_imu_multisource_v3.md](docs/rtk_imu_multisource_v3.md) | G90/HI13 统一导出及 R1b/R2V/R2G/R3 旋转链路。 |
| [docs/rtk_imu_engineering_6dof.md](docs/rtk_imu_engineering_6dof.md) | node-state factor graph、机械先验、验收门禁。 |
| [docs/IMU-LiDAR标定.md](docs/IMU-LiDAR标定.md) | LiDAR–IMU 方法与采集要求。 |
| [docs/20260808_LiDAR-IMU标定现状与问题.md](docs/20260808_LiDAR-IMU标定现状与问题.md) | LiDAR–IMU 当前问题、证据和历史处置记录。 |

## 结果与过程文件

`artifacts/rtk_imu_calibration_v3/` 中只提交审核结论及其关键证据。原始 `.rscap`、统一导出数据、节点状态、checkpoint、调试 JSON 与旧版本过程产物均通过 `.gitignore` 保持本地，不应随提交或推送传播。

每次改动前先确认使用哪一条链路；每次交付前先读取相应 release JSON 中的 accepted gate，而不是仅凭优化器收敛、残差下降或一个看似合理的 4×4 矩阵下结论。

## LiDAR–IMU 专用运行指南

[README_Lidar_IMU.md](README_Lidar_IMU.md) 保留 LiDAR–IMU 的独立运行命令、合成复现与输入输出说明；它是远端原 README 的专用化重命名，不再承担仓库总导航职责。