calibration/docs/雷达-IMU标定.md

雷达–IMU 标定

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

目标与当前结论

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

p_IMU = T_IMU_lidar · p_lidar

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

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

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

方法概览

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

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

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。

输入、输出与配置

输入

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 可转换为上述格式：

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	用于复核和点云可视化的相对运动对

运行与判读

安装依赖：

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

先运行仅旋转模式：

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 -File tools\reproduce_synthetic.ps1
python -m pytest -q

采集要求

单次有效会话建议：

静止 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，自动化测试说明见 tests/README.md。