calibration/docs/V1_数据格式.md

V1 标准中间数据格式

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

从原始数据导出

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

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：

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

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

目录结构：

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

frames_index.csv

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 帧，场景有墙/柱等结构，含转弯