diff --git a/README.md b/README.md index 2c38e52..ec35d5b 100644 --- a/README.md +++ b/README.md @@ -63,3 +63,7 @@ RTK–IMU 不得依赖 LiDAR 专用的 `lidar_io.py`、`lidar_deskew.py`、`regi `artifacts/rtk_imu_calibration_v3/` 中只提交审核结论及其关键证据。原始 `.rscap`、统一导出数据、节点状态、checkpoint、调试 JSON 与旧版本过程产物均通过 `.gitignore` 保持本地,不应随提交或推送传播。 每次改动前先确认使用哪一条链路;每次交付前先读取相应 release JSON 中的 accepted gate,而不是仅凭优化器收敛、残差下降或一个看似合理的 4×4 矩阵下结论。 + +## LiDAR–IMU 专用运行指南 + +[README_Lidar_IMU.md](README_Lidar_IMU.md) 保留 LiDAR–IMU 的独立运行命令、合成复现与输入输出说明;它是远端原 README 的专用化重命名,不再承担仓库总导航职责。 diff --git a/README_Lidar_IMU.md b/README_Lidar_IMU.md new file mode 100644 index 0000000..e751b79 --- /dev/null +++ b/README_Lidar_IMU.md @@ -0,0 +1,184 @@ +# LiDAR–IMU 外参标定 + +用连续行驶中的 LiDAR 与 IMU 相对运动,估计安装外参与时间偏置: + +```text +p_IMU = T_IMU_lidar · p_lidar +``` + +**当前阶段:** 算法与合成自检已闭环;已提供 `tools/export_rscap_to_v1.py`(N300 `.rscap` + H32 dlog/MSOP → 中间格式);**合格实车验收尚未完成**,故正式外参尚未对实车落盘交付。 + +--- + +## 先看什么(对外三份就够) + + +| 顺序 | 文档 | 用途 | +| --- | -------------------------------------- | -------------------- | +| 1 | **本 README** | 做什么、怎么跑、结果怎么判 | +| 2 | [docs/V1_数据格式.md](docs/V1_数据格式.md) | 中间格式 + 原始数据导出命令 | +| 3 | [docs/标定流程与采集清单.md](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): + +```powershell +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. 一键复现(合成,不需实车) + +```powershell +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`)。叠点查看: + +```powershell +# 优先读取 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 +``` + +旧标定目录若缺少缓存,可只补导出运动对(不重求解外参): + +```powershell +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. 标定: + +```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 +``` + +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](tests/README.md)。 + +--- + + + +## 6. 仓库结构与其余文档 + +```text +imu_lidar/ 算法与 CLI +config/ 车辆配置模板 +docs/ 采集清单、数据格式、方法细述 +tools/ 导出、合成复现、可视化 +tests/ 自动化测试 +``` + + +| 文档 | 何时看 | +| ------------------------------------------------ | ---------------- | +| [docs/IMU-LiDAR标定.md](docs/IMU-LiDAR标定.md) | 要看方法约定与实现状态表 | +| [tests/README.md](tests/README.md) | 要看合成用例 / S2 烟测记录 | +| [imu_lidar/文件职责说明.md](imu_lidar/文件职责说明.md) | 要改源码 | +| [imu_lidar/CHANGELOG.md](imu_lidar/CHANGELOG.md) | 要查改动史 | + + +改算法请同步职责说明与 CHANGELOG;改对外用法请更新本 README。 \ No newline at end of file