# 车辆识别

**Repository Path**: sys_one/vehicle-recognition

## Basic Information

- **Project Name**: 车辆识别
- **Description**: 车辆识别并统计车流量
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2026-01-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vehicle-YOLO 🚗

<div align="center">

![Python](https://img.shields.io/badge/Python-3.8%2B-blue)
![YOLOv8](https://img.shields.io/badge/YOLO-v8-green)
![License](https://img.shields.io/badge/license-MIT-orange)
![Status](https://img.shields.io/badge/Status-Active-brightgreen)

**基于 YOLOv8 的高效车辆检测与智能交通流量统计系统**

[特性](#-核心特性-features) • [安装](#-环境要求与安装-installation) • [快速开始](#-快速开始-quick-start) • [文档](#-使用文档-documentation) • [贡献](#-贡献指南-contributing)

</div>

---

## 📖 项目简介 (Introduction)

**Vehicle-YOLO** 是一个开源的智能交通分析解决方案，基于强大的 Ultralytics YOLOv8 框架开发。本项目不仅仅是一个物体检测器，更是一个完整的交通流统计工具链。

它旨在解决道路监控场景下的**车辆精确检测**与**流量自动统计**问题。通过集成先进的目标追踪（Object Tracking）算法，系统能够对视频流中的车辆进行去重计数，并自动生成标准化的 Excel 数据报表，极大地简化了交通数据分析流程。

## ✨ 核心特性 (Features)

- 🎯 **高精度检测**：基于 YOLOv8 State-of-the-Art 模型，支持多尺度车辆检测。
- 🔄 **智能去重计数**：内置目标追踪算法 (ByteTrack/BoT-SORT)，有效解决车辆重复计数问题，统计独立车流。
- 📊 **自动报表生成**：检测结果实时汇总，自动导出为 `.xlsx` 格式，支持多视频数据自动追加合并。
- ⚔️ **多策略训练**：提供“强增广”与“无预处理”双重训练模式，便于科研对比与模型调优。
- ⚡ **跨平台支持**：完美适配 CPU/GPU 环境，支持 Windows/Linux 系统部署。

## 🎁 项目结构 (Project Structure)

```text
Vehicle-YOLO/
├── datasets/                   # 数据集存储目录
│   └── vehicle/                # 车辆数据集 (标准 YOLO 格式)
├── logs/                       # 训练日志与运行记录
├── runs/                       # 模型训练输出 (权重 .pt、PR曲线、混淆矩阵)
├── traffic_stats/              # 统计结果输出目录 (Excel 报表)
├── training_scripts/           # 核心功能脚本
│   ├── train_default_yolo.py   # 🚀 标准训练脚本 (含数据增广)
│   ├── train_no_preprocess.py  # 🔬 实验对照训练脚本 (无预处理)
│   └── predict_video.py        # 🎥 视频推理与计数脚本
├── utils/                      # 工具函数库
│   ├── counter.py              # 核心计数逻辑与 Excel 生成器
│   └── logger.py               # 日志管理模块
├── dataset.yaml                # YOLO 数据集配置文件
└── requirements.txt            # 项目依赖清单
```

## 🛠️ 环境要求与安装 (Installation)

### 前置要求
- Python 3.8 或更高版本
- CUDA Toolkit (如果需要 GPU 加速)

### 安装步骤

您可以选择 **源码安装** 或 **使用离线压缩包**。

#### 方式一：从源码安装 (通过 Git)

1. **克隆仓库**
   ```bash
   git clone https://gitee.com/sys_one/vehicle-recognition.git
   cd Vehicle
   ```

2. **创建虚拟环境**
   ```bash
   conda create -n vehicle python=3.9
   conda activate vehicle
   ```

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

#### 方式二：使用离线包 (通过 Zip)

如果您已下载本项目的发布包 `Vehicle.zip`：

1. **解压并进入目录**
   解压压缩包，在终端中进入解压后的文件夹。

> 该压缩包经过精简，已自动排除缓存文件，并包含以下核心内容：
> - 📂 `datasets/`, `training_scripts/`, `utils/`
> - 📂 `traffic_stats/` (包含生成的报表)
> - 📄 `dataset.yaml`, `requirements.txt`, `README.md`
> - ⚖️ `runs/detect/vehicle_default_aug/weights/best.pt` (训练好的最佳权重)

2. **创建环境并安装依赖**
   ```bash
   conda create -n vehicle python=3.9
   conda activate vehicle
   pip install -r requirements.txt
   ```

> 💡 **提示**: Windows 用户如果安装 `lapx` (包含在 requirements.txt 中) 遇到编译错误，建议安装 Microsoft C++ Build Tools 或直接下载对应版本的 `.whl` 文件安装。

## 🎯 快速开始 (Quick Start)

### 1. 数据准备
请确保您的数据集遵循 YOLO 格式并存放在 `datasets/vehicle/` 目录下：
- `images/`: 存放图片文件 (`train/`, `val/`, `test/`)
- `labels/`: 存放标签文件 (`train/`, `val/`, `test/`)

配置文件 `dataset.yaml` 应如下所示：
```yaml
path: ./datasets/vehicle
train: images/train
val: images/val
names:
  0: vehicle
```

### 2. 模型训练 (Model Training)

我们提供了两种训练模式以适应不同的需求：

#### 🅰️ 生产模式 (推荐)
使用 YOLOv8 默认的 Mosaic 等强增广策略，模型鲁棒性更好。
```bash
python training_scripts/train_default_yolo.py --data dataset.yaml --name vehicle_default_aug --epochs 50
```

#### 🅱️ 实验模式
关闭所有预处理和增广，仅进行基础训练，用于验证原始数据质量或特定实验对照。
```bash
python training_scripts/train_no_preprocess.py --data dataset.yaml --name vehicle_no_aug --epochs 50
```

**关键参数说明：**
| 参数 | 说明 | 默认值 |
| :--- | :--- | :--- |
| `--data` | 数据集配置文件路径 | `dataset.yaml` |
| `--epochs` | 训练轮次 | `50` |
| `--batch` | 批次大小 | `16` |
| `--device` | 运行设备 (`cpu`, `0`, `0,1`) | `0` |

### 3. 视频流量统计 (Video Counting)

使用训练好的模型对视频文件进行推理，并自动生成流量统计报表。

```bash
python training_scripts/predict_video.py \
    --video datasets/vehicle/videos/video1.mp4 \
    --model runs/detect/vehicle_default_aug/weights/best.pt \
    --output-excel traffic_stats/video_summary.xlsx \
    --device cpu
```

**输出结果：**
脚本运行完成后，`traffic_stats/video_summary.xlsx` 将会自动更新，包含以下字段：
- **Video Name**: 视频文件名
- **Total Frames**: 处理的总帧数
- **Total Unique Vehicles**: 统计到的独立车辆总数

## 📊 结果示例 (Results)

### 1. 视频流量统计 (Video Counting)

生成的 Excel 报表 (`video_summary.xlsx`) 格式如下，支持多次运行自动追加数据：

| Video Name | Total Frames | Total Unique Vehicles |
| :--- | :--- | :--- |
| video1.mp4 | 35 | 54 |
| video2.mp4 | 53 | 59 |
| vidoe3.mp4 | 32 | 66 |
| video4.mp4 | 27 | 51 |

**识别结果视频预览**  
*(点击以下链接查看完整视频)*

- 🎥 [查看视频 1 (video1.avi)](runs/detect/video1_run/video1.avi)

> ⚠️ **说明**: 
> - **Excel 报表**: 存储在 `traffic_stats/video_summary.xlsx`，包含流量统计数据。
> - **可视化视频**: 存储在 `runs/detect/<视频名>_run/` 目录下，包含带追踪ID和边框的识别结果视频。

### 2. 静态图片检测 (Image Detection)

**验证集预测样本**  
*(左侧为真实标签，右侧为模型预测结果)*

![Validation Predictions](runs/detect/vehicle_default_aug/val_batch0_pred.jpg)

> ⚠️ **说明**: 
> - **Excel 报表**: 存储在 `traffic_stats/<模型名>_counts.xlsx`（例如 `vehicle_default_aug_counts.xlsx`），记录了测试集中每一张图片的车辆数量。
> - **可视化结果**: 训练或预测完成后，带标注的图片和预测标签保存在 `runs/detect/<模型名>/` 目录下。
> - **如何运行**: 在训练脚本中添加 `--predict-test` 参数（如 `python training_scripts/train_default_yolo.py ... --predict-test`），即可在训练结束后自动对测试集进行预测统计。

## 📈 训练性能与可视化 (Performance & Visualization)

本节展示了两种不同训练策略的模型性能对比。

### 🅰️ 模型一：默认强增广 (Default Augmentation)
*训练脚本：`train_default_yolo.py` (50 Epochs)*

#### 1. 核心指标 (Key Metrics)

| Metric | Value | 说明 |
| :--- | :--- | :--- |
| **Precision (P)** | **0.590** | 查准率：预测准确性较高 |
| **Recall (R)** | **0.500** | 查全率：能检测出一半的真实目标 |
| **mAP@50** | **0.436** | 基础检测能力 |
| **mAP@50-95** | **0.200** | 高精度定位能力 |

#### 2. 可视化结果 (Visualization)

<details>
<summary>点击展开详细图表</summary>

**损失与指标变化曲线**  
![Training Results](runs/detect/vehicle_default_aug/results.png)

**混淆矩阵 (Confusion Matrix)**  
![Confusion Matrix](runs/detect/vehicle_default_aug/confusion_matrix.png)

**PR 曲线 (Precision-Recall Curve)**  
![PR Curve](runs/detect/vehicle_default_aug/BoxPR_curve.png)

**验证集预测样本**  
![Validation Predictions](runs/detect/vehicle_default_aug/val_batch0_pred.jpg)

</details>

---

### 🅱️ 模型二：无预处理 (No Preprocess)
*训练脚本：`train_no_preprocess.py` (50 Epochs)*
*特点：关闭 Mosaic、Mixup 等所有数据增广，仅使用原始数据训练。*

#### 1. 核心指标 (Key Metrics)

| Metric | Value | 说明 |
| :--- | :--- | :--- |
| **Precision (P)** | **0.476** | 相比默认增广模型下降约 19% |
| **Recall (R)** | **0.322** | 相比默认增广模型下降明显 |
| **mAP@50** | **0.233** | 基础检测能力较弱 |
| **mAP@50-95** | **0.112** | 定位精度较低 |

#### 2. 可视化结果 (Visualization)

<details>
<summary>点击展开详细图表</summary>

**损失与指标变化曲线**  
![Training Results](runs/detect/vehicle_no_preprocess_gpu_retry3/results.png)

**混淆矩阵 (Confusion Matrix)**  
![Confusion Matrix](runs/detect/vehicle_no_preprocess_gpu_retry3/confusion_matrix.png)

**PR 曲线 (Precision-Recall Curve)**  
![PR Curve](runs/detect/vehicle_no_preprocess_gpu_retry3/BoxPR_curve.png)

**验证集预测样本**  
![Validation Predictions](runs/detect/vehicle_no_preprocess_gpu_retry3/val_batch0_pred.jpg)

</details>

## 🤝 贡献指南 (Contributing)

欢迎任何形式的贡献！如果您有好的建议或发现了 Bug，请随时提交 Issue 或 Pull Request。

## 📄 许可证 (License)

本项目采用 [MIT License](LICENSE) 许可证。

## � 致谢 (Acknowledgements)

- [Ultralytics YOLOv8](https://github.com/ultralytics/ultralytics)
- [Pandas](https://pandas.pydata.org/)
## 🎯 应用场景 (Scenarios)

- 城市道路交通流量监控
- 停车场车辆出入统计
- 高速公路车流密度分析

## 📝 更新日志 (Changelog)
### [2025-11-23] - Initial Release
- 发布基于 自定义模型 的车辆检测与流量统计系统
- 支持视频流车辆去重计数与 Excel 报表自动生成
### [2026-01-08] - Initial Release
- 发布基于 YOLOv8 的车辆检测与流量统计系统
- 支持视频流车辆去重计数与 Excel 报表自动生成
- 提供默认强增广与无预处理两种训练模式对比