# 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):**

```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  |

**读取示例:**

```python
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`)

```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)