# 道路损伤检测系统 - 完整使用指南

## 📋 系统简介

本系统是一个基于YOLO深度学习模型的道路损伤检测系统，支持对视频文件进行智能分析，自动识别和标注道路损伤区域。系统提供了Web界面操作方式，适合不同技术水平的用户使用。

### 🎯 核心特色功能

#### 🔍 智能检测技术
- **动态模型识别**: 自动识别模型类型并优化检测参数
- **自适应置信度**: 根据检测场景自动调整置信度阈值
- **多尺度检测**: 支持不同尺寸目标的精确检测
- **检测质量过滤**: 自动过滤低质量检测结果

#### 📊 智能标注显示
- **纯中文标注**: 标注框只显示中文类别名称，更符合中文用户习惯
- **智能类别映射**: 自动将英文类别名称映射为中文，支持部分匹配和组合词
- **动态颜色分配**: 根据类别自动分配识别颜色
- **置信度可视化**: 标注框粗细反映检测置信度

#### 🗂️ 智能文件管理
- **智能文件夹生成**: 只为检测到目标的类别创建文件夹，避免生成空文件夹
- **按类别分组**: 检测结果按损伤类型自动分类存储
- **完整检测记录**: 详细的检测日志和统计信息

### 📹 主要功能
- 📹 支持多种视频格式批量处理
- 🌐 友好的Web界面操作
- 📊 详细的检测报告和统计分析
- 🔧 灵活的模型管理和参数配置
- 💾 完整的检测结果保存和导出

## 🚀 快速开始

### 第一步：环境准备

#### 系统要求
- **操作系统**: Windows 10/11
- **Python版本**: 3.8 或更高版本
- **内存**: 建议8GB以上
- **存储**: 建议10GB可用空间
- **GPU**: 可选，NVIDIA GPU可加速检测

#### 安装步骤

1. **安装Python环境**
   - 下载并安装 Python 3.8 或更高版本
   - 下载地址：https://www.python.org/downloads/
   - 安装时勾选 "Add Python to PATH"

2. **安装系统依赖**
   ```bash
   # 方法一：使用安装脚本（推荐）
   双击运行 install.bat
   
   # 方法二：手动安装
   pip install -r requirements.txt
   ```

### 第二步：准备文件

#### 文件结构说明
```
检测系统/
├── app.py                    # Web应用主程序
├── batch_detector.py         # 批量检测器
├── config.py                # 配置文件
├── detector.py              # 核心检测器
├── requirements.txt         # Python依赖包列表
├── install.bat             # 环境安装脚本
├── start_web_app.bat       # Web应用启动脚本
├── input_videos/           # 输入视频文件夹
│   ├── video1.mp4          # 您的视频文件
│   └── video2.avi          # 支持多种格式
├── models/                 # 检测模型文件夹
│   ├── best.pt            # 预训练模型
│   └── best_info.json     # 模型信息
├── output_frames/          # 检测结果输出文件夹
├── logs/                   # 系统日志文件夹
├── static/                 # Web界面静态资源
│   └── css/
│       └── style.css      # 界面样式文件
└── templates/              # Web界面模板
    ├── index.html         # 主页面
    ├── layout.html        # 布局模板
    ├── report.html        # 报告页面
    └── video_results.html # 视频结果页面
```

#### 准备检测文件

1. **准备视频文件**
   - 将需要检测的视频文件放入 `input_videos` 文件夹
   - 支持格式：`.mp4`, `.avi`, `.mov`, `.mkv`, `.wmv`, `.flv`, `.webm`
   - 可以创建子文件夹组织视频文件

2. **准备检测模型**
   - 系统已预置 `best.pt` 模型
   - 可通过Web界面上传自定义模型（.pt格式）

### 第三步：启动系统

#### Web界面启动（推荐）
```bash
# 启动Web应用
双击运行 start_web_app.bat
# 或者
python app.py
```
然后在浏览器中访问：http://localhost:5000

## 🌐 Web界面使用指南

### 界面布局
- **左侧面板**：检测历史记录和结果列表
- **右侧面板**：文件管理和检测配置
- **顶部导航**：功能切换和系统状态

### 核心功能操作

#### 1. 视频文件管理

**添加视频文件：**
- 方法一：直接将视频文件拖拽到 `input_videos` 文件夹
- 方法二：通过Web界面的文件管理功能上传

**文件管理功能：**
- **查看文件列表**：显示当前待检测的视频文件
- **删除文件**：移除单个视频文件
- **清空文件夹**：一键清空所有视频文件

#### 2. 模型管理
- **上传新模型**：点击上传区域选择.pt格式的YOLO模型文件
- **查看模型列表**：显示所有可用模型及其信息
- **删除模型**：移除不需要的模型文件
- **模型自动识别**：系统会自动分析模型类型并优化参数

#### 3. 检测配置

**选择检测模型：**
- `best.pt`：专门训练的道路损伤检测模型（推荐）
- 其他自定义模型：可通过界面上传

**调整置信度阈值：**
- **0.3-0.4**：宽松检测，检测更多目标（可能有误检）
- **0.5-0.6**：平衡检测（推荐）
- **0.7-0.8**：严格检测，只检测高置信度目标

**系统会根据模型类型自动优化：**
- **道路损伤检测**: 0.25-0.4 (系统会自动优化)
- **通用目标检测**: 0.4-0.6
- **高精度检测**: 0.6-0.8

#### 4. 开始检测

**检测流程：**
1. 确认视频文件已添加
2. 选择合适的检测模型
3. 设置置信度阈值
4. 点击「开始检测」按钮
5. 等待检测完成

**检测过程：**
- 实时显示检测进度和状态
- 显示当前处理的视频和帧数信息
- 自适应检测算法自动优化检测效果

#### 5. 查看结果

**检测报告：**
- 点击左侧检测记录查看详细报告
- 包含检测统计、时间分析、类别分布等
- 详细的检测日志和自适应检测统计

**视频结果：**
- 查看原始视频帧和标注结果
- 按类别浏览检测到的损伤
- 导出检测数据和报告

## 📊 检测结果说明

### 支持的损伤类型

系统可以检测以下18种道路损伤和交通事故类型：

**道路损伤：**
- 坑洞
- 横向裂缝
- 纵向裂缝
- 网状裂缝
- 白线模糊

**交通事故：**
- 追尾碰撞
- 正面碰撞
- 侧面碰撞
- 翻车事故
- 多车连环相撞

**交通违规：**
- 违规变道
- 闯红灯
- 超速行驶

**其他：**
- 交通拥堵
- 公交车
- 行人
- 自行车
- 摩托车

### 输出文件结构

```
output_frames/
└── [检测时间戳]/
    ├── report.html          # 检测报告
    ├── summary.json         # 检测摘要
    └── [视频名称]/
        ├── [类别名称]/      # 按类别分组的检测结果
        │   ├── original/    # 原始帧
        │   └── annotated/   # 标注帧
        ├── detection_log.json  # 详细检测日志
        ├── statistics.json     # 统计信息
        └── [视频名称]_detections.json  # 详细检测数据
```

### 检测数据格式

```json
{
  "frame_number": 123,
  "timestamp": "00:02:05",
  "detections": [
    {
      "class": "坑洞",
      "confidence": 0.85,
      "bbox": [x, y, width, height]
    }
  ],
  "adaptive_detection": true,
  "detection_quality": 0.78
}
```

## 🔧 系统配置

### 配置文件说明（config.py）

- `INPUT_FOLDER`: 输入视频文件夹路径
- `OUTPUT_FOLDER`: 输出结果文件夹路径
- `MODELS_FOLDER`: 模型文件夹路径
- `CONFIDENCE_THRESHOLD`: 默认置信度阈值
- `SUPPORTED_FORMATS`: 支持的视频格式

### 检测参数调优

1. **置信度阈值建议**
   - 道路损伤检测推荐：0.3-0.6
   - 精确检测推荐：0.6-0.8
   - 宽松检测推荐：0.2-0.4

2. **模型选择**
   - `best.pt`: 专门训练的道路损伤检测模型
   - 系统会自动识别模型类型并优化参数

## 🚨 故障排除

### 安装问题

**Q: install.bat 运行失败**
- 确保已安装Python 3.8+
- 以管理员身份运行install.bat
- 检查网络连接是否正常

**Q: 缺少依赖包**
```bash
pip install -r requirements.txt
```

### 使用问题

**Q: Web界面无法访问**
- 检查防火墙设置
- 确认端口5000未被占用
- 重新运行start_web_app.bat

**Q: 检测速度慢**
- 检查是否有GPU可用
- 降低视频分辨率
- 调整检测参数

**Q: 内存不足**
- 减少批量处理的视频数量
- 降低视频分辨率
- 关闭其他应用程序

**Q: 模型加载失败**
- 检查模型文件完整性
- 确认模型格式正确（.pt）
- 重新下载模型文件

### 日志查看

```bash
# 查看系统日志
type logs\app.log

# 查看检测日志
type logs\detection.log
```

## 🔄 系统更新与维护

### 更新依赖包

```bash
pip install -r requirements.txt --upgrade
```

### 更新模型

1. 下载新的模型文件
2. 放入 `models` 文件夹
3. 通过Web界面上传或直接复制
4. 系统会自动识别新模型类型

### 性能优化建议

1. **硬件优化**
   - 使用SSD存储提高I/O性能
   - 配置NVIDIA GPU加速
   - 增加系统内存

2. **软件优化**
   - 定期清理输出文件夹
   - 优化视频文件大小
   - 调整检测参数

## 🎯 使用技巧

### 提高检测效果

1. **视频质量**
   - 使用高清视频获得更好的检测效果
   - 确保视频光线充足，画面清晰
   - 避免过度压缩的视频文件

2. **参数调整**
   - 根据检测目标调整置信度阈值
   - 利用系统的自适应检测功能
   - 观察检测报告中的统计信息进行优化

3. **结果分析**
   - 查看检测报告了解检测效果
   - 分析类别分布和置信度统计
   - 根据检测质量调整参数

## 📝 更新日志

### v2.2.0 - 最新版本
- ✨ 新增纯中文标注系统
- 🗂️ 智能文件夹管理，只生成有检测结果的类别文件夹
- 🔍 改进的自适应检测算法
- 📊 增强的检测统计和报告功能
- 🎨 优化的Web界面和用户体验

### v2.0.0
- 新增Web界面
- 优化检测算法
- 改进用户体验
- 增加批量处理功能

### v1.0.0
- 初始版本发布
- 基础检测功能
- 命令行界面

## 📞 技术支持

### 联系方式

如果您在使用过程中遇到问题，可以通过以下方式获取帮助：

1. **查看日志文件**: 检查 `logs` 文件夹中的日志信息
2. **检查配置**: 确认 `config.py` 中的配置是否正确
3. **重新安装**: 运行 `install.bat` 重新安装依赖

### 常见解决方案

1. **环境问题**: 确保Python版本和依赖包正确安装
2. **权限问题**: 以管理员身份运行相关脚本
3. **网络问题**: 检查网络连接和防火墙设置
4. **硬件问题**: 确保系统资源充足

---

**注意**: 本系统仅供学习和研究使用，检测结果仅供参考，实际应用请结合专业判断。

**版权声明**: 本系统基于开源技术开发，遵循相关开源协议。