calibration/tests/README.md

测试说明

本目录说明两类试验的边界，避免把「合成通过」或「旧车 blocked」误读成实车外参已交付 / 算法不可用。

总览见根目录 README.md §0。

试验	是否默认 pytest	在证明什么	不在证明什么
合成数据	是	算法链路正确、能收回已知 yaw / δt	实车安装精度、平移可交付
旧车 S2	否（线下手工）	主机时间旧数据上流水线能跑完；质量门会拒绝坏结果	外参真值；新车可用性

---

1. 自动化测试（合成数据 / pytest）

入口：tests/test_v1_pipeline.py
命令：

cd <仓库根目录>
python -m pytest -q

测试	输入	在测什么	期望结果
test_rotation_handeye_recovers_yaw	合成运动对（无点云）	旋转手眼能否收回已知 yaw	旋转误差 < 1°
test_time_offset_on_synthetic	合成会话（故意加 δt）	模长相关粗估时间偏置	|δt 误差| < 0.05 s
test_signed_time_offset_refine_improves_or_keeps	同上 + 真值 R	有符号三轴 δt 精修	不比粗估明显更差
test_preintegration_bias_jacobian_matches_finite_difference	随机陀螺序列	旋转预积分 J_bg	与有限差分一致（松阈值）
test_imu_preintegration_recovers_constant_accel_translation	常值加速度	完整预积分 Δv/Δp	接近解析值
test_imu_preintegration_bias_jacobian_finite_difference	随机 IMU	J_bg/J_ba 一阶修正	与重积分接近
test_synthetic_pipeline_rotation_and_time_offset	端到端合成会话	rotation_only 全流程	rotation_only_accepted；δt 准；手眼 RMS < 5°
test_synthetic_pipeline_full_se3_smoke	同上	full_se3 不崩溃	状态为 accepted / rejected / rotation_only 之一

合成数据由 tools/generate_synthetic_session.py 生成（墙面点云 + 已知外参 yaw 与 δt）。
一键复现见根目录 README：tools/reproduce_synthetic.py。

---

2. 旧车 S2 线下试验（不在默认 pytest 里）

用了什么数据

项	内容
车辆 / 批次	旧 S2 验证集（主机时间时代的录制）
典型路径	D:\IMU_calibration\work\S2_scheme1_validation\（历史目录名；含 imu.csv + 雷达会话）
IMU 时间	主机 UTC 接收时间（串口块到达时刻），不是 IMU 设备时间
雷达时间	dlog 导出的主机侧 unix_time_ns，不是 MSOP 设备时间
帧率特征	雷达约 1 Hz 量级，关键帧间隔偏长
配置烟测	config/s2_old_smoke.yaml（仅声明为旧数据烟测，不当交付）

这些数据只能用来验证流水线能否跑通，不能当作新车外参真值来源。
blocked 是质量门的预期结果，不是「算法突然坏了」。

做了什么测试

对同一批 S2 中间格式多次跑 cli run，例如：

• 预积分加强后的输出目录（本机历史名如 out_scheme2_preint）
• 有符号 δt / 联合精修后的输出（本机历史名如 out_scheme2_phaseA）
• 用 tools/compare_s2_runs.py 对比两次 summary.json

命令形态（路径按本机实际修改；雷达会话目录若仍叫 scheme2_session 为历史命名）：

python -m imu_lidar.cli run `
  --vehicle-config config\s2_old_smoke.yaml `
  --imu D:\IMU_calibration\work\S2_scheme1_validation\imu.csv `
  --lidar D:\IMU_calibration\work\S2_scheme1_validation\scheme2_session `
  --output path\to\out_s2 `
  --mode rotation_only `
  --time-offset-search-s 2.0

python tools\compare_s2_runs.py path\to\out_old\summary.json path\to\out_new\summary.json

得到什么结果（记录摘要）

指标	预积分加强一轮	有符号 δt / 精修一轮
status	blocked（预期）	blocked（预期）
手眼 RMS	约 15.0°	约 14.5°
手眼中位数	—	约 6.8°
δt	约 −2.0 s	约 −1.75 s（有修正）
相关峰	很弱（约 0.18）	仍弱（约 0.13）
结论	链路可跑	残差略降，但 不当交付外参

原因归纳：

1. 时间戳是主机时间，相关峰弱，δt / yaw / 零偏互相耦合；
2. 雷达约 1 Hz，运动对间隔长，IMU 侧更易漂；
3. 质量门主动 blocked，避免把坏结果当成安装参数。

正式标定必须改用设备时间（IMU device_timestamp、雷达 MSOP 设备时）重新采集后再跑。

---

3. 配准结果怎么目视检查

标定跑完后（合成或实车）：

python tools\visualize_pair_3d.py `
  --lidar examples\synthetic_session\lidar `
  --imu examples\synthetic_session\imu.csv `
  --summary examples\synthetic_session\out\summary.json `
  --pair-index 0 `
  --save-png examples\synthetic_session\out\pair0_overlay.png

交互窗口快捷键：1–4 切换叠点模式；N/] 下一运动对，P/[ 上一运动对。
无显示器时加 --no-gui --save-png ... 只出俯视图 PNG。