# UZH-FPV Velocity Prediction

从 DAVIS 事件相机灰度图像序列预测机体速度（body-frame forward/lateral velocity）。

## 项目结构

```
uzh_fpv/
├── AGENTS.md
├── requirements.txt
├── DATASET_FORMAT.md
├── rosbag2wds.py                      # ROS bag → WebDataset shard
├── batch_convert.sh
├── dataset/                           # 数据集（.gitignore）
│   └── <scene_name>/
│       ├── shard_0000.tar
│       ├── imu_sequence.npz
│       └── metadata.json
├── src/
│   ├── event_utils.py                 # 帧间亮度变化 → 模拟事件帧
│   └── velocity_prediction/           # 主项目代码
│       ├── config.py
│       ├── utils.py
│       ├── transforms.py
│       ├── dataset.py
│       ├── model.py
│       ├── train.py
│       └── evaluate.py
├── visualize/
│   └── visualize_dataset.py
├── checkpoints/                       # 模型权重（.gitignore）
├── logs/                              # TensorBoard 日志（.gitignore）
└── videos/                            # 可视化输出（.gitignore）
```

## 运行环境

```bash
uv run python -m <module>
```

依赖：PyTorch, WebDataset, OpenCV, NumPy, Matplotlib。

## 数据集

UZH-FPV 数据集，DAVIS 事件相机采集。每个场景目录：

| 文件 | 格式 | 内容 |
|------|------|------|
| `shard_*.tar` | WebDataset | 灰度图 (320×240) + 位姿 + 速度 + 时间戳 |
| `imu_sequence.npz` | NPZ | 完整 IMU 序列（加速度+角速度） |
| `metadata.json` | JSON | 场景元信息 |

shard 样本字段：

| Key | 类型 | 说明 |
|-----|------|------|
| `jpg` | JPEG bytes | 灰度图 320×240 |
| `ts` | float64 | 时间戳 |
| `pose` | float32[7] | `[x, y, z, qx, qy, qz, qw]` 世界→机体四元数 |
| `vel` | float32[6] | `[vx, vy, vz, wx, wy, wz]` 世界线速度 + 角速度 |

### 场景列表

| 场景 | 帧数 | 类型 |
|------|------|------|
| indoor_forward_3/5/6/7/9/10 | 627~4918 | 室内前飞 |
| indoor_45_2/4/9/12/13/14 | 656~1472 | 室内 45° 飞行 |
| outdoor_forward_1/3/5 | 907~13299 | 室外前飞 |
| outdoor_45_1 | 799 | 室外 45° 飞行 |

## 关键命令

```bash
# 训练（GPU 优先 cuda:7）
uv run python -m src.velocity_prediction.train --device cuda:7

# 数据集可视化（单场景）
uv run python -m visualize.visualize_dataset --scene indoor_forward_3 --output videos/scene.mp4

# 数据集可视化（全部场景）
uv run python -m visualize.visualize_dataset --all --output videos/

# 数据集可视化（实时显示）
uv run python -m visualize.visualize_dataset --scene indoor_forward_3 --show
```