calibration/README.md

LiDAR–IMU 外参标定

用连续行驶中的 LiDAR 与 IMU 相对运动，估计安装外参与时间偏置：

p_IMU = T_IMU_lidar · p_lidar

当前阶段： 算法与合成自检已闭环；已提供 tools/export_rscap_to_v1.py（N300 .rscap + H32 dlog/MSOP → 中间格式）；合格实车验收尚未完成，故正式外参尚未对实车落盘交付。

---

先看什么（对外三份就够）

顺序	文档	用途
1	本 README	做什么、怎么跑、结果怎么判
2	docs/V1_数据格式.md	中间格式 + 原始数据导出命令
3	docs/标定流程与采集清单.md	现场怎么采（合格数据要求）

其余（方法细述、测试说明、源码职责、CHANGELOG）给深入阅读 / 改代码时用，见文末。

---

1. 输入 / 输出

输入	说明
imu.csv	t,gx,gy,gz,ax,ay,az（秒；rad/s；m/s²）；t 用设备时间
雷达会话目录	frames_index.csv + frames/*.npz（米制 XYZ）
车辆 YAML	轴向与时间语义；外参真值可空（config/vehicle_installation.template.yaml）

输出	说明
T_IMU_lidar.json	外参
time_offset.json	t_imu = t_lidar + δt
summary.json	状态、残差、可观性

新车原始数据导出（H32 dlog/zip + HI13 rscap）：

python tools\export_rscap_to_v1.py `
  --imu-rscap path\to\hi13r4-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

---

2. 一键复现（合成，不需实车）

cd <本仓库根目录>
python -m pip install -e ".[dev]"
python -m pip install -e ".[open3d]"   # 推荐
powershell -File tools\reproduce_synthetic.ps1

证明：链路可跑通，能收回已知 yaw / δt。
不证明：实车安装精度、平移可交付。

产物在 examples/synthetic_session/out/（含 summary.json 与 motion_pairs.json）。叠点查看：

# 优先读取 summary 同目录的 motion_pairs.json，按需加载点云（无需重算配准）
python tools\visualize_pair_3d.py `
  --lidar examples\synthetic_session\lidar `
  --summary examples\synthetic_session\out\summary.json `
  --pair-index 0

旧标定目录若缺少缓存，可只补导出运动对（不重求解外参）：

python tools\export_motion_pairs_for_viz.py `
  --lidar path\to\lidar `
  --imu path\to\imu.csv `
  --summary path\to\out\summary.json

键 1–4 切换叠点模式；N/P 切换运动对。

---

3. 真实数据怎么跑

1. 按采集清单录制（设备时间；静止 + 低速转弯；有结构场景）
2. 导出中间格式（第1节命令）
3. 填写车辆 YAML 的轴向与时间语义
4. 标定：

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

1. 看 summary.json，再叠点 / 用验证会话复核后才交付

模式	交付	成功标志
rotation_only（先做）	旋转 + δt	rotation_only_accepted
full_se3（激励够再试）	+ 可观平移	full_se3_accepted（否则平移拒绝）

summary.json 状态	含义
rotation_only_accepted / full_se3_accepted	可进入验证
full_se3_rejected_due_to_observability	旋转可用，平移不交
blocked	不可作安装参数

预期量级：旋转约 0.5°–2°；水平平移数厘米～十几厘米；无坡时竖直常不可观。

---

4. 方法（一句话）

关键帧雷达配准得 B，同区间 IMU 预积分得 A，解 R_A R_X ≈ R_X R_B；再估 δt。可观时才在 full_se3 下交平移。

---

5. 试验边界（勿误读）

	合成 pytest	旧车 S2 线下
目的	回归算法	验证旧主机时间数据上链路能跑完
期望	rotation_only_accepted	blocked（预期）
当安装参数？	否	否

细节：tests/README.md。

---

6. 仓库结构与其余文档

imu_lidar/   算法与 CLI
config/      车辆配置模板
docs/        采集清单、数据格式、方法细述
tools/       导出、合成复现、可视化
tests/       自动化测试

文档	何时看
docs/IMU-LiDAR标定.md	要看方法约定与实现状态表
tests/README.md	要看合成用例 / S2 烟测记录
imu_lidar/文件职责说明.md	要改源码
imu_lidar/CHANGELOG.md	要查改动史

改算法请同步职责说明与 CHANGELOG；改对外用法请更新本 README。