# `imu_lidar` 模块说明

**用途：** 改 `imu_lidar/` 源码时查阅。对外用法见根目录 [`README.md`](../README.md)。

本包实现 LiDAR–IMU 外参标定：在连续行驶数据上选取关键帧，用 IMU 预积分与雷达配准构造相对运动对，求解安装外参。

```text
A ≈ 关键帧间 IMU 相对运动（预积分：旋转 / 速度增量 / 位移增量）
B ≈ 关键帧间雷达配准
解 R_A R_X = R_X R_B  →  旋转外参（手眼阶段只用旋转）
再精修旋转与陀螺零偏；在完整六自由度模式下，可观时再估计平移等
```

入口：

```powershell
python -m imu_lidar.cli plan
python -m imu_lidar.cli run --vehicle-config ... --imu ... --lidar ... --output ...
```

整体流程由 `pipeline.py` 串联。  
修改本目录代码时，请同步更新本说明，并在 [`CHANGELOG.md`](CHANGELOG.md) 追加「时间戳 + 原本 → 改成」。

---

## 流水线顺序与文件


| 顺序  | 文件                      | 作用                            |
| --- | ----------------------- | ----------------------------- |
| 0   | `contracts.py`          | 公共数据类型与状态枚举                   |
| 0   | `geometry.py`           | 刚体变换与旋转工具                     |
| 0   | `vehicle_config.py`     | 读取并校验车辆 YAML                  |
| 1   | `imu_io.py`             | 读标准 IMU 中间格式                  |
| 1   | `lidar_io.py`           | 读标准雷达会话目录                     |
| 2   | `timestamp_audit.py`    | 时间单调 / 频率 / 空洞检查              |
| 3   | `imu_audit.py`          | 静止零偏、加速度模长检查、建议竖直轴            |
| 4   | `time_offset.py`        | 粗估时间偏置 δt，并用旋转外参精修            |
| 5   | `registration.py`       | 帧间点云配准                        |
| 5   | `keyframes.py`          | 按运动量抽取关键帧                     |
| 5   | `lidar_deskew.py`       | 可选点云去畸变（低速可关）                 |
| 6   | `imu_preintegration.py` | IMU 预积分（旋转及速度/位移增量、协方差、零偏雅可比） |
| 6   | `motion_pairs.py`       | 构造运动对；手眼使用其中的旋转               |
| 6   | `motion_pairs_io.py`    | 运动对 JSON 缓存读写（供可视化直读）          |
| 7   | `rotation_handeye.py`   | 加权旋转手眼                        |
| 8   | `observability.py`      | 旋转 / 平移可观性检查                  |
| 8   | `joint_optimizer.py`    | 联合精修；完整模式下可估计平移、重力、速度与时变零偏    |
| 9   | `finalize.py`           | 写出结果 JSON（含 `motion_pairs.json`） |
| —   | `pipeline.py`           | 编排全流程                         |
| —   | `cli.py`                | 命令行入口                         |
| —   | `CHANGELOG.md`          | 改动记录                          |


---

## 运行模式要点

- **运动对**始终计算完整预积分量（旋转、速度增量、位移增量及不确定度）。
- `--mode rotation_only`：只精修旋转与常值陀螺零偏，交付旋转与时间偏置。
- `--mode full_se3`：当前完成 Phase-A 后明确拒绝平移；待 Phase-B/C 会话状态重构完成后再恢复完整 SE(3) 交付。

---

## 输入格式

```text
imu.csv                         # t,gx,gy,gz,ax,ay,az（建议设备时间）
lidar_session/
  frames_index.csv              # frame_id,filename,t_start,t_end
  frames/frame_XXXXX.npz        # points: (N,3) 米
```

原始 N300 `.rscap` + H32 dlog（或旧 MSOP `.rscap`）用仓库工具导出：`python tools/export_rscap_to_v1.py ...`（见 [`docs/V1_数据格式.md`](../docs/V1_数据格式.md)）。

---

## 当前能力

- 本包是仓库**唯一**标定路径：质检 → 时间偏置 → 关键帧配对 → 旋转手眼 → 联合精修 →（可选）完整六自由度 → 报告  
- 点云去畸变：可选  
- 阶段与用法见根目录 [`README.md`](../README.md)  
- 改动史：[`CHANGELOG.md`](CHANGELOG.md)
