calibration/docs/V1_数据格式.md

# V1 标准中间数据格式

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

## 从原始数据导出

**推荐（新 H32 + HI13）：** HI13 `.rscap` + 雷达 Medulla dlog / recovered zip（raw MSOP + DIFOP）。

```powershell
python tools\export_rscap_to_v1.py `
  --imu-rscap path\to\hi13r4-imu.rscap `
  --imu-kind hi13 `
  --lidar-dlog path\to\session_or_dlog_or_recovered.zip `
  --host-start 2026-08-08T17:40:05 `
  --host-end 2026-08-08T17:45:15 `
  --out path\to\session_v1 `
  --frame-stride 5 `
  --require-difop
```

`--lidar-dlog` 可为：标准 `dobject/`+`dobject_recording/` 目录，或 recovered zip（`indices.log` + `data.bin`）。  
`--imu-kind`：`hi13` / `n300` / `auto`（默认按文件名推断）。  
`--host-start/end`：按本地墙钟切窗（仅裁剪；标定主轴仍是设备时间）。  
默认 DObject：`frontlidar-msop-raw`、`frontlidar-difop-raw`。

**兼容旧 MSOP-only `.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`。  
标定主轴仍是**设备时间**；同时写出**主机 UTC 接收时间**，用于把雷达帧桥接到 IMU 设备钟（禁止把两边设备时间第一帧强行重合）。

## IMU

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

### CSV

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

| 列 | 含义 | 单位 |
|---|---|---|
| t | IMU 设备时钟时间 | s |
| gx,gy,gz | 角速度 | rad/s |
| ax,ay,az | 比力/加速度 | m/s² |
| t_host_utc_s | 主机 UTC 接收时间（Unix） | s |
| receive_utc_ticks | 同上，.NET UTC ticks | — |

### 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,host_receive_utc_ticks,t_host_utc_s,host_receive_utc_end_ticks,t_host_utc_end_s
0,frames/frame_00000.npz,10.000,10.100,6389...,1754646005.12,6389...,1754646005.22
```

| 列 | 含义 |
|---|---|
| t_start / t_end | H32 MSOP **设备时间**（秒） |
| t_host_utc_s / t_host_utc_end_s | 帧首/末包 **HostReceiveUtcTicks** → Unix 秒 |

也兼容旧列名 `file`。对齐脚本用主机 UTC 把 `t_*` 重写到 IMU 设备钟后再跑标定。

### 每帧 NPZ

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

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

可以，前提是：

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

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

## 最小可用会话

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