initial commit

DATASET_FORMAT.md

@@ -0,0 +1,95 @@
+# 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)