# small_mubiao

**Repository Path**: LiLiLiFan_admin/small_mubiao

## Basic Information

- **Project Name**: small_mubiao
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-13
- **Last Updated**: 2026-02-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 火花飞溅轨迹追踪系统 - 使用指南

基于YOLOv8深度学习的火花检测与追踪系统

---

## 快速开始

### 1. 环境安装

```bash
# 安装依赖
pip install -r requirements.txt

# 如果有GPU，确保安装了CUDA版本的PyTorch
# 访问 https://pytorch.org/ 获取适合你系统的安装命令
```

### 2. 完整工作流程

```
视频 → 提取帧 → 标注 → 划分数据集 → 训练模型 → 处理视频 → 导出数据
```

---

## 详细步骤

### 步骤1: 从视频提取帧

```bash
# 从单个视频提取帧（每秒1帧）
python extract_frames.py -i video.mp4 -o frames -t 1.0

# 批量处理目录中的所有视频
python extract_frames.py -d videos_dir -o frames_output -t 1.0

# 只提取某个时间段（2-8秒）
python extract_frames.py -i video.mp4 -o frames -s 2 -e 8 -t 0.5
```

**参数说明:**
- `-i`: 输入视频文件
- `-d`: 输入视频目录（批量处理）
- `-o`: 输出目录
- `-t`: 提取间隔（秒），默认1.0
- `-s`: 开始时间（秒）
- `-e`: 结束时间（秒）

**建议:**
- 每个10秒视频提取30-50帧
- 重点提取有火花的帧
- 也包含一些无火花的帧（负样本）

---

### 步骤2: 标注数据

#### 2.1 安装标注工具

```bash
pip install labelImg
```

#### 2.2 启动LabelImg

```bash
labelImg
```

#### 2.3 配置LabelImg

1. 点击 "Open Dir" 选择图片目录
2. 点击 "Change Save Dir" 选择标注保存目录
3. 切换到 "YOLO" 格式（左侧按钮）
4. 创建 `classes.txt` 文件，内容为: `spark`

#### 2.4 标注原则

- **紧贴火花边缘**：框要紧凑
- **标注所有火花**：即使很小或模糊
- **不标注干扰物**：反光、污渍、纹理等
- **快捷键**：
  - `W`: 创建框
  - `D`: 下一张
  - `A`: 上一张
  - `Ctrl+S`: 保存

**目标数量:**
- 最少: 200-300张
- 推荐: 500-1000张
- 理想: 1000+张

详细标注指南见 [`数据标注指南.md`](数据标注指南.md:1)

---

### 步骤3: 划分数据集

```bash
# 基本划分（80%训练，15%验证，5%测试）
python split_dataset.py -i labeled_data -o spark_dataset

# 自定义比例
python split_dataset.py -i labeled_data -o spark_dataset --train 0.7 --val 0.2 --test 0.1

# 验证数据集
python split_dataset.py --verify spark_dataset
```

**输出结构:**
```
spark_dataset/
├── images/
│   ├── train/
│   ├── val/
│   └── test/
├── labels/
│   ├── train/
│   ├── val/
│   └── test/
└── dataset.yaml
```

---

### 步骤4: 训练YOLO模型

```bash
# 基本训练（使用默认参数）
python train_yolo.py -d spark_dataset

# 自定义参数
python train_yolo.py -d spark_dataset -m s -e 150 -b 32 --imgsz 640

# 使用CPU训练（不推荐，很慢）
python train_yolo.py -d spark_dataset --device cpu
```

**参数说明:**
- `-d`: 数据集目录
- `-m`: 模型大小 (n/s/m/l/x)，n最快，x最准
- `-e`: 训练轮数，默认100
- `-b`: 批次大小，默认16
- `--imgsz`: 图像大小，默认640
- `--device`: GPU编号或cpu

**训练时间估计:**
- YOLOv8n + 500张图片 + GPU: 1-2小时
- YOLOv8s + 1000张图片 + GPU: 2-3小时
- CPU训练: 10-20倍时间

**输出:**
- 模型保存在: `runs/train/spark_detector/weights/best.pt`
- 训练曲线: `runs/train/spark_detector/results.png`

---

### 步骤5: 处理视频

```bash
# 处理单个视频（交互式标定）
python process_video.py -i video.mp4 -m runs/train/spark_detector/weights/best.pt -o results

# 批量处理（使用保存的标定参数）
python process_video.py -d videos_dir -m best.pt -o results --batch

# 指定排放口尺寸
python process_video.py -i video.mp4 -m best.pt -o results --real-size 25.0
```

**交互式标定:**
1. 程序会显示第一帧
2. 点击排放口的边界点（至少2个点）
3. 按 ENTER 确认，ESC 取消
4. 标定参数会自动保存

**输出文件:**
- `video_tracked.mp4`: 带标注的视频
- `video_data.csv`: 逐帧数据
- `video_trajectories.csv`: 轨迹统计
- `video_calibration.json`: 标定参数
- `video_trajectory_plot.png`: 轨迹图

---

## 输出数据说明

### 1. 逐帧数据 (video_data.csv)

| 列名 | 说明 |
|------|------|
| frame_id | 帧编号 |
| timestamp | 时间戳（秒） |
| track_id | 轨迹ID |
| pixel_x | 像素X坐标 |
| pixel_y | 像素Y坐标 |
| real_x | 物理X坐标（cm） |
| real_y | 物理Y坐标（cm） |
| distance | 距离原点的距离（cm） |
| confidence | 检测置信度 |

### 2. 轨迹统计 (video_trajectories.csv)

| 列名 | 说明 |
|------|------|
| track_id | 轨迹ID |
| max_distance | 最大飞溅距离（cm） |
| duration | 持续时间（秒） |
| avg_speed | 平均速度（cm/s） |
| num_points | 轨迹点数 |

---

## 常见问题

### Q1: 训练时显存不足？

```bash
# 减小批次大小
python train_yolo.py -d spark_dataset -b 8

# 或使用更小的模型
python train_yolo.py -d spark_dataset -m n -b 8
```

### Q2: 检测效果不好？

1. **增加训练数据**: 标注更多图片
2. **调整置信度阈值**: 修改 [`process_video.py`](process_video.py:1) 中的 `conf_threshold`
3. **增加训练轮数**: `-e 200`
4. **使用更大的模型**: `-m s` 或 `-m m`

### Q3: 追踪ID频繁切换？

修改 [`spark_tracker_yolo.py`](spark_tracker_yolo.py:1) 中的DeepSORT参数:
```python
self.tracker = DeepSort(
    max_age=50,              # 增加最大丢失帧数
    n_init=2,                # 减少确认帧数
    max_iou_distance=0.8,    # 增加IOU阈值
)
```

### Q4: 如何在没有GPU的电脑上使用？

1. 在有GPU的电脑或云平台（如Google Colab）上训练模型
2. 下载训练好的模型文件 `best.pt`
3. 在本地电脑上使用CPU进行推理（速度较慢但可行）

```bash
python process_video.py -i video.mp4 -m best.pt -o results --device cpu
```

---

## 项目文件说明

| 文件 | 说明 |
|------|------|
| [`extract_frames.py`](extract_frames.py:1) | 视频帧提取工具 |
| [`split_dataset.py`](split_dataset.py:1) | 数据集划分工具 |
| [`train_yolo.py`](train_yolo.py:1) | YOLO模型训练脚本 |
| [`spark_tracker_yolo.py`](spark_tracker_yolo.py:1) | 火花检测追踪核心类 |
| [`process_video.py`](process_video.py:1) | 完整处理流程脚本 |
| [`requirements.txt`](requirements.txt:1) | Python依赖库 |
| [`数据标注指南.md`](数据标注指南.md:1) | 详细标注教程 |
| [`YOLO方案评估.md`](YOLO方案评估.md:1) | 技术方案详解 |

---

## 技术支持

如遇问题，请参考:
- [`YOLO方案评估.md`](YOLO方案评估.md:1) - 技术细节
- [`数据标注指南.md`](数据标注指南.md:1) - 标注教程
- [`方案对比与建议.md`](方案对比与建议.md:1) - 方案选择

---

## 性能指标

**预期效果:**
- 检测准确率: > 90%
- 误检率: < 5%
- 追踪稳定性: ID不混乱
- 处理速度: 30-60 FPS (GPU)

**实际效果取决于:**
- 训练数据质量和数量
- 视频质量和光照条件
- 模型大小和硬件配置