# 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) 进行模型训练。

祝你标注顺利！