# 无人机水文视频测流 Demo 需求规划

> 基于 ByteTrack 的实时流速测量系统

---

## 一、项目背景

### 1.1 目标
开发一个**无人机视频流速测量 Demo**，实现：
- 无人机航拍水面示踪物
- 实时跟踪示踪物轨迹
- 计算流速分布和断面流量

### 1.2 应用场景

| 场景 | 说明 |
|------|------|
| 洪水应急监测 | 快速获取洪水流速 |
| 河道流量测验 | 代替传统浮标法 |
| 水库泄洪评估 | 实时监测流速分布 |

---

## 二、技术架构

```
┌─────────────────────────────────────────────────────────┐
│                    系统架构图                           │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  ┌──────────┐     ┌──────────┐     ┌──────────┐        │
│  │ 无人机   │────▶│ 边缘计算 │────▶│ 数据展示 │        │
│  │ 摄像机   │     │   设备   │     │   平台   │        │
│  └──────────┘     └──────────┘     └──────────┘        │
│                       │                               │
│              ┌────────┴────────┐                     │
│              ▼                 ▼                       │
│       ┌──────────┐     ┌──────────┐                  │
│       │ YOLOX    │     │ByteTrack│                  │
│       │ 目标检测 │     │ 多目标跟踪│                  │
│       └──────────┘     └──────────┘                  │
│              │                 │                       │
│              └────────┬────────┘                     │
│                       ▼                               │
│              ┌──────────────┐                        │
│              │ 流速计算引擎 │                        │
│              └──────────────┘                        │
│                       │                               │
│                       ▼                               │
│              ┌──────────────┐                        │
│              │ 结果可视化   │                        │
│              └──────────────┘                        │
└─────────────────────────────────────────────────────────┘
```

---

## 三、功能需求

### 3.1 核心功能

| 序号 | 功能 | 优先级 | 说明 |
|------|------|--------|------|
| F1 | 视频输入 | P0 | 支持视频文件 / 摄像头 / RTSP 流 |
| F2 | 目标检测 | P0 | 检测示踪物（泡沫球/氢气球） |
| F3 | 多目标跟踪 | P0 | ByteTrack 实时跟踪 |
| F4 | 轨迹可视化 | P0 | 实时显示跟踪轨迹 |
| F5 | 流速计算 | P0 | 基于轨迹计算流速 |
| F6 | 结果导出 | P1 | 导出轨迹数据和流速结果 |

### 3.2 扩展功能

| 序号 | 功能 | 优先级 | 说明 |
|------|------|--------|------|
| E1 | 参数配置 | P1 | 可配置检测阈值、跟踪参数 |
| E2 | 离线分析 | P2 | 支持事后视频分析 |
| E3 | 多帧平均 | P2 | 平滑流速结果 |
| E4 | 断面流量 | P2 | 计算完整断面流量 |

---

## 四、非功能需求

### 4.1 性能指标

| 指标 | 要求 | 说明 |
|------|------|------|
| 处理帧率 | ≥ 25 FPS | 实时性要求 |
| 跟踪精度 | IDF1 ≥ 70 | 轨迹连续性 |
| 流速误差 | ≤ 15% | 与标准方法对比 |
| 端到端延迟 | ≤ 100ms | 从帧输入到结果输出 |

### 4.2 系统要求

| 项目 | 要求 |
|------|------|
| 运行环境 | Python 3.8+, PyTorch 1.7+ |
| 硬件要求 | NVIDIA GPU (4GB+ VRAM) |
| 边缘部署 | Jetson AGX Xavier / Orin |
| 兼容性 | 支持视频文件 / USB相机 / 网络流 |

### 4.3 可用性

- 配置文件管理参数
- 友好的日志输出
- 异常错误提示

---

## 五、模块设计

### 5.1 模块列表

```
src/
├── video_input/          # 视频输入模块
│   ├── file_reader.py    # 视频文件读取
│   ├── camera_reader.py  # 摄像头读取
│   └── rtsp_reader.py    # RTSP 流读取
├── detector/             # 目标检测模块
│   └── yolox_detector.py # YOLOX 检测器
├── tracker/              # 多目标跟踪模块
│   └── byte_tracker.py   # ByteTrack 跟踪器
├── velocity/             # 流速计算模块
│   ├── tracker.py        # 轨迹管理
│   └── velocity_calc.py  # 流速计算
├── visualizer/           # 可视化模块
│   └── overlay.py        # 结果叠加
└── main.py               # 主程序入口
```

### 5.2 数据结构

```python
# 示踪物检测结果
class Detection:
    bbox: List[float]  # [x1, y1, x2, y2]
    score: float        # 检测置信度
    class_id: int       # 类别

# 跟踪轨迹
class Track:
    track_id: int
    bbox: List[float]
    velocity: Tuple[float, float]  # 像素/秒
    history: List[Tuple[float, float, int]]  # (x, y, frame_id)

# 流速结果
class VelocityResult:
    track_id: int
    velocity_x: float  # m/s
    velocity_y: float  # m/s
    speed: float        # m/s
    direction: float    # rad
```

---

## 六、开发阶段

### Phase 1: 核心框架 (1-2周)

**目标**：完成基础跟踪功能

| 任务 | 工期 | 交付物 |
|------|------|--------|
| 环境搭建 | 1天 | Docker 镜像 |
| 视频输入 | 2天 | 支持文件/摄像头 |
| YOLOX 集成 | 3天 | 检测器封装 |
| ByteTrack 集成 | 3天 | 跟踪器封装 |
| 基础可视化 | 2天 | 轨迹叠加显示 |

**交付物**：可跟踪视频中运动物体的 Demo

### Phase 2: 流速计算 (1周)

**目标**：实现流速计算功能

| 任务 | 工期 | 交付物 |
|------|------|--------|
| 轨迹管理 | 2天 | Track 类 |
| 坐标转换 | 1天 | 像素→物理坐标 |
| 流速计算 | 2天 | VelocityCalc 类 |
| 结果展示 | 1天 | 流速箭头叠加 |

**交付物**：显示流速矢量的 Demo

### Phase 3: 参数调优 (1周)

**目标**：优化检测和跟踪效果

| 任务 | 工期 | 交付物 |
|------|------|--------|
| 参数配置 | 2天 | config.yaml |
| 检测优化 | 2天 | 阈值调优 |
| 跟踪优化 | 2天 | 卡尔曼滤波调参 |

**交付物**：参数可配置的 Demo

### Phase 4: 测试验证 (1周)

**目标**：验证流速精度

| 任务 | 工期 | 交付物 |
|------|------|--------|
| 测试视频采集 | 2天 | 测试数据集 |
| 精度对比 | 3天 | 误差分析报告 |
| 性能优化 | 2天 | 优化后 Demo |

**交付物**：完整 Demo + 测试报告

---

## 七、测试数据需求

### 7.1 测试视频

| 类型 | 内容 | 时长 | 数量 |
|------|------|------|------|
| 室内水槽 | 控制条件 | 30s | 3 |
| 野外河流 | 实测场景 | 60s | 5 |
| 洪水场景 | 应急监测 | 60s | 2 |

### 7.2 对照数据

- ADCP 同步测量数据
- 流速仪对照数据
- 浮标轨迹人工标注

---

## 八、风险评估

| 风险 | 影响 | 概率 | 应对措施 |
|------|------|------|----------|
| 检测效果差 | 高 | 中 | 准备多套检测模型 |
| 跟踪ID跳变 | 中 | 中 | 增加轨迹缓冲 |
| 边缘设备性能不足 | 高 | 低 | 提前测试 Jetson 性能 |
| 流速精度不达标 | 中 | 中 | 多方法对比验证 |

---

## 九、验收标准

### 9.1 功能验收

- [ ] 可读取视频文件并实时显示
- [ ] 检测器可识别示踪物
- [ ] ByteTrack 跟踪轨迹稳定
- [ ] 流速计算结果合理
- [ ] 支持导出结果数据

### 9.2 性能验收

- [ ] 处理帧率 ≥ 25 FPS (1080p)
- [ ] 跟踪轨迹连续，无频繁断裂
- [ ] 流速误差 ≤ 15% (与ADCP对比)

### 9.3 代码质量

- [ ] 代码结构清晰
- [ ] 注释完整
- [ ] 单元测试覆盖核心模块

---

## 十、后续扩展

| 方向 | 说明 |
|------|------|
| 深度优化 | 专用检测器微调 |
| 工程化 | 边缘部署优化 |
| 云端集成 | 数据上传与分析 |
| 自动化 | 无人值守自动测量 |

---

## 附录：技术选型

| 组件 | 选择 | 原因 |
|------|------|------|
| 检测器 | YOLOX | ByteTrack 原生支持，效果好 |
| 跟踪器 | ByteTrack | 双阶段关联，适合遮挡 |
| 深度学习框架 | PyTorch | 生态丰富 |
| 边缘设备 | Jetson AGX Xavier | 算力足够 |
| 编程语言 | Python | 开发效率高 |