calibration/docs/V1_数据格式.md

# V1 标准中间数据格式

**用途：** 标定程序读入的 CSV/NPZ 约定，以及新车 `.rscap` 如何导出。总览见根目录 [README](../README.md)。

## 从原始 `.rscap` 导出

```powershell
python tools\export_rscap_to_v1.py `
  --imu-rscap path\to\n300.rscap `
  --lidar-rscap path\to\h32_msop.rscap `
  --out path\to\session_v1 `
  --frame-stride 1
```

产出：`imu.csv`、`lidar/`（含 `frames_index.csv`）、`export_summary.json`。  
时间轴为**设备时间**：N300 `device_timestamp_us`→秒；H32 MSOP `device_timestamp_ms`→秒。主机接收时间不写入标定主轴。

## IMU

文件：`imu.csv` 或 `imu.npz`

### CSV

```text
t,gx,gy,gz,ax,ay,az
0.000000000,0.01,-0.02,0.00,0.05,-0.03,9.81
...
```

| 列 | 含义 | 单位 |
|---|---|---|
| t | IMU 时钟时间 | s |
| gx,gy,gz | 角速度 | rad/s |
| ax,ay,az | 比力/加速度 | m/s² |

### NPZ

数组：`t (N,)`, `gyro (N,3)`, `acc (N,3)`，含义同上。

> IMU 与 LiDAR 的时间原点可以不同。流水线会估计常值偏置：`t_imu = t_lidar + delta_t`。

## LiDAR

目录结构：

```text
lidar_session/
├── frames_index.csv
└── frames/
    ├── frame_00000.npz
    ├── frame_00001.npz
    └── ...
```

### frames_index.csv

```text
frame_id,filename,t_start,t_end
0,frames/frame_00000.npz,10.000,10.100
1,frames/frame_00001.npz,10.100,10.200
```

也兼容旧列名 `file`（NumPy 读取时可能变成 `file_`）。

### 每帧 NPZ

- `points`: `float64/float32`，形状 `(N, 3)`，LiDAR 直角坐标系，单位米

## 时间不同步能不能用？

可以，前提是：

1. 两边都覆盖同一段**有角速度激励**的物理运动（尤其是转弯）；
2. 偏置近似为**常数**（短会话）；
3. `--time-offset-search-s` 足够覆盖可能的偏移（默认 ±1 s，可加大）。

若两段数据完全不是同一趟行驶，或只有静止 IMU、没有重叠运动，则无法估 δt，标定会被 `blocked`。

## 最小可用会话

- IMU：建议含静止段 + 运动段，采样率稳定
- LiDAR：建议 ≥ 20 帧，场景有墙/柱等结构，含转弯