重整双链路标定文档与求解说明

README.md

@@ -1,184 +1,65 @@
-# LiDAR–IMU 外参标定
+# 车辆多传感器外参标定
 
-用连续行驶中的 LiDAR 与 IMU 相对运动，估计安装外参与时间偏置：
+本仓库同时维护两条独立的外参标定链路：LiDAR–IMU 与 RTK–IMU。两条链路共享通用的几何和 IMU 预积分基础能力，但各自的观测模型、求解器、工具入口和验收结论独立管理。
+
+## 当前应如何使用
+
+| 目标 | 推荐链路 | 当前可交付状态 |
+| --- | --- | --- |
+| LiDAR 与 IMU 的旋转、时间对齐 | LiDAR–IMU | 旋转与主机桥接时间对齐可冻结；完整平移不可交付。 |
+| RTK 天线相位中心与 IMU 的工程外参 | RTK–IMU | 机械杆臂经动态数据一致性验证；data-only 平移及正式 engineering 放行尚未通过。 |
+| 需要完整 RTK–IMU 工程候选和复现方式 | RTK–IMU | 先阅读 [README_RTK_IMU.md](README_RTK_IMU.md)。 |
+
+不要把任何一条链路未通过的平移结果当作已标定的 6DoF 外参。结果的接受状态以对应 JSON 中的 gate 为准。
+
+## 为什么同时保留两条链路
+
+LiDAR–IMU 链路通过点云相对运动与 IMU 预积分求手眼外参，适合旋转与时间对齐；但当前实车数据的加速度预积分位移，尤其 Z 分量，不足以支持可靠平移求解，且主要采集运动缺乏竖直激励。因此它的 `full_se3` 门禁未通过。
+
+RTK–IMU 链路直接利用双天线基线、GNSS 位置和 Doppler 速度，并以机械测量给出天线相位中心相对 IMU 的绝对杆臂。它不是“用 RTK 替代 LiDAR”，而是针对 LiDAR–IMU 平移不可观的问题，采用更直接的天线位置/速度观测做工程外参验证。
+
+完整理由、两条模型的差异及当前结果见 [LiDAR→RTK–IMU 决策说明](docs/lidar_imu_to_rtk_imu.md)。
+
+## 仓库结构
 
 ```text
-p_IMU = T_IMU_lidar · p_lidar
+calibration/
+├─ imu_lidar/                 LiDAR–IMU 专用流程，以及双方共用基础模块
+├─ rtk_imu/                   RTK–IMU 专用算法包
+├─ tools/                     两条链路的命令入口、导出和审计工具
+├─ tests/                     自动化测试
+├─ docs/                      详细方法、状态、采集与决策说明
+├─ artifacts/                 受审核的结果快照；大过程文件仅保留本地
+├─ config/                    车辆安装与流程配置
+├─ README.md                  本页：仓库总览
+└─ README_RTK_IMU.md          RTK–IMU 当前工程流程、结果与复现
 ```
 
-**当前阶段：** 算法与合成自检已闭环；已提供 `tools/export_rscap_to_v1.py`（N300 `.rscap` + H32 dlog/MSOP → 中间格式）；**合格实车验收尚未完成**，故正式外参尚未对实车落盘交付。
+`rtk_imu/` 只依赖下列 `imu_lidar/` 通用模块：
 
----
+- `contracts.py`：数据契约。
+- `geometry.py`：SO(3)、变换和坐标运算。
+- `geodesy.py`：地理坐标到 ENU。
+- `imu_io.py`：IMU 读取。
+- `imu_preintegration.py`：IMU 预积分、bias 修正与 whitening。
+- `rotation_handeye.py`：通用旋转手眼初值器。
 
-## 先看什么（对外三份就够）
+RTK–IMU 不得依赖 LiDAR 专用的 `lidar_io.py`、`lidar_deskew.py`、`registration.py`、`pipeline.py`、`phase_a.py` 或 `joint_optimizer.py`。
 
+## 文档入口
 
-| 顺序  | 文档                                     | 用途                   |
-| --- | -------------------------------------- | -------------------- |
-| 1   | **本 README**                           | 做什么、怎么跑、结果怎么判        |
-| 2   | [docs/V1_数据格式.md](docs/V1_数据格式.md)     | 中间格式 + 原始数据导出命令 |
-| 3   | [docs/标定流程与采集清单.md](docs/标定流程与采集清单.md) | 现场怎么采（合格数据要求）        |
+| 文档 | 内容 |
+| --- | --- |
+| [README_RTK_IMU.md](README_RTK_IMU.md) | RTK–IMU 当前候选、状态、流程、审核证据和复现命令。 |
+| [docs/lidar_imu_to_rtk_imu.md](docs/lidar_imu_to_rtk_imu.md) | 为什么 LiDAR–IMU 暂不能交平移、为什么引入 RTK–IMU、两者边界与共享代码。 |
+| [rtk_imu/README.md](rtk_imu/README.md) | RTK–IMU 包的代码职责与 import 边界。 |
+| [docs/rtk_imu_multisource_v3.md](docs/rtk_imu_multisource_v3.md) | G90/HI13 统一导出及 R1b/R2V/R2G/R3 旋转链路。 |
+| [docs/rtk_imu_engineering_6dof.md](docs/rtk_imu_engineering_6dof.md) | node-state factor graph、机械先验、验收门禁。 |
+| [docs/IMU-LiDAR标定.md](docs/IMU-LiDAR标定.md) | LiDAR–IMU 方法与采集要求。 |
+| [docs/20260808_LiDAR-IMU标定现状与问题.md](docs/20260808_LiDAR-IMU标定现状与问题.md) | LiDAR–IMU 当前问题、证据和历史处置记录。 |
 
+## 结果与过程文件
 
-其余（方法细述、测试说明、源码职责、CHANGELOG）给深入阅读 / 改代码时用，见文末。
+`artifacts/rtk_imu_calibration_v3/` 中只提交审核结论及其关键证据。原始 `.rscap`、统一导出数据、节点状态、checkpoint、调试 JSON 与旧版本过程产物均通过 `.gitignore` 保持本地，不应随提交或推送传播。
 
----
-
-
-
-## 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。
+每次改动前先确认使用哪一条链路；每次交付前先读取相应 release JSON 中的 accepted gate，而不是仅凭优化器收敛、残差下降或一个看似合理的 4×4 矩阵下结论。