ShaoHua
353 lines
8.5 KiB
Markdown
353 lines
8.5 KiB
Markdown
|
||
# 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) 进行模型训练。
|
||
|
||
祝你标注顺利！
|