# BigProject

**Repository Path**: ocirx/big-project

## Basic Information

- **Project Name**: BigProject
- **Description**: 华清远见大项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-12
- **Last Updated**: 2025-12-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于YOLO的无人机视角地面目标识别

[![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)](https://www.python.org/)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.110+-green.svg)](https://fastapi.tiangolo.com/)
[![YOLO](https://img.shields.io/badge/YOLO-Ultralytics-red.svg)](https://ultralytics.com/)
[![Docker](https://img.shields.io/badge/Docker-Ready-blue.svg)](https://www.docker.com/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 📋 项目概述

这是一个基于 YOLO 模型的无人机视角地面目标识别系统，采用前后端分离架构，提供完整的图像、视频和实时摄像头检测功能。系统包含高性能的后端服务和用户友好的 Qt 客户端界面，专门针对无人机航拍场景进行优化。

### ✨ 主要特性

- 🖼️ **图像检测** - 支持多种格式 (PNG, JPG, JPEG, BMP, WEBP, GIF)，实时显示原图和检测结果对比
- 🎥 **视频检测** - 支持多种格式 (MP4, AVI, MOV, MKV, FLV, WMV)，逐帧目标检测和追踪，智能编码器选择
- 📹 **实时检测** - WebSocket 实时传输和检测，检测框平滑处理算法 (SMOOTH_ALPHA = 0.6)，多类别颜色区分显示
- 📊 **历史记录** - SQLite 数据库存储检测记录，智能缓存管理，自动清理，支持图片和视频结果回放
- 🐳 **容器化部署** - Docker 一键部署，Nginx 反向代理，健康检查和自动重启策略
- 🌐 **跨平台** - 支持 Windows、Linux、macOS
- 🏗️ **模块化架构** - Qt 客户端模块化设计，职责单一，易于维护扩展
- 🔧 **智能配置** - 自动服务器发现，多编码器兼容，环境变量支持

## 🛠️ 技术栈

### 后端服务
- **FastAPI** - 现代化的 Web 框架
- **Ultralytics YOLO** - 目标检测模型
- **OpenCV** - 图像处理
- **SQLite** - 轻量级数据库
- **WebSocket** - 实时通信

### 客户端界面
- **PySide6** - Qt 框架 Python 绑定
- **Requests** - HTTP 客户端
- **WebSockets** - 实时通信

### 部署运维
- **Docker** - 容器化
- **Nginx** - 反向代理
- **Docker Compose** - 服务编排

## 📁 项目结构

```
project_AI_new/
├── backend/                     # 后端服务
│   ├── app/                     # 应用核心代码
│   │   ├── main.py             # FastAPI 主应用 (400+ 行)
│   │   ├── Inference.py        # YOLO 推理引擎 (300+ 行)
│   │   ├── database.py         # 数据库操作
│   │   ├── bytetrack.yaml      # 目标追踪配置
│   │   ├── final_yolov8n_ghost.pt # YOLO 模型文件
│   │   ├── detection_results/  # 检测结果存储
│   │   └── results/            # 上传文件存储
│   ├── requirements.txt        # Python 依赖
│   ├── docker-compose.yml      # Docker 编排
│   ├── Dockerfile             # Docker 镜像
│   ├── nginx.conf             # Nginx 配置
│   ├── .dockerignore          # Docker 忽略文件
│   └── DOCKER_DEPLOY.md       # 部署指南
└── frontend/
    └── QT/                     # Qt 客户端
        ├── qt.py               # 主程序入口 (100+ 行)
        ├── utils.py            # 工具函数和配置
        ├── workers.py          # 后台工作线程
        ├── pages.py            # UI 页面组件 (400+ 行)
        ├── camera.py           # 摄像头功能模块 (200+ 行)
        ├── config.py           # 客户端配置
        ├── server_config.txt   # 服务器配置
        └── README_CLIENT.md    # 客户端使用指南
```

## 🚀 快速开始

### 环境要求
- Python 3.12+
- Docker 20.10+ (可选)
- 4GB+ RAM
- 10GB+ 磁盘空间

### 方式一：Docker 部署（推荐）

```bash
# 1. 克隆项目
git clone https://gitee.com/ocirx/big-project.git
cd big-project

# 2. 启动服务
cd backend
docker-compose up -d

# 3. 查看服务状态
docker-compose ps

# 4. 访问服务
curl http://localhost/health
```

### 方式二：本地部署

```bash
# 后端服务
cd backend/app
pip install -r ../requirements.txt
python main.py

# 客户端
cd frontend/QT
pip install PySide6>=6.6.0 requests>=2.31.0 websockets>=12.0 opencv-python>=4.8.0 pillow>=10.0.0
python qt.py
```

### 测试命令

```bash
# 检查后端服务
curl http://localhost:5000/docs

# 查看容器日志
docker-compose logs -f yolo-backend

# 检查数据库
sqlite3 backend/app/database.db "SELECT * FROM urls LIMIT 3;"
```

### 客户端使用

#### 安装依赖
```bash
pip install PySide6>=6.6.0 requests>=2.31.0 websockets>=12.0 opencv-python>=4.8.0 pillow>=10.0.0
```

#### 服务器配置
**方式一：配置文件**
```bash
# 编辑 frontend/QT/server_config.txt:
SERVER_HOST=服务器IP地址
SERVER_PORT=5000
```

**方式二：环境变量**
```bash
# Windows
set YOLO_SERVER_HOST=192.168.1.100
set YOLO_SERVER_PORT=5000

# Linux/macOS
export YOLO_SERVER_HOST=192.168.1.100
export YOLO_SERVER_PORT=5000
```

#### 启动客户端
```bash
cd frontend/QT
python qt.py
```

#### 客户端架构
```
frontend/QT/
├── qt.py              # 主程序入口 (100+ 行)
├── utils.py           # 工具函数和配置 (80+ 行)
├── workers.py         # 后台工作线程 (120+ 行)
├── pages.py           # UI 页面组件 (400+ 行)
├── camera.py          # 摄像头功能模块 (200+ 行)
├── config.py          # 客户端配置文件
├── server_config.txt  # 服务器配置
└── README_CLIENT.md   # 详细使用指南
```

**主要改进**:
- 🏗️ **模块化重构**: 1000+ 行代码拆分为 5 个功能模块
- 🎨 **现代化界面**: 响应式布局，图标主题
- 🗂️ **智能缓存**: 历史文件临时缓存，自动清理
- 🔧 **配置管理**: 统一配置文件，环境变量支持
- 📱 **用户体验**: 实时状态反馈，错误处理优化

**注意**: 
- 客户端采用模块化架构，便于维护和扩展
- 通过 HTTP/WebSocket 连接到远程后端服务
- 详细配置请参考 `frontend/QT/README_CLIENT.md`

## 📖 详细文档

### API 文档
启动服务后访问：
- **Swagger UI**: http://localhost:5000/docs
- **ReDoc**: http://localhost:5000/redoc

### 主要接口

| 接口 | 方法 | 功能 |
|------|------|------|
| `/upload/image` | POST | 图像上传检测 |
| `/upload/video` | POST | 视频上传检测 |
| `/realtime_detection` | POST | 实时检测 |
| `/history` | GET | 历史记录查询 |
| `/ws/camera` | WebSocket | 实时摄像头 |

### 配置说明

#### 服务器配置
- **模型路径**: `/app/final_yolov8n_ghost.pt`
- **数据存储**: `/app/detection_results/`
- **数据库**: `/app/database.db`
- **全局变量**: `backend/app/main.py` 中的全局配置

#### 客户端配置
- **配置文件**: `frontend/QT/server_config.txt`
- **环境变量**: `YOLO_SERVER_HOST`, `YOLO_SERVER_PORT`

## 🔧 开发指南

### 代码规范
- 遵循 PEP 8 代码风格
- 使用类型注解
- 模块化设计，职责单一
- 异步处理不阻塞 UI
- 编写单元测试
- 添加详细注释

### 贡献流程
1. Fork 项目
2. 创建功能分支
3. 提交代码变更
4. 创建 Pull Request

### 调试技巧
```bash
# 查看容器日志
docker-compose logs -f yolo-backend

# 进入容器调试
docker-compose exec yolo-backend bash

# 检查服务状态
curl http://localhost:5000/docs
```

## 📊 性能优化

### 检测优化
- **框平滑算法**: 指数移动平均，减少检测框抖动 (SMOOTH_ALPHA = 0.6)
- **异步处理**: 提升并发性能，避免 UI 阻塞
- **资源管理**: 及时释放内存和文件句柄
- **智能编码器**: 多编码器支持 (mp4v, avc1, x264, DIVX, XVID, MJPG)，降级机制确保视频处理兼容性
- **目标追踪**: bytetrack.yaml 配置文件支持
- **连接复用**: 超时控制，错误重试机制

### 客户端优化
- **模块化加载**: 按需加载功能模块，减少内存占用
- **缓存管理**: 智能临时文件缓存，自动清理机制
- **网络优化**: 连接复用，超时控制，错误重试
- **界面响应**: 异步操作，实时状态反馈

### 部署优化
- **负载均衡**: Nginx 多实例分发
- **缓存策略**: 静态文件缓存，Gzip 压缩
- **监控告警**: 服务健康检查，性能指标
- **容器化**: Docker 多阶段构建，镜像优化，Python 3.12-slim 基础镜像
- **网络配置**: 后端监听所有接口 (host="0.0.0.0")，WebSocket 代理支持，CORS 跨域配置
- **安全考虑**: 文件上传大小限制，支持的文件格式白名单，临时文件自动清理，访问权限控制

## 🔒 安全配置

### 网络安全
- 配置防火墙规则
- 使用 HTTPS 加密
- 限制访问来源

### 数据安全
- 定期备份数据库
- 敏感信息加密存储
- 访问权限控制

## 📝 更新日志

### v2.1.0 (2025-12-03)
- ✅ **视频编码器优化**: 智能编码器选择，多格式兼容
- ✅ **缓存管理改进**: 历史文件智能缓存，自动清理
- ✅ **错误处理增强**: 详细错误信息，优雅降级
- ✅ **配置文件统一**: 集中配置管理，环境变量支持
- ✅ **性能监控**: 实时状态反馈，资源使用优化

### v2.0.0 (2025-12-03)
- ✅ Qt 客户端模块化重构
- ✅ 现代化 UI 界面设计
- ✅ 4个功能模块分离
- ✅ 性能优化和错误处理
- ✅ 完善的文档和配置

### v1.0.0 (2025-12-03)
- ✅ 完整的 YOLO 检测功能
- ✅ Qt 客户端界面
- ✅ Docker 容器化部署
- ✅ 实时 WebSocket 通信
- ✅ 历史记录管理

## 🔧 已知问题解决

### 视频处理问题
- ❌ **FFMPEG 编码器错误**: `tag 0x34706d2e/'.mp4' is not found`
- ✅ **解决方案**: 多编码器降级机制，智能选择兼容编码器 (mp4v, avc1, x264, DIVX, XVID, MJPG)

### 实时检测问题  
- ❌ **解包错误**: `ValueError: not enough values to unpack`
- ✅ **解决方案**: 修复颜色函数返回值，QPainter 安全管理

### 文件管理问题
- ❌ **临时文件污染**: 历史视频保存到项目目录
- ✅ **解决方案**: 系统临时目录缓存，定时自动清理

### 网络连接问题
- ❌ **服务器配置固定**: 只能连接本地服务器
- ✅ **解决方案**: 动态配置管理，环境变量支持

### 其他常见问题
- ❌ **WebSocket 连接问题**: 检查防火墙和代理配置
- ❌ **模型加载失败**: 确认 final_yolov8n_ghost.pt 文件存在
- ❌ **客户端连接失败**: 检查 server_config.txt 配置

## 🤝 支持与反馈

### 问题报告
如果您遇到问题，请：
1. 查看 [已知问题解决](#已知问题解决)
2. 检查客户端配置 `QT/README_CLIENT.md`
3. 查看服务日志和错误信息
4. 搜索已有 Issues

### 快速故障排除
```bash
# 检查后端服务
curl http://localhost:5000/health

# 检查客户端配置
cat frontend/QT/server_config.txt

# 查看服务日志
docker-compose logs -f yolo-backend

# 验证数据库
sqlite3 backend/app/database.db

# 测试 WebSocket
# 使用浏览器开发者工具连接 ws://localhost:5000/ws/camera
```

### 联系方式
- 📧 Email: support@example.com
- 💬 讨论: [GitHub Discussions](https://github.com/your-repo/discussions)
- 📖 文档: [详细文档](frontend/QT/README_CLIENT.md)
- 🔗 项目地址: https://gitee.com/ocirx/big-project.git

## 📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

## 📋 版本信息

- **当前版本**: v2.1.0 (2025-12-03)
- **Python 要求**: 3.12+
- **内存要求**: 4GB+
- **磁盘空间**: 10GB+

## 🙏 致谢

感谢以下开源项目：
- [Ultralytics YOLO](https://github.com/ultralytics/ultralytics)
- [FastAPI](https://github.com/tiangolo/fastapi)
- [PySide6](https://doc.qt.io/qtforpython/)
- [OpenCV](https://opencv.org/)

---

⭐ 如果这个项目对您有帮助，请给我们一个 Star！

---

## 🎯 模型训练模块

### 概述
本项目包含完整的模型训练模块，支持从数据准备到模型部署的全流程。基于 Ultralytics YOLO 框架，集成了 GhostHead 轻量化模块，专门针对无人机视角的地面目标识别进行优化。

### 主要特性
✅ **GhostHead 轻量化** - 集成 Ghost 模块，减少 30-50% 计算量  
✅ **小目标优化** - 针对无人机视角的小目标检测专门优化  
✅ **高分辨率支持** - 支持 1280×1280 高分辨率输入  
✅ **多格式导出** - 支持 PyTorch、ONNX、TensorRT 等多种格式  
✅ **硬件适配** - 针对不同 GPU 显存提供优化配置  

### 项目结构
```
model_train/
├── ghost_head.py              # GhostHead 轻量化模块实现
├── train.py                   # 训练脚本
├── val.py                     # 验证脚本
├── requirements.txt           # Python 依赖包
├── visdrone.yaml              # VisDrone 数据集配置文件
├── yolov8n_ghost.yaml         # YOLOv8-Ghost 模型配置文件
├── readme.md                  # 详细训练指南文档
├── yolo11n_v1_val/            # YOLO11n 验证结果
└── yolov8n_ghost_val/         # YOLOv8-Ghost 验证结果
```

### 快速开始

#### 环境配置
```bash
# 1. 创建 conda 环境
conda create -n yd python=3.10
conda activate yd

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

# 3. 验证安装
python -c "from ultralytics import YOLO; print('YOLO version:', YOLO.__version__)"
```

#### 数据集准备
VisDrone 数据集已包含在项目中，包含 10 个类别：
- `pedestrian` (行人)
- `people` (人)
- `bicycle` (自行车)
- `car` (汽车)
- `van` (面包车)
- `truck` (卡车)
- `tricycle` (三轮车)
- `awning-tricycle` (带棚三轮车)
- `bus` (公交车)
- `motor` (摩托车)

#### 训练模型
```bash
# 基础训练
python train.py

# 使用 GhostHead 训练（推荐）
python train.py --use-ghost --epochs 200 --batch 16 --imgsz 1280 --amp --name yolodrone_ghost_1280

# 验证模型
python val.py
```

#### 硬件适配配置
| 参数 | 推荐值 | 说明 |
|------|--------|------|
| 图像尺寸 | 1280×1280 | 小目标检测需要高分辨率 |
| 批次大小 | 16 | 8-12GB 显存的最佳平衡 |
| 优化器 | AdamW | 小目标场景效果优于 SGD |
| 训练轮数 | 200 | VisDrone 数据集复杂度较高 |

### 模型架构特点
1. **Ghost 模块集成**
   - 使用 `GhostConv` 替代标准卷积
   - 使用 `C3Ghost` 模块替代 `C3` 模块
   - 减少计算量同时保持特征表达能力

2. **多尺度特征融合**
   - P3 (1/8 尺度): 小目标检测
   - P4 (1/16 尺度): 中等目标检测
   - P5 (1/32 尺度): 大目标检测

### 性能指标
| 模型 | mAP50 | mAP50-95 | 参数量 | GFLOPs | FPS (RTX 5060) |
|------|-------|----------|--------|--------|----------------|
| YOLOv8n | 0.45 | 0.28 | 3.1M | 8.9 | 120 |
| YOLOv8n-Ghost | 0.43 | 0.26 | 2.2M | 6.3 | 150 |
| YOLO11n | 0.48 | 0.30 | 3.5M | 10.2 | 110 |

### 常见问题解决

#### Q1: 训练时出现 CUDA out of memory 错误
**解决方案**：
1. 降低 `--batch` 参数（如从 16 降到 8）
2. 启用 `--amp` 混合精度训练
3. 降低 `--imgsz` 参数（如从 1280 降到 960）
4. 关闭部分数据增强（如 `--mosaic 0`）

#### Q2: 如何从断点恢复训练？
```bash
python train.py --resume
```

#### Q3: 如何导出为其他格式？
```python
# 导出为 ONNX
model.export(format="onnx", imgsz=1280)

# 导出为 TensorRT
model.export(format="engine", imgsz=1280)

# 导出为 OpenVINO
model.export(format="openvino", imgsz=1280)
```

### 完整工作流
1. **数据准备** - 准备 VisDrone 数据集
2. **模型训练** - 使用 GhostHead 进行轻量化训练
3. **模型验证** - 评估模型性能指标
4. **模型导出** - 导出为多种格式
5. **部署应用** - 集成到后端服务中

### 详细文档
更多详细信息请参考 `model_train/readme.md` 文件，包含完整的训练指南、配置说明和性能分析。