# 雷达–IMU 标定

本文是本仓库雷达–IMU 标定的唯一规范说明，覆盖目标、数据格式、运行方式、当前实车结果和采集要求。

## 目标与当前结论

目标是求雷达坐标系到 IMU 坐标系的安装关系：

```text
p_IMU = T_IMU_lidar · p_lidar
```

`T_A_B` 表示把 B 坐标系中的点变换到 A 坐标系。流程利用连续行驶中的相对运动，而不是把 IMU 加速度二次积分的长时间轨迹当作绝对真值。

当前 2026-08-08 实车数据的结论是：**旋转和主机桥接后的时间关系可作为候选冻结；完整平移不可交付。** 不应把旋转结果和零平移拼成看似完整的 4×4 外参，更不能把当前 IMU 位移预积分用于正式平移标定。

| 项目 | 当前状态 |
| --- | --- |
| 连续运动雷达–IMU 流程 | 已实现并有合成测试 |
| 实车旋转候选 | 三个窗口一致，可用于进一步验证 |
| 实车时间关系 | 主机桥接后冻结为 `0 s`，不再自由精修 |
| 实车完整平移 | 不可观且受预积分位移误差影响，拒绝交付 |

## 方法概览

```text
设备时间与惯性质量检查
  → 估计或确认两传感器时间关系
  → 雷达关键帧配准得到相对运动
  → 同一时间区间的 IMU 预积分得到相对运动
  → 先求旋转手眼关系
  → 只有平移可观时才进入完整六自由度优化
```

对关键帧区间 `[i, j]`：

```text
A_ij ≈ IMU 预积分相对运动
B_ij ≈ 雷达点云配准相对运动
A_ij · X ≈ X · B_ij
X = T_IMU_lidar
```

旋转子问题为 `R_A · R_X = R_X · R_B`。旋转通常比平移稳定：加速度偏置和重力方向的微小误差会在位移积分中快速累积，平面转弯又难以提供竖直杆臂信息。因此，完整六自由度只有在残差、跨会话一致性和可观性同时通过时才允许输出。

## 当前实车结果与限制

当前可用的三段优先窗口均在主机时间桥接后固定 `time_offset_s=0`，并禁用自由的有符号时间精修：

| 会话窗口 | roll / pitch / yaw（°） | 手眼旋转 RMS（°） |
| --- | --- | ---: |
| `priority_174005_174515` | `-0.398 / 0.108 / 89.998` | 0.625 |
| `priority_174905_175450` | `-0.316 / -0.352 / 90.002` | 0.293 |
| `priority_175910_180530` | `-0.373 / -0.036 / 90.005` | 0.786 |

三段旋转相互差约为 `0.15°–0.47°`。但以下问题阻止平移放行：

1. IMU 预积分的位移，尤其竖直分量，会出现米级甚至更大的漂移；它不能作为可靠平移观测。
2. 当前重点会话以平面转弯为主，缺少持续坡道或俯仰激励，竖直平移弱可观。
3. 允许时间偏移自由精修时，时间与旋转曾发生相互补偿，产生跨窗口矛盾的航向。因此桥接后的偏移固定为零，而不是再次为降低残差调整它。
4. 单一窗口残差小不等于外参正确；必须检查跨窗口一致性与点云叠加。

这也是仓库增加 RTK–IMU 流程的原因：不是替代雷达旋转标定，而是为天线相位中心到 IMU 的平移提供更直接的 GNSS 位置和速度观测。两条流程边界见仓库 [README](../README.md)。

## 输入、输出与配置

### 输入

```text
imu.csv
  t,gx,gy,gz,ax,ay,az
  单位：秒、rad/s、m/s²；t 应为设备时间

lidar_session/
  frames_index.csv              帧编号、文件名、开始/结束时间
  frames/frame_XXXXX.npz        米制 XYZ 点云

vehicle_installation.yaml
  坐标轴、时间语义、可选机械安装信息
```

原始 HI13 IMU `.rscap` 和 H32 雷达 dlog/MSOP 可转换为上述格式：

```powershell
python tools\export_rscap_to_v1.py `
  --imu-rscap path\to\hi13-imu.rscap `
  --imu-kind hi13 `
  --lidar-dlog path\to\session_or_recovered.zip `
  --host-start 2026-08-08T17:40:05 `
  --host-end 2026-08-08T17:45:15 `
  --out path\to\session_v1 `
  --require-difop
```

### 输出

| 文件 | 含义 |
| --- | --- |
| `T_IMU_lidar.json` | 通过验收时的外参；仅旋转模式下不能把其中平移当交付值 |
| `time_offset.json` | 定义为 `t_imu = t_lidar + δt` 的时间关系 |
| `summary.json` | 状态、残差、可观性和拒绝原因 |
| `motion_pairs.json` | 用于复核和点云可视化的相对运动对 |

## 运行与判读

安装依赖：

```powershell
python -m pip install -e ".[dev]"
python -m pip install -e ".[open3d]"   # 点云处理需要时安装
```

先运行仅旋转模式：

```powershell
python -m imu_lidar.cli run `
  --vehicle-config config\vehicle_installation.template.yaml `
  --imu path\to\session_v1\imu.csv `
  --lidar path\to\session_v1\lidar `
  --output path\to\out `
  --mode rotation_only `
  --time-offset-search-s 2.0
```

| `summary.json` 状态 | 含义 |
| --- | --- |
| `rotation_only_accepted` | 旋转与时间关系可进入独立验证；不代表平移可用 |
| `full_se3_accepted` | 仅当完整平移可观且门禁通过时，才可交付完整外参 |
| `full_se3_rejected_due_to_observability` | 旋转可用，平移拒绝 |
| `blocked` | 时间、质量或模型门禁失败，不能作安装参数 |

合成复现可验证软件链路，不证明实车精度：

```powershell
powershell -File tools\reproduce_synthetic.ps1
python -m pytest -q
```

## 采集要求

单次有效会话建议：

```text
静止 20–30 s → 连续低速多方向转弯 3–8 min → 静止 10–20 s
```

- 必须保留雷达和 IMU 的设备时间戳；不能仅依赖主机接收时间。
- 在结构化环境采集，保证点云配准具有稳定几何约束。
- 旋转标定优先包含左右圆或“8”字；直线加减速有助于时间和水平平移。
- 若要尝试完整平移，增加连续缓坡、俯仰或其他竖直激励；仅平面运动通常不足。
- 标定全过程不得改变两传感器安装关系。

## 代码结构

`imu_lidar/` 是雷达–IMU 专用实现：

| 组件 | 作用 |
| --- | --- |
| `cli.py`、`pipeline.py` | 命令行入口与流程编排 |
| `lidar_io.py`、`registration.py`、`keyframes.py` | 点云读取、配准和关键帧 |
| `timestamp_audit.py`、`imu_audit.py`、`time_offset.py` | 时间和 IMU 质量检查、时间关系估计 |
| `imu_preintegration.py`、`motion_pairs.py` | IMU 预积分与相对运动对 |
| `rotation_handeye.py`、`joint_optimizer.py`、`observability.py` | 旋转求解、联合优化和可观性门禁 |
| `finalize.py` | 结果写出 |

历史改动见 [imu_lidar/CHANGELOG.md](../imu_lidar/CHANGELOG.md)，自动化测试说明见 [tests/README.md](../tests/README.md)。