流程走通。（效果不行:数据集和数据标注都比较少）

2026-05-05 03:02:34 +08:00
parent 41e3bb113a
commit 3fa64a95f8
28 changed files with 1179 additions and 404 deletions
@@ -0,0 +1,352 @@
+
+# VisioFirm 标注工具使用指南
+
+本指南将帮助你使用 VisioFirm 进行 YOLO 目标检测数据标注。
+
+***
+
+## 目录
+
+1. [VisioFirm 简介](#1-visiofirm-简介)
+2. [安装与启动](#2-安装与启动)
+3. [项目设置](#3-项目设置)
+4. [标注操作](#4-标注操作)
+5. [导出 YOLO 格式](#5-导出-yolo-格式)
+6. [使用导出数据](#6-使用导出数据)
+7. [快捷键](#7-快捷键)
+
+***
+
+## 1. VisioFirm 简介
+
+VisioFirm 是一款开源、跨平台的 AI 辅助图像标注工具，专为计算机视觉任务设计。
+
+**官方链接：**
+
+- GitHub 仓库：<https://github.com/OschAI/VisioFirm>
+- PyPI 项目：<https://pypi.org/project/visiofirm/>
+- 论文地址：<https://arxiv.org/abs/2509.04180>
+
+**主要特性：**
+
+- AI 驱动的预标注（YOLO、SAM2、Grounding DINO），节省高达 80% 人工标注
+- 支持多种标注格式：YOLO、COCO、PascalVOC 等
+- 自动划分训练/验证/测试集
+- 支持视频标注和标签传播
+- 直观的用户界面
+- 批量处理功能
+- 标注验证和预览
+- 支持分类、目标检测、分割任务
+
+***
+
+## 2. 安装与启动
+
+### 2.1 系统要求
+
+- Python 3.10 或更高版本
+- 推荐使用 CUDA 11.8（如需 GPU 加速）
+- 16GB 或更多内存
+
+### 2.2 安装（推荐方式：pip）
+
+**注意：** VisioFirm 直接安装在项目的 `yolo_demo` 环境中，无需创建新环境。
+
+1. 激活项目虚拟环境：
+   ```bash
+   conda activate yolo_demo
+   ```
+2. 设置 UTF-8 环境变量（Windows 中文环境必须）：
+   ```powershell
+   # PowerShell
+   $env:PYTHONUTF8=1
+   ```
+3. 使用 pip 安装 VisioFirm：
+   ```bash
+   pip install visiofirm
+   ```
+
+**或者使用一键启动脚本：**
+
+```powershell
+.\start_visiofirm.ps1
+```
+
+### 2.3 启动 VisioFirm
+
+**方法一：使用一键启动脚本（推荐）**
+
+直接运行项目根目录下的启动脚本：
+
+```powershell
+.\start_visiofirm.ps1
+```
+
+**方法二：手动启动**
+
+1. 激活环境并设置 UTF-8：
+   ```powershell
+   conda activate yolo_demo
+   $env:PYTHONUTF8=1
+   ```
+2. 启动 VisioFirm：
+   ```bash
+   visiofirm
+   ```
+
+启动后，浏览器会自动打开 VisioFirm 界面（通常是 [http://localhost:8000）。>](http://localhost:8000）。>)
+
+***
+
+## 3. 项目设置
+
+### 3.1 创建新项目
+
+1. 打开 VisioFirm
+2. 点击 **"New Project"** 或 **"创建新项目"**
+3. 输入项目名称（如：YOLO_Demo）
+4. 选择项目保存位置
+
+### 3.2 配置项目
+
+**导入图片：**
+
+1. 点击 **"Import Images"** 或 **"导入图片"**
+2. 选择你的图片文件夹
+3. 选择要标注的图片文件（可全选）
+
+**设置类别：**
+
+1. 点击 **"Classes"** 或 **"类别"** 标签
+2. 点击 **"Add Class"** 或 **"添加类别"**
+3. 输入类别名称（如：car, person, bicycle）
+4. 为每个类别选择颜色（便于区分）
+5. 保存类别配置
+
+示例类别配置：
+
+```
+0: person   (行人)
+1: bicycle  (自行车)
+```
+
+**数据集划分设置（可选）：**
+
+VisioFirm 在导出时会自动将数据集划分为 train/val/test。默认划分比例：
+- 训练集（train）：70%
+- 验证集（val）：15%
+- 测试集（test）：15%
+
+***
+
+## 4. 标注操作
+
+### 4.1 基本标注步骤
+
+1. 从左侧图片列表中选择要标注的图片
+2. 选择标注工具（通常是矩形框工具）
+3. 在图片上拖动鼠标绘制边界框，框选目标
+4. 从类别列表中选择对应的类别
+5. 确认标注无误后，点击保存或自动保存
+
+### 4.2 标注技巧
+
+**精确框选：**
+
+- 尽量紧贴目标边缘绘制边界框
+- 避免框选过多背景
+- 对于部分遮挡的目标，仍然标注可见部分
+
+**类别一致性：**
+
+- 保持同类目标标注标准一致
+- 对于模糊不清的目标，可以选择跳过或标记为不确定
+
+**标注顺序：**
+
+- 按类别顺序标注，减少类别切换
+- 使用快捷键提高效率
+
+**AI 预标注（推荐）：**
+
+VisioFirm 支持 AI 预标注功能，可以大幅提高标注效率：
+1. 点击 AI 预标注按钮
+2. 选择合适的模型（如 YOLO）
+3. 自动生成标注框
+4. 人工检查和修正
+
+***
+
+## 5. 导出 YOLO 格式
+
+### 5.1 导出设置
+
+1. 完成标注后，点击 **"Export"** 或 **"导出"**
+2. 选择 **"YOLO"** 格式
+3. 设置导出选项：
+   - 导出路径：选择项目内的 `dataset/tags/visiofirm/` 目录
+   - 勾选 "自动划分 train/val/test"
+   - 类别映射：确认类别名称正确
+   - 坐标格式：选择归一化坐标（0-1）
+4. 可以选择导出为 ZIP 压缩包或文件夹
+
+### 5.2 执行导出
+
+1. 点击 **"Export"** 或 **"开始导出"**
+2. 等待导出完成
+3. 导出完成后，会在 `dataset/tags/visiofirm/` 目录下生成新文件夹（如 `20260505_01/`）
+
+### 5.3 导出结果说明
+
+导出后，目录结构如下：
+
+```
+dataset/tags/visiofirm/
+├── 20260505_01/           # 每次导出会生成带日期的文件夹
+│   ├── data.yaml          # 数据集配置文件（VisioFirm 格式）
+│   ├── train/
+│   │   ├── images/        # 训练集图片
+│   │   └── labels/        # 训练集标注
+│   ├── val/
+│   │   ├── images/        # 验证集图片
+│   │   └── labels/        # 验证集标注
+│   └── test/
+│       ├── images/        # 测试集图片
+│       └── labels/        # 测试集标注
+└── 1_YOLO.zip             # ZIP 压缩包（可选）
+```
+
+**标注文件格式：**
+
+```
+class_id center_x center_y width height
+```
+
+**示例：**
+
+```
+0 0.5 0.5 0.3 0.4
+1 0.2 0.3 0.1 0.2
+```
+
+**说明：**
+
+- `class_id`：类别 ID（从 0 开始）
+- `center_x, center_y`：边界框中心点坐标（归一化 0-1）
+- `width, height`：边界框宽高（归一化 0-1）
+
+***
+
+## 6. 使用导出数据
+
+### 6.1 配置项目
+
+1. 复制 `configs/dataset-traditional.yaml` 到项目根目录，重命名为 `dataset.yaml`
+2. 编辑 `dataset.yaml`，修改 `path` 指向刚导出的数据文件夹：
+
+```yaml
+path: ./dataset/tags/visiofirm/20260505_01
+train: train/images
+val: val/images
+test: test/images
+
+nc: 2
+names:
+  - person
+  - bicycle
+```
+
+**注意：** `nc` 和 `names` 需要根据你实际标注的类别进行修改。
+
+### 6.2 验证数据集
+
+使用项目验证脚本检查导出的标注：
+
+```bash
+python src/validate_dataset.py
+```
+
+验证通过后，即可开始训练模型！
+
+***
+
+## 7. 快捷键
+
+| 快捷键       | 功能     |
+| --------- | ------ |
+| `W` 或 `R` | 矩形框工具  |
+| `A`       | 上一张图片  |
+| `D`       | 下一张图片  |
+| `Ctrl+S`  | 保存标注   |
+| `Ctrl+Z`  | 撤销     |
+| `Ctrl+Y`  | 重做     |
+| `Del`     | 删除选中的框 |
+| `Esc`     | 取消当前操作 |
+| `Space`   | 平移画布   |
+| `鼠标滚轮`    | 缩放     |
+
+**注意：** 具体快捷键可能因 VisioFirm 版本不同而略有差异，请以实际软件为准。
+
+***
+
+## 8. 标注质量检查
+
+完成标注后，建议进行以下检查：
+
+1. **完整性检查**
+   - 确认所有图片都已标注
+   - 确认所有目标都已框选
+
+2. **准确性检查**
+   - 检查边界框是否准确
+   - 检查类别是否正确
+
+3. **格式验证**
+   - 使用项目中的验证脚本检查标注格式：
+   ```bash
+   python src/validate_dataset.py
+   ```
+
+***
+
+## 9. 常见问题
+
+### Q: VisioFirm 如何获取？
+
+A: 推荐使用 pip 安装：`pip install visiofirm`，详细步骤见"安装与启动"章节。
+也可以访问 GitHub 仓库：<https://github.com/OschAI/VisioFirm> 获取源码。
+
+### Q: VisioFirm 是免费的吗？
+
+A: 是的，VisioFirm 是开源软件，采用 Apache-2.0 许可证，完全免费使用。
+
+### Q: 导出后如何使用这些数据？
+
+A: 导出的数据已经自动划分好 train/val/test。
+只需修改项目根目录的 `dataset.yaml` 中的 `path` 指向导出文件夹即可开始训练。
+
+### Q: 如何批量处理图片？
+
+A: VisioFirm 支持批量导入图片，可以一次选择多张或整个文件夹进行标注。
+导出时也支持批量导出所有标注。
+
+### Q: 标注过程中如何暂停和继续？
+
+A: VisioFirm 会自动保存进度，关闭浏览器标签页后重新打开 <http://localhost:8000> 即可继续。
+
+### Q: 如何修改已有标注？
+
+A: 选择要修改的框，可以拖动调整位置或大小，也可以删除后重新标注。
+对于 AI 预标注的结果，可以直接进行修正。
+
+### Q: 遇到技术问题怎么办？
+
+A: 可以在 GitHub Issues 页面提交问题：<https://github.com/OschAI/VisioFirm/issues>
+
+***
+
+## 下一步
+
+标注完成后，请继续参考 [YOLO 模型测试流程指南](./1.YOLO模型测试流程指南.md) 进行模型训练。
+
+祝你标注顺利！