# SmartLabel

**Repository Path**: giaming023/SmartLabel

## Basic Information

- **Project Name**: SmartLabel
- **Description**: SmartLabel 是一个开源的、AI 驱动的图像标注工具，旨在加速计算机视觉任务（如分类、目标检测、旋转边界框（OBB）、分割和视频标注）的标注工作。它专为速度和简洁而构建，利用最先进的模型进行半自动预标注，让您专注于优化而不是从头开始。无论您是为 YOLO、SAM 还是自定义模型准备数据集，SmartLabel 都通过直观的 Web 界面和强大的后端简化您的工作流程。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-04-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SmartLabel：面向计算机视觉的快速近乎全自动图像标注工具

**SmartLabel** 是一个开源的、AI 驱动的图像标注工具，旨在加速计算机视觉任务（如分类、目标检测、旋转边界框（OBB）、分割和视频标注）的标注工作。它专为速度和简洁而构建，利用最先进的模型进行半自动预标注，让您专注于优化而不是从头开始。无论您是为 YOLO、SAM 还是自定义模型准备数据集，SmartLabel 都通过直观的 Web 界面和强大的后端简化您的工作流程。

非常适合处理大型图像数据集的研究人员、数据科学家和机器学习工程师——在几分钟而不是几小时内获得高质量标注！

## 为什么选择 SmartLabel？

SmartLabel 主要专注于 AI 模型集成的便捷性，以实现快速的 CV 任务标注。

- **AI 驱动的预标注**：使用 YOLO、SAM2 和 Grounding DINO 自动检测和分割对象——节省高达 80% 的手动工作量。
- **多任务支持**：在一个工具中处理分类、边界框、旋转边界框和多边形分割，现在甚至支持视频。
- **基于浏览器的编辑**：交互式画布用于精确调整，在浏览器中实时进行 SAM 驱动的分割。
- **离线友好**：模型自动下载（或预取以供离线使用），SQLite 后端用于本地项目。
- **可扩展且开源**：使用您自己的 ultralytics 模型进行自定义或集成到流程中——欢迎贡献！
- **基于 SAM2 的 webgpu**：通过 SAM2 即时绘制标注，支持 worker 卸载和自动标注以加快计算速度！

![标注编辑演示](examples/SmartLabelv1.gif) 

## 功能特性

* **半自动标注**
  使用 AI 模型（如用于检测的 **YOLO (v5–v12)**、用于分割的 **SAM2**、用于零样本对象定位的 **Grounding DINO** 和用于自动分类的 **CLIP**）快速启动标注。

* **灵活的标注类型**

  * 用于标准检测的轴对齐边界框。
  * 用于旋转对象（如航拍图像）的旋转边界框。
  * 用于精确边界的多边形分割。
  * 带有自动标签建议的图像分类。

* **视频标注与标签传播**
  以帧到帧的一致性标注视频：

  * **SmartPropagator**（SAM2 驱动的精确传播）。
  * **OpenCV 跟踪器**（CSRT、KCF、Boosting、MIL、TLD、MedianFlow、MOSSE、GOTURN）。
  * 在标注的起始/结束帧之间进行 **插值**。

* **跨域标注**

  * 使用检测模型自动生成分割掩码。
  * 使用分割模型预标注边界框。

* **Ultralytics 模型支持**
  完全支持 **YOLOv12、v11、v10、v9、v8、v5**，以及用于开放词汇预标注的 **YOLOv8-world**（无需 GPU）。

* **交互式前端**
  在响应式画布上绘制、编辑和优化标签。

  * 使用基于浏览器的 SAM2 进行 **点击分割**。
  * 热键、撤销/重做和缩放以实现高效标注。

* **项目管理**
  使用 SQLite 支持的项目组织数据集。

  * 多类别支持。
  * 最小化设置的导入/导出。

* **导出格式**
  将标注导出为 **YOLO、COCO 或自定义格式** 以实现无缝训练。

* **性能优化**

  * GPU 内存管理，用于高效的模型加载/卸载。
  * 聚类重叠检测、简化轮廓并按置信度过滤。
  * 多线程上传和优化的图像导入。

* **云/SSH 集成**
  从云存储或 SSH 服务器下载图像，远程保存标注，并管理大规模项目。

* **后端迁移到 FastAPI**
  更快的响应时间、异步支持和更流畅的 UI 性能。

* **SmartLabel Python API**
  将标注工作流程集成到自定义脚本和机器学习流程中。

## 演示

基于预训练/零样本模型的检测：

![标注编辑演示](examples/AIpreannotator-demo.gif)

使用智能传播器的视频分割：

https://github.com/user-attachments/assets/c5caa227-a9bb-4ff3-a11a-688067fb58ae

## 安装

SmartLabel 已在 `Python 3.10+` 上测试。

> [!NOTE]
> SmartLabel v1 引入了新的数据库管理逻辑。
> 为避免与旧版本冲突，您需要在运行新版本之前 **重命名/删除旧的缓存文件夹**：
> 
> - **Linux**：`~/.cache/SmartLabel_cache`
> - **macOS**：`~/Library/Caches/SmartLabel_cache`
> - **Windows**：`%LOCALAPPDATA%\SmartLabel_cache`
> 
> 删除文件夹后，重启 SmartLabel —— 它将自动以新结构重新创建缓存目录。

```bash
pip install -U SmartLabel
```

用于开发或可编辑安装（从克隆的仓库）：

```bash
git clone https://github.com/giaming023/SmartLabel.git
cd SmartLabel
pip install -e .
```
 
## 快速开始

使用单个命令启动 SmartLabel——它会自动启动本地 Web 服务器并在浏览器中打开。

```bash
SmartLabel
```

1. 创建新项目并上传图像。
2. 定义类别（例如，"car"、"person"）。
3. 对于易于检测的对象，运行 AI 预标注（选择模型：YOLO、Grounding DINO）。
4. 在交互式编辑器中优化标签。
5. 导出您标注的数据集。

SmartLabel 应用程序使用缓存目录在本地存储设置。

### 使用 AI 进行预标注

SmartLabel 使用先进的模型进行初始标注：

- **YOLO**：所有基于 ultralytics 的 YOLO 模型现在都兼容并可以使用。
- **SAM2**：精确分割，用于图像标注和视频传播
- **Grounding DINO**：通过文本提示进行零样本检测。

## MySQL表详解
SmartLabel 项目使用 MySQL 数据库，采用**单库多项目**架构（所有项目共用同一个数据库，通过 `project_id` 区分）。以下是每个表的详细作用：

---

### **1. sl_projects（项目表）**
**作用**：存储项目的基本信息

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | BIGINT | 项目 ID（主键） |
| `name` | VARCHAR(255) | 项目名称（唯一） |
| `description` | TEXT | 项目描述 |
| `setup_type` | VARCHAR(64) | 项目类型（如 "Bounding Box", "Segmentation", "Classification" 等） |
| `annotation_style_config` | TEXT | 标注样式配置（JSON 格式） |
| `created_time` | DATETIME | 创建时间 |
| `updated_time` | DATETIME | 更新时间 |

**用途**：
- 每个项目对应一条记录
- 决定项目的标注类型（检测/分割/分类）
- 存储用户的标注偏好设置

---

### **2. sl_classes（类别表）**
**作用**：存储每个项目的标注类别

| 字段 | 类型 | 说明 |
|------|------|------|
| `project_id` | BIGINT | 所属项目 ID（联合主键） |
| `class_name` | VARCHAR(255) | 类别名称（如 "cat", "dog", "car"） |

**用途**：
- 定义项目中可用的标注类别
- 用于 AI 预标注时的提示词生成
- 联合主键确保同一项目中类别不重复

---

### **3. sl_images（图像表）**
**作用**：存储所有图像的元数据

| 字段 | 类型 | 说明 |
|------|------|------|
| `image_id` | BIGINT | 图像 ID（主键） |
| `project_id` | BIGINT | 所属项目 ID |
| `absolute_path` | VARCHAR(512) | 图像文件的绝对路径 |
| `width` | INT | 图像宽度（像素） |
| `height` | INT | 图像高度（像素） |

**用途**：
- 记录所有导入的图像文件
- **视频帧也存储在这里**，但 `absolute_path` 是虚拟路径（格式：`video.mp4#frame_number`）
- 前端通过此表获取图像列表进行展示

---

### **4. sl_annotations（标注表）**
**作用**：存储用户手动创建的正式标注

| 字段 | 类型 | 说明 |
|------|------|------|
| `annotation_id` | BIGINT | 标注 ID（主键） |
| `image_id` | BIGINT | 所属图像 ID |
| `user_id` | BIGINT | 创建者用户 ID |
| `type` | VARCHAR(64) | 标注类型（"rect" / "polygon" / "classification"） |
| `class_name` | VARCHAR(255) | 类别名称 |
| `x`, `y` | DOUBLE | 位置坐标（左上角） |
| `width`, `height` | DOUBLE | 宽高尺寸 |
| `rotation` | DOUBLE | 旋转角度（默认 0） |
| `segmentation` | LONGTEXT | 分割多边形点集（JSON 数组） |

**用途**：
- 存储用户在前端绘制的标注
- 导出功能从这里读取数据
- 支持矩形框、多边形、分类三种类型

---

### **5. sl_preannotations（预标注表）**
**作用**：存储 AI 自动生成的预标注结果

| 字段 | 类型 | 说明 |
|------|------|------|
| `preannotation_id` | BIGINT | 预标注 ID（主键） |
| `image_id` | BIGINT | 所属图像 ID |
| `type` | VARCHAR(64) | 标注类型 |
| `class_name` | VARCHAR(255) | 类别名称 |
| `x`, `y`, `width`, `height` | DOUBLE | 几何参数 |
| `rotation` | DOUBLE | 旋转角度 |
| `segmentation` | LONGTEXT | 分割多边形 |
| `confidence` | DOUBLE | AI 置信度（0~1） |

**用途**：
- AI 预标注功能的结果存储（YOLO、Grounding DINO、SAM2 等）
- 前端以灰色显示，用户可以确认或修改
- 确认后转移到 `sl_annotations` 表并清空此表

---

### **6. sl_reviewed_images（已审核图片表）**
**作用**：标记已经过审核的图像

| 字段 | 类型 | 说明 |
|------|------|------|
| `image_id` | BIGINT | 图像 ID（主键） |
| `reviewed_at` | TIMESTAMP | 审核时间 |
| `user_id` | BIGINT | 审核人用户 ID |

**用途**：
- 质量检查流程中，标记已审核的图片
- 防止重复审核
- 追踪审核责任人

---

### **7. sl_videos（视频表）**
**作用**：存储视频文件的元数据

| 字段 | 类型 | 说明 |
|------|------|------|
| `video_id` | BIGINT | 视频 ID（主键） |
| `project_id` | BIGINT | 所属项目 ID |
| `absolute_path` | VARCHAR(512) | 视频文件绝对路径 |
| `name` | VARCHAR(255) | 视频文件名 |
| `duration` | DOUBLE | 时长（秒） |
| `fps` | DOUBLE | 帧率 |
| `frame_count` | INT | 总帧数 |
| `width`, `height` | INT | 视频分辨率 |

**用途**：
- 视频标注项目的核心表
- 提取帧时作为索引基础
- 导出视频标注时使用

---

### **8. sl_frames（帧表）**
**作用**：存储视频帧的索引信息

| 字段 | 类型 | 说明 |
|------|------|------|
| `frame_id` | BIGINT | 帧 ID（主键） |
| `video_id` | BIGINT | 所属视频 ID |
| `image_id` | BIGINT | 关联的图像 ID（指向 `sl_images`） |
| `frame_number` | INT | 帧号（从 0 开始） |
| `subsampled` | TINYINT(1) | 是否子采样帧（1=是，0=否） |
| `timestamp` | DOUBLE | 时间戳（秒） |

**用途**：
- 建立视频帧与图像记录的关联
- 记录哪些帧被提取出来用于标注
- 支持视频播放时的标注同步

---

### **9. sys_user（用户表）** ⭐ 外部表
**作用**：FastapiAdmin 的统一用户管理系统表（独立于项目数据库）

| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | BIGINT | 用户 ID |
| `username` | VARCHAR(255) | 用户名（唯一） |
| `password` | VARCHAR(255) | 密码哈希 |
| `name` | VARCHAR(255) | 显示名称 |
| `email` | VARCHAR(255) | 邮箱 |
| `status` | VARCHAR(1) | 状态（"0"=活跃，"1"=禁用） |
| `is_superuser` | TINYINT(1) | 是否超级管理员 |
| `created_time` | DATETIME | 创建时间 |
| `updated_time` | DATETIME | 更新时间 |

**用途**：
- 用户认证和授权
- 标注记录关联到具体用户
- 权限管理

---

## 🔗 **表之间的关系图**

```
sys_user (用户表)
    │
    ├─ user_id → sl_annotations.user_id (谁创建的标注)
    └─ user_id → sl_reviewed_images.user_id (谁审核的图片)

sl_projects (项目表)
    │
    ├─ project_id → sl_classes.project_id (项目包含的类别)
    ├─ project_id → sl_images.project_id (项目包含的图片)
    └─ project_id → sl_videos.project_id (项目包含的视频)

sl_videos (视频表)
    │
    └─ video_id → sl_frames.video_id (视频包含的帧)

sl_images (图像表)
    │
    ├─ image_id → sl_annotations.image_id (图像的标注)
    ├─ image_id → sl_preannotations.image_id (图像的预标注)
    ├─ image_id → sl_reviewed_images.image_id (图像的审核状态)
    └─ image_id ← sl_frames.image_id (帧对应的图像记录)
```


---

## 💡 **典型数据流**

### **图片标注流程**：
1. 上传图片 → 写入 `sl_images`
2. AI 预标注 → 写入 `sl_preannotations`
3. 用户在前端查看并修改 → 删除旧的 `sl_annotations`
4. 确认标注 → 从 `sl_preannotations` 转移到 `sl_annotations`

### **视频标注流程**：
1. 上传视频 → 写入 `sl_videos`
2. 提取帧 → 写入 `sl_images`（虚拟路径）+ `sl_frames`
3. 标注某一帧 → 写入 `sl_annotations`
4. 使用跟踪器（SAM2/CV2）→ 批量写入 `sl_preannotations`
5. 确认所有帧 → 批量转移到 `sl_annotations`

### **导出流程**：
1. 从 `sl_annotations` 读取标注数据
2. 从 `sl_images` 获取图像路径
3. 根据 `sl_projects.setup_type` 决定导出格式（COCO/YOLO/Pascal VOC 等）

---

这样的数据库设计使得 SmartLabel 能够：
- ✅ 支持多种标注类型（检测/分割/分类）
- ✅ 支持图片和视频两种媒体
- ✅ 支持 AI 预标注和人工作标注协作
- ✅ 完整的质量控制和审核流程
- ✅ 灵活的导出功能

## 安装依赖

### 1. 安装 Python 依赖
```bash
pip install -r requirements.txt
```

### 2. 安装 FFmpeg
- **Windows**: 运行 `python install_ffmpeg.py` 自动安装
- **其他系统**: 请手动安装 FFmpeg 并添加到环境变量

### 3. 验证安装
```bash
ffmpeg -version
```