# Yolov8-Expression-Classification

**Repository Path**: zhang-junah/yolov8-expression-classification

## Basic Information

- **Project Name**: Yolov8-Expression-Classification
- **Description**: 基于 YOLOv8 深度学习算法与 PySide6 桌面框架打造的高效快递包裹智能分类管理系统。本系统实现了从数据预处理、模型推理到结果可视化的一站式解决方案，支持图片、视频流及实时摄像头检测，适用于物流分拣场景的自动化识别与数据统计。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-07
- **Last Updated**: 2026-05-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 快递分类管理系统 (Express Classification System)

[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![Yolov8](https://img.shields.io/badge/Yolov8-PyTorch%20%7C%20Ultralytics-red.svg)](https://pytorch.org/)
[![GUI](https://img.shields.io/badge/GUI-PySide6-green.svg)](https://doc.qt.io/qtforpython/)
[![License](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)

基于 **YOLOv8** 深度学习算法与 **PySide6** 桌面框架打造的高效快递包裹智能分类管理系统。本系统实现了从数据预处理、模型推理到结果可视化的一站式解决方案，支持图片、视频流及实时摄像头检测，适用于物流分拣场景的自动化识别与数据统计。

![image-20260310153750650](./assets/image-20260310153750650.png)

---

## 📖 项目简介

> **注：由于训练好的权重文件过大、适配此项目的YOLOV8标注好的数据集体积过大，无法上传，请联系微信traffic_zhang获取。**

本系统旨在解决传统人工分拣效率低、易出错的问题。通过集成先进的目标检测算法 YOLOv8，系统能够高精度识别多种类型的快递包裹（如Box\Parcel等）。配合友好的图形用户界面 (GUI)，用户可轻松加载模型、输入媒体流并实时查看检测结果与统计报表。

### 核心特性
- **🚀 高性能检测**：基于 YOLOv8 原生架构，支持 CPU/GPU 自动加速，实现毫秒级推理。
- **🖥️ 跨平台桌面应用**：采用 PySide6 (Qt for Python) 构建，界面简洁专业，支持 Windows/Linux/macOS。
- **📹 多模态输入支持**：
  - 单张图片即时检测
  - 本地视频文件逐帧分析
  - 实时摄像头低延迟监控
  - 文件夹批量自动化处理
- **📊 实时数据看板**：动态展示检测总数、分类统计、FPS 帧率及推理耗时。
- **💾 结果导出**：支持保存带标注的图片/视频，并自动生成 CSV/JSON 格式的检测报告。

---

## 🏗️ 系统架构

系统采用分层架构设计，确保模块解耦与高可维护性：

1.  **表示层 (View)**: 基于 `PySide6` 的主窗口、自定义控件及多线程 UI 刷新机制，防止界面卡顿。
2.  **业务逻辑层 (Controller)**: 协调用户操作与算法交互，通过信号槽机制安全传递数据。
3.  **核心算法层 (Model)**: 封装 `ultralytics` YOLOv8 接口，独立于 UI 进行推理、预处理及后处理 (NMS)。
4.  **数据层**: 负责文件 IO、模型权重加载及配置文件解析。

---

## 🛠️ 技术栈

| 模块 | 技术/库 | 说明 |
| :--- | :--- | :--- |
| **开发语言** | Python 3.9+ | 主流 AI 开发语言 |
| **GUI 框架** | PySide6 (Qt6) | 跨平台高性能界面库 |
| **深度学习** | PyTorch + Ultralytics | YOLOv8 官方原生支持 |
| **图像处理** | OpenCV (cv2) | 高效的视频流与图像预处理 |
| **数据分析** | NumPy, Pandas | 矩阵运算与报表导出 |
| **打包部署** | PyInstaller | 生成独立可执行文件 (.exe) |

---

## 📂 项目结构

```text
Express_Classification_System/
│
├── 📂 data/                      # 数据集管理
│   ├── 📂 images/                # 训练/验证/测试集图片
│   ├── 📂 labels/                # YOLO 格式标签 (.txt)
│   ├── 📂 outputs/               # 检测结果输出 (图片/视频/报表)
│   └── dataset.yaml              # 数据集配置文件
│
├── 📂 models/                    # 模型权重
│    ├── 📂 weights/               # .pt 权重文件 (预训练/微调)
│   └── 📂 runs/                  # 训练过程记录
│
├── 📂 src/                       # 核心源码
│   ├── 📂 core/                   # 算法引擎 (detector.py, predictor.py)
│   ├── 📂 ui/                    # 界面逻辑 (main_window.py, widgets/)
│   ├── 📂 config/                # 配置管理 (settings.py, classes.json)
│   └── main.py                   # 程序入口
│
├── 📂 scripts/                   # 辅助脚本
│   ├── train_model.py            # 模型训练脚本
│   ├── validate_model.py         # 模型验证脚本
│   └── convert_labels.py         # 标签格式转换工具
│
├── 📄 requirements.txt           # 依赖列表
├── 📄 README.md                  # 项目说明
└── 📄 run_app.bat                # Windows 启动脚本
```

---

## 🚀 快速开始

### 1. 环境准备

确保已安装 Python 3.9 或更高版本。

```bash
# 创建虚拟环境 (推荐)
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

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

> **注意**: 若需 GPU 加速，请确保已安装对应的 CUDA 版本及 `torch` GPU 版本。

### 2. 模型准备

将训练好的 YOLOv8 权重文件 (`.pt`) 放置于 `models/weights/` 目录下。
若无自定义模型，可下载官方预训练权重 (如 `yolov8n.pt`) 进行测试，但建议针对快递数据集进行微调以获得最佳效果。

配置类别名称：编辑 `src/config/classes.json` 以匹配你的模型类别 ID。

### 3. 运行系统

#### 方式 A: 直接运行
```bash
python src/main.py
```


### 4. 使用指南

1.  **加载模型**: 点击菜单栏 `模型` -> `加载权重`，选择 `.pt` 文件。
2.  **选择输入源**:
    *   **图片**: `文件` -> `打开图片`
    *   **视频**: `文件` -> `打开视频`
    *   **摄像头**: `文件` -> `打开摄像头`
    *   **批量**: `文件` -> `批量处理`
3.  **调整参数**: 在 `设置` 中调整置信度阈值 (Conf Threshold) 和 IoU 阈值。
4.  **查看结果**: 观察中心区域的检测框及右侧面板的实时统计数据。
5.  **保存结果**: 点击 `保存结果` 按钮，导出标注后的媒体文件及 CSV 报表。

---

## 📈 功能流程图

### 模型训练流程
系统提供独立的训练脚本 `scripts/train_model.py`，支持 Mosaic/Mixup 增强、自动验证及最优权重保存。
*(详细流程见文档中的序列图：初始化 -> 迭代训练 (前向/反向/验证) -> 输出报告)*

### 推理检测流程
*   **单图/视频**: 加载媒体 -> 预处理 -> YOLO 推理 -> NMS 后处理 -> 绘制结果 -> 更新 UI/保存。
*   **摄像头**: 线程捕获帧 -> 降频处理 (可选) -> 推理 -> 实时渲染 (FPS 监控)。

---

## ⚙️ 配置说明

### 数据集配置 (`data/dataset.yaml`)
```yaml
# data.yaml
path: D:\MoonLightningProjects\yolov8_package_classification\express_classification_system\data\  # 数据集根目录 (可以是绝对路径)
train: images/train  # 训练集图片相对路径
val: images/val    # 验证集图片相对路径

# 类别名称 (必须与标签中的 class_id 顺序一致)
names:
  0: Box
  1: Parcel
```


## 📝 常见问题 (FAQ)

**Q: 界面点击“开始检测”后无反应？**
A: 请检查是否已正确加载 `.pt` 模型文件，并查看底部日志窗口是否有报错信息。大视频文件处理时可能会有短暂加载时间。

**Q: 如何添加新的快递类别？**
A: 
1. 在 `dataset.yaml` 中添加新类别名称。
2. 重新标注数据并训练模型。
3. 更新 `src/config/classes.json` 中的类别映射。

**Q: GPU 未被调用？**
A: 确认已安装 `torch` 的 CUDA 版本，并在代码中检查 `device` 参数是否自动识别为 `cuda:0`。

---

## 📄 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。


---

> **提示**: 本系统专为毕业设计及工程实践打造，代码结构清晰，注释完备，适合作为深度学习落地应用的参考案例。