YOLO Label Tool

基于 PySide6 的 YOLO 标注和训练工具，支持手动标注、模型辅助标注、实时窗口检测和模型训练功能。

功能特点

🎯 核心功能

• 图片管理：加载/关闭文件夹、自动恢复上次文件夹、图片预览、切换图片
• 标注绘制：手动绘制矩形标注框、编辑标注框、删除标注
• 类别管理：添加/编辑/删除标注类别、清空所有类别、自定义类别颜色、16色调色盘自动分配不重复颜色
• 数据导出：导出YOLO格式数据集（data.yaml + labels文件夹），支持自定义yaml文件名，一步完成
• 切图自动保存：切换图片时自动保存当前标注，无需手动点击
• 键盘快捷键：←/→ 翻图、Tab/Shift+Tab 循环切换类别

🚀 高级功能

• 模型辅助标注：加载训练好的YOLO模型进行自动标注
• 模型参数调整：实时调整置信度阈值、IoU阈值
• 数据集划分：自动划分训练集/验证集/测试集，支持分层采样、均衡采样
• 模型训练：完整的YOLO模型训练功能，支持多种训练参数配置
• 国际化支持：中英文双语界面，支持动态语言切换
• 快捷键支持：提高标注效率
• 标注统计：各类别标注数量统计

🎨 用户体验

• 三主题切换：支持黑夜/白天/炫彩主题，保护眼睛
• 图片缩放：支持放大/缩小/适应窗口、鼠标滚轮缩放
• 快捷键：常用操作快捷键支持
• 状态显示：实时显示标注状态和信息
• 撤销/重做：支持标注操作的撤销和重做（命令模式，最多 100 步）
• 日志系统：自动记录程序运行日志和异常信息，方便调试

🖥️ 实时验证

• 窗口捕获检测：实时捕获屏幕中指定窗口内容进行 YOLO 目标检测
• 区域捕获检测：选择屏幕任意区域进行实时目标检测
• 图片检测：支持单张图片文件检测
• DXCam 高性能捕获：基于 dxcam 实现低延迟屏幕捕获
• 窗口高亮：捕获窗口时自动高亮边框
• DPI 感知：支持多显示器不同 DPI 缩放
• 显示控制：可调节标签字体大小，开关置信度显示

🔧 图片列表管理

• 右键菜单：删除所有未标注图片（同时删除本地文件）、从列表中移除（保留本地文件）
• 多选操作：支持 Ctrl/Shift 多选图片后批量移除
• 图片统计：实时显示已标注/未标注图片数量

🔧 开发增强

• 异常捕获：自动捕获未处理异常并记录到日志文件
• 模块化设计：代码结构清晰，易于扩展和维护
• 配置文件：保存用户偏好设置，如窗口大小、主题、类别
• 国际化架构：支持多语言，易于扩展新语言
• 异常捕获：自动捕获未处理异常并记录到日志文件
• 模块化设计：代码结构清晰，易于扩展和维护
• 配置文件：保存用户偏好设置，如窗口大小、主题、类别
• 国际化架构：支持多语言，易于扩展新语言

安装要求

环境要求

• Python 3.8+
• PySide6
• OpenCV
• ultralytics (YOLO模型支持和训练)

安装步骤

1. 克隆仓库

GitHub：git clone https://github.com/notzhong/YOLOLabelsTool.git
or
Gitee：git clone https://gitee.com/notzhong/YOLOLabelsTool.git
cd YoloLabelTool

2. 安装依赖

pip install -r requirements.txt

3. 运行应用

python main.py

打包发布

打包为独立可执行文件

YOLO Label Tool 支持使用 PyInstaller 打包为独立的可执行文件，方便在没有 Python 环境的 Windows 系统上运行。

打包步骤

1. 安装打包依赖

pip install -r requirements-build.txt

2. 下载并安装 UPX（可选，但推荐用于压缩）

   • 从 https://upx.github.io/ 下载 UPX
   • 解压并将 upx.exe 添加到系统 PATH

3. 执行打包命令

pyinstaller YoloLabelsTrainTool.spec

打包选项说明

• spec 文件：YoloLabelsTrainTool.spec 包含了完整的打包配置
• 打包内容：
  • 主程序可执行文件
  • 翻译文件（中英文）
  • 主题样式文件（黑夜/白天）
  • 图标文件
  • 配置文件和目录
• 输出目录：打包完成后，可执行文件位于 dist/YoloLabelsTrainTool/ 目录

打包注意事项

1. 文件大小：打包后的可执行文件较大（约 300MB-500MB），因为包含了 Python 运行时、PySide6、OpenCV、ultralytics 等依赖
2. 第一次启动：第一次启动可能较慢，系统需要进行解压和加载
3. 模型文件：用户自己的 YOLO 模型文件需要放在程序运行目录的 model/ 文件夹中
4. CUDA 支持：如果使用 GPU 加速，需要确保目标系统有合适的 NVIDIA 驱动和 CUDA 库

快速开始

1. 启动应用

python main.py

2. 加载图片

• 点击"加载文件夹"按钮选择包含图片的文件夹
• 支持的图片格式：jpg, jpeg, png, bmp, tiff, tif, gif

3. 标注图片

1. 选择类别：在右侧面板选择要标注的类别
2. 绘制标注框：在图片上按住鼠标左键拖拽绘制矩形框
3. 编辑标注：可以调整、删除已绘制的标注框

4. 导出数据

1. 保存标注：标注自动保存，切换图片时自动保存当前标注，无需手动点击
2. 导出YOLO格式：点击"导出YOLO格式"，在文件对话框中选择输出路径及 data.yaml 文件名，一步完成
3. 数据集划分：支持自动划分训练集/验证集/测试集

5. 模型训练

1. 准备数据集：使用本工具标注并导出YOLO格式数据集
2. 配置训练：通过菜单"模型 → 训练模型"打开训练配置对话框
3. 开始训练：配置参数后点击"开始训练"按钮

6. 实时目标检测

1. 加载模型：通过菜单"模型 → 加载模型"加载 YOLO 模型
2. 打开验证窗口：通过菜单"模型 → 验证模型"打开实时检测对话框
3. 选择捕获源：
   • 窗口模式：鼠标移动到目标窗口上，点击确认捕获
   • 区域模式：拖拽选择屏幕任意区域进行实时检测
   • 图片模式：选择单张图片文件检测

快捷键

快捷键	功能
Ctrl+O	打开文件夹
Ctrl+S	保存标注
Ctrl+E	导出YOLO格式
Ctrl+Z	撤销
Ctrl+Y	重做
Delete	删除选中标注
A / ←	上一张图片
D / →	下一张图片
Tab / Shift+Tab	切换上一个/下一个标注类别
Ctrl+F	适应窗口
Ctrl++	放大
Ctrl±	缩小
Ctrl+A	自动标注当前图片
Ctrl+Shift+A	批量自动标注
Ctrl+M	加载模型
Ctrl+T	训练模型

标注格式

YOLO格式

导出文件结构：

output/
├── images/
│   ├── train/      # 训练集图片
│   ├── val/        # 验证集图片
│   └── test/       # 测试集图片
├── labels/
│   ├── train/      # 训练集标注（txt格式）
│   ├── val/        # 验证集标注
│   └── test/       # 测试集标注
├── train.txt       # 训练集图片路径列表（images/train/xxx.jpg）
├── val.txt         # 验证集图片路径列表（images/val/xxx.jpg）
├── test.txt        # 测试集图片路径列表（images/test/xxx.jpg）
└── data.yaml       # 数据集配置文件（导出时可自定义文件名）

data.yaml 格式

path: .  # 相对路径（方便数据集迁移到其他机器）
train: images/train
val: images/val
test: images/test

nc: 0  # 类别数量（根据实际添加的类别自动计算）
names: []  # 类别名称列表（ID 连续时为 list；不连续时为 dict）

标注文件格式（.txt）

每行一个标注，格式为：

<class_id> <x_center> <y_center> <width> <height>

所有坐标值都是归一化后的（0-1之间）。

未标注的图片会生成空的 .txt 文件，保证 images/ 和 labels/ 目录一一对应，确保 YOLO 训练兼容。

模型辅助标注

支持模型

项目基于 ultralytics 库实现模型加载和推理，支持以下 YOLO 模型版本：

• YOLOv5 (.pt格式) - 经典版本，支持广泛
• YOLOv6 (.pt格式) - 高效检测版本
• YOLOv8 (.pt格式) - 最新主流版本，支持目标检测、实例分割、姿态估计等
• YOLOv9 (.pt格式) - 2024年发布的先进版本
• YOLOv10 (.pt格式) - 2024年发布的高效版本
• YOLOv11 (.pt格式) - 2024年版本
• YOLOv26 (.pt格式) - 2025年版本

注意：ultralytics 库会自动适配不同版本的 YOLO 模型，只要模型文件是 .pt 格式且使用标准的 Ultralytics 架构，工具就能正确加载和使用。

使用方法

1. 加载模型：

   • 通过菜单"模型 → 加载模型"或工具栏加载YOLO模型
   • 右侧面板会显示模型信息面板（含置信度/IoU阈值调整控件）
   • 可选择导入模型类别到类别管理器

2. 自动标注：

   • 单张图片标注：选择图片后点击"自动标注"或按 Ctrl+A
   • 批量自动标注：选择多张图片后点击"批量自动标注"或按 Ctrl+Shift+A
   • 进度显示：批量标注时显示进度条

3. 模型参数调整：

   • 置信度阈值：调整检测结果的置信度要求
     • 范围：0.01 - 1.00
     • 默认值：0.25
     • 滑块 + 数值输入，实时调整
   • IoU阈值：调整非极大值抑制的重叠阈值
     • 范围：0.01 - 1.00
     • 默认值：0.45
     • 滑块 + 数值输入，实时调整

4. 模型管理：

   • 卸载模型：模型信息面板提供卸载按钮
   • 刷新信息：重新加载模型信息
   • 状态指示：绿色"● 已加载"或红色"● 未加载"

注意事项

• 需要安装 ultralytics 库：pip install ultralytics
• 模型首次推理可能需要额外时间下载权重
• 批量标注时可随时取消

实时目标检测验证

功能说明

提供三种实时/离线检测模式，用于验证模型效果：

1. 窗口捕获模式：

   • 鼠标移动到任意可见窗口上，窗口自动高亮红色边框
   • 点击确认后持续捕获该窗口内容进行实时检测
   • 窗口关闭时自动停止检测

2. 区域捕获模式：

   • 点击后进入全屏区域选择界面
   • 拖拽鼠标选择屏幕任意矩形区域
   • 持续对该区域进行实时检测

3. 图片检测模式：

   • 选择单张图片文件进行检测
   • 显示检测结果（绿色检测框 + 类别名称 + 置信度）

4. 显示控制：

   • 标签字体大小：滑块/数值输入框实时调整检测标签文字大小（0.1~2.0）
   • 置信度开关：勾选控制是否在标签上显示置信度分数
   • 类别名称：标签显示类别名称（如 person:0.85），而非数字 ID

依赖说明

• 窗口/区域捕获模式依赖 dxcam 库（可选，缺失时自动降级）
• 仅支持 Windows 系统（依赖 Win32 API）
• 支持多显示器不同 DPI 缩放

模型训练功能

训练配置

YOLO Label Tool 提供了完整的模型训练功能，支持详细的训练参数配置：

1. 基本设置：预训练模型、数据集配置、输出目录、恢复训练等
2. 训练参数：训练轮数、图像尺寸、批量大小、设备选择、早停耐心值等
3. 优化器设置：优化器选择、初始学习率、学习率调度策略等
4. 数据增强：Mixup增强、旋转、剪切、透视变换、HSV增强等
5. 高级参数：权重衰减、动量、学习率预热、损失权重、标签平滑等

训练界面

• 训练配置对话框：五个标签页分别配置不同参数
• 训练进度对话框：实时显示训练进度、损失曲线、日志输出
• 异步训练：训练在后台线程中进行，不阻塞主界面
• 进度监控：实时显示当前epoch、已用时间、损失值

市场最优参数

工具提供了经过验证的市场最优默认参数，支持一键重置：

• 优化器：AdamW（适合大多数场景）
• 学习率：0.01（配合余弦退火调度）
• 训练轮数：300（充分训练）
• 图像尺寸：640（平衡精度和速度）
• 批量大小：4（适配 8GB 显存，大显存可适当调大）
• 工作进程：4（Windows 下稳定配置）
• 数据增强：综合增强策略（HSV、旋转、剪切等）

国际化支持

支持语言

• 简体中文 (zh_CN) - 默认语言
• 英文 (en_US) - 国际通用语言

语言切换

• 通过菜单"语言 → 中文/英文"切换界面语言
• 支持实时切换，无需重启程序
• 所有UI文本、对话框、按钮、菜单都支持翻译

翻译架构

• 基于INI文件的翻译系统
• 支持动态加载和切换
• 易于扩展新语言（只需添加新的翻译文件）

项目结构

YoloLabelTool/
├── main.py                 # 主程序入口
├── pyproject.toml          # 项目配置和依赖
├── requirements.txt        # 依赖包列表
├── requirements-dev.txt    # 开发依赖
├── requirements-build.txt  # 打包构建依赖
├── README.md               # 项目说明
├── YoloLabelsTrainTool.spec # PyInstaller打包配置文件
├── icon.ico                # 应用程序图标
├── yolo26n.pt              # 预训练 YOLOv26n 模型文件（可选）
├── src/
│   ├── __init__.py         # 版本信息
│   ├── core/               # 核心模块
│   │   ├── annotation.py   # 标注数据结构和管理器（支持撤销/重做）
│   │   ├── class_manager.py # 类别管理器（支持YAML导入/导出/合并/统计）
│   │   ├── image_manager.py # 图片管理器（LRU缓存、缩略图、批量缩放）
│   │   └── model_manager.py # YOLO模型管理器
│   ├── ui/                 # 用户界面
│   │   ├── annotation_canvas.py # 标注画布组件（QGraphicsView 封装）
│   │   ├── main_window.py  # 主窗口（菜单、快捷键、面板协调）
│   │   ├── panels.py       # 统计面板 + 模型信息面板
│   │   ├── class_dialog.py # 类别编辑对话框
│   │   ├── region_selector.py # 窗口高亮器 + 屏幕区域选择器
│   │   ├── train_dialog.py # 训练配置对话框（5个标签页）
│   │   ├── train_progress_dialog.py # 训练进度对话框
│   │   └── validation_dialog.py # 实时验证/检测对话框
│   └── utils/              # 工具模块
│       ├── dataset_splitter.py # 数据集划分器
│       ├── i18n.py         # 国际化翻译管理器（预缓存 + en_US 回退）
│       ├── logger.py       # 日志系统模块
│       ├── widget_helpers.py # 滑块/SpinBox 同步绑定辅助类
│       ├── win32_helpers.py # Win32 API 辅助函数
│       └── yolo_exporter.py # YOLO格式导出器
├── yolo_tool/              # YOLO训练模块
│   ├── __init__.py
│   └── yolo_train.py       # YOLO模型训练器（异步训练）
├── translations/           # 国际化翻译文件
│   ├── zh_CN.ini           # 简体中文翻译
│   └── en_US.ini           # 英文翻译
├── qss/                    # 主题样式文件
│   ├── dark_theme.qss      # 黑夜主题样式
│   ├── light_theme.qss     # 白天主题样式
│   └── colorful_theme.qss  # 炫彩主题样式
├── config/                 # 配置文件目录
│   └── config.ini          # 用户配置设置
├── annotations/            # 标注文件目录（自动生成）
│   └── *_{hash}.json       # 标注数据文件（文件名+短哈希）
├── logs/                   # 日志文件目录（自动生成）
│   └── YYYY-MM-DD.log      # 按日期命名的日志文件
├── runs/                   # 训练结果目录（由ultralytics自动创建）
│   └── detect/
└── model/                  # 模型文件目录（用户可选创建）

开发说明

添加新功能

1. 扩展标注功能：修改 src/core/annotation.py
2. 修改界面：修改 src/ui/main_window.py 或对应面板组件（src/ui/panels.py、src/ui/annotation_canvas.py）
3. 添加导出格式：在 src/utils/ 下创建新的导出器
4. 添加训练功能：修改 yolo_tool/yolo_train.py 和 src/ui/train_dialog.py
5. 添加新语言支持：在 translations/ 目录下添加新的翻译文件
6. 使用日志系统：通过 from src.utils.logger import get_logger_simple 获取日志记录器

运行测试

pytest tests/

常见问题

Q: 无法加载图片

A: 检查图片格式是否支持，文件路径是否包含中文或特殊字符

Q: 导出失败

A: 检查输出目录权限，确保有写入权限

Q: 模型加载失败

A: 检查模型文件路径是否正确，确保安装了ultralytics库

Q: 界面显示异常

A: 尝试调整窗口大小，或检查PySide6版本

Q: 训练模型需要什么配置？

A: 训练模型需要足够的GPU内存（建议8GB以上）和充足的数据集。CPU训练也可行，但速度较慢。

Q: 实时检测功能需要什么依赖？

A: 窗口捕获和区域捕获模式需要安装 dxcam 库（pip install dxcam），且仅支持 Windows 系统。图片检测模式无额外依赖。

Q: 如何切换界面语言？

A: 通过菜单"语言 → 中文/英文"切换界面语言，切换会立即生效，无需重启程序。

贡献指南

1. Fork 本仓库
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情

联系方式

如有问题或建议，请通过以下方式联系：

• 提交 Issue
• 发送邮件到 developer@example.com

更新日志

v2.1.0 (2026-05-04)

• 图片列表右键菜单：删除所有未标注图片（连本地文件一起删）、从列表中移除选中图片（不删文件）、支持 Ctrl/Shift 多选
• 修复数据集导出 Bug：“Export Dataset Split” 补全缺失的 data.yaml；未标注图片现在生成空 label 文件保证 images/labels 一致
• 修复训练多个问题：
  • 多次训练时信号累积连接导致重复弹窗
  • lr0 默认值不一致（UI 和训练器各有一个默认值）
  • TQDM stdout 为 None 崩溃、GBK 编码无法处理 emoji 字符
  • multiprocessing 子进程在 Windows 上重新启动 GUI
  • epoch 显示 0-indexed 改为 1-indexed
• 优化训练默认参数：batch 16→4、workers 8→4（适配 8GB 显存）
• 导出改进：data.yaml 改用相对路径、random_split 增加固定种子保证可复现
• 标注匹配改进：用索引替代坐标匹配，消除同位置同类别标注误删
• UI 改进：关闭训练进度对话框自动停止训练、单张自动标注增加覆盖确认、resume 模式不再强制要求 model_path
• 打包修复：移除 unittest 排除项解决 torch 导入失败、全面收集 ultralytics 子模块

v2.0.0 (2026-05-01)

• 提取标注画布组件：将 QGraphicsView 封装为独立 AnnotationCanvas 类（~520 行），主窗口仅通过信号通信
• 提取统计/模型面板：StatsPanel 和 ModelInfoPanel 独立为 panels.py，消除 ~280 行和 ~50 个 hasattr 守卫
• 提取窗口选择器组件：WindowHighlighter 和 RegionSelector 独立为 region_selector.py，Win32 API 辅助函数提取为 win32_helpers.py
• 数据集导出统一：DatasetSplitter 委托 YOLOExporter 处理文件 I/O，消除三个重复方法
• LRU 图片缓存：ImageManager 改用 OrderedDict 实现 LRU 淘汰策略
• 国际化增强：TranslationManager 启动时预缓存所有语言，新增 en_US 回退链
• 新增快捷键：←/→ 翻图、Tab/Shift+Tab 循环切换类别
• 切图自动保存：切换图片时自动保存当前标注
• 简化导出流程：YOLO 导出合并为单次文件对话框
• 新增单元测试：80 个测试用例覆盖核心数据类、命令模式、类别管理和图片缓存
• 修复 bug：补回提取画布时丢失的 add_annotation_with_command 方法定义
• 清除冗余代码：消除 12 处局部 tr() 导入、10 个重复的滑块绑定方法、死代码 _split_paths

v1.6.0 (2026-04-26)

• 重构 YOLO 导出：提取通用 annotation_to_yolo_lines() 函数，消除 yolo_exporter 与 dataset_splitter 间的标签写入重复代码
• 优化统计面板：update_statistics_panel() 改用缓存字典，消除 O(n) 磁盘 I/O
• 修复撤销/重做按钮匹配：移除按翻译文本匹配工具栏按钮的脆弱逻辑，改用 QAction 对象直接绑定
• 限制撤销栈深度：添加 MAX_UNDO_SIZE = 100，防止内存无限增长
• 修复类别 ID 空洞：删除类别时始终更新 _next_class_id，避免 ID 跳跃浪费
• 重构模型推理：提取 _process_boxes() 共享方法，消除 predict() 与 predict_image() 中的重复 box 处理代码
• 优化十字准线渲染：复用图形项替代每次 mouseMove 创建/销毁，减少 GC 压力
• 清理 i18n 死代码：移除未使用的 _fallback_translations 与 QTranslator 安装逻辑
• 精简浏览方法：将 train_dialog 四个结构相同的浏览方法合并为两个通用方法

v1.5.0 (2026-04-26)

• 新增标签显示控制：检测标签字体大小可调（滑块0.1~2.0），置信度显示可开关
• 标签显示优化：检测结果框显示类别名称（如 person）而非数字ID
• 修复窗口选择交互：简化选择逻辑，点击目标窗口即可确认，无需拖拽
• 修复区域选择死锁：移除 per-pixel alpha 分层窗口，改用统一透明度，解决 exec() 模态事件循环死锁
• 区域选择视觉优化：去除窗口整体透明度设置，橡皮筋选择框清晰可见
• 验证窗口焦点修复：区域选择完成后自动恢复验证窗口焦点

v1.0.0~1.4.0 (2026-02-22~2026-04-26)

• 初始版本发布：手动标注、YOLO导出、模型辅助标注、暗色主题
• 新增日志系统、双主题切换、模型信息面板增强
• 新增模型训练功能、国际化支持（中英文动态切换）
• 新增 PyInstaller 打包支持
• 新增实时验证/检测功能（窗口捕获、区域捕获、图片检测）