uzh-fpv-sv-test/DATASET_FORMAT.md

UZH FPV Dataset Format

由 rosbag2wds.py 从 DAVIS 事件相机 ROS bag 转换生成

目录结构

dataset/
├── <dataset_name>/
│   ├── shard_0000.tar        # WebDataset shard (图像 + 对齐的 GT)
│   ├── shard_0001.tar
│   ├── ...
│   ├── imu_sequence.npz      # 完整 IMU 序列 (独立存储)
│   └── metadata.json         # 数据集元信息

文件说明

1. WebDataset Shard (shard_*.tar)

每个 tar 文件包含 shard_size 个样本（默认 2000），每个样本的 key 为 frame_<index>，包含以下字段：

Key	类型	内容
jpg	JPEG bytes	灰度图，尺寸 320×240，JPEG quality=85
ts	float64	图像时间戳（ROS bag 系统时间 t.to_sec()）
pose	float32[7]	位姿：[x, y, z, qx, qy, qz, qw]（位置 + 单位四元数）
vel	float32[6]	速度：[vx, vy, vz, wx, wy, wz]（线速度 + 角速度）

读取示例 (Python):

import webdataset as wds

dataset = wds.WebDataset("dataset/<name>/shard_0000.tar")
for sample in dataset:
    img = sample["jpg"]       # JPEG bytes
    ts = sample["ts"]         # bytes -> np.frombuffer(..., dtype=np.float64)
    pose = sample["pose"]     # bytes -> np.frombuffer(..., dtype=np.float32).reshape(7)
    vel = sample["vel"]       # bytes -> np.frombuffer(..., dtype=np.float32).reshape(6)

2. IMU 序列 (imu_sequence.npz)

独立存储的完整 IMU 数据（NPZ 压缩格式），包含三个数组：

Key	类型	形状	内容
timestamps	float64	(N,)	IMU 时间戳
accelerations	float32	(N, 3)	线性加速度 (ax, ay, az) m/s²
angular_velocities	float32	(N, 3)	角速度 (gx, gy, gz) rad/s

读取示例:

import numpy as np
data = np.load("dataset/<name>/imu_sequence.npz")
timestamps = data["timestamps"]
acc = data["accelerations"]
gyro = data["angular_velocities"]

3. 元信息 (metadata.json)

{
  "dataset_name": "indoor_forward_7",
  "source_bag": "/mnt/indoor_forward_7_davis_with_gt.bag",
  "num_images": 2459,
  "num_imu_messages": 66632,
  "num_ground_truth": 33350,
  "image_size": [320, 240],
  "imu_frequency_hz": 999.02,
  "camera_frequency_hz": 36.89,
  "gt_frequency_hz": 500.01,
  "coordinate_system": "horizontal (z aligned with gravity, assumed from GT)",
  "velocity_dimensions": 6
}

数据来源

Topic	内容	频率 (典型值)
/dvs/image_raw	灰度图像 (mono8)	~30–50 Hz
/dvs/imu	IMU (加速度+角速度)	~1000 Hz
/groundtruth/odometry	位姿真值	~500 Hz

预处理说明

• 时间戳: 统一使用 ROS bag 系统时间 t.to_sec()，而非 msg.header.stamp
• 时间对齐: 图像与 GT 通过最近邻时间戳匹配，最大允许偏差 0.1s
• 速度计算: GT 速度由位姿差分计算（前向/后向有限差分 + 四元数旋转向量），忽略 bag 中原始 twist 数据
• 时间裁剪: 所有数据裁剪至 GT 时间范围内，去除首尾无 GT 的片段
• 图像缩放: 原始 DAVIS 分辨率 240×180 → 缩放至 320×240 (INTER_LINEAR)