提交4-2图像标注实战（Label Studio）

2026-06-02 10:57:48 +08:00
parent 132b6bb861
commit 36df679989
1 changed files with 735 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -1,2 +1,736 @@
-# 4-2-image-labeling
+# 4-2 图像标注实战（Label Studio）
 ## 学习目标
 1. 掌握 Label Studio 的安装、启动与界面使用
 2. 学会配置三种图像标注类型（分类、目标检测、语义分割）
 3. 独立完成边界框、多边形、关键点的标注
 4. 理解 VOC / YOLO / COCO 三种导出格式的区别
 ---
 ## 1. Label Studio 简介
 ### 1.1 一句话定义
 **Label Studio**：一个开源的、**多模态**数据标注平台，支持图像、文本、语音、视频等几乎所有数据类型的标注与团队协作。
 ### 1.2 为什么选它
 我们这门课统一用 Label Studio 的原因：
 | 需求 | Label Studio 对应能力 |
 |------|---------------------|
 | 多种数据类型 | 图像 / 文本 / 语音 / 视频 / 时序，一站式 |
 | 不用写代码 | 通过 XML 标签可视化配置标注界面 |
 | 团队协作 | 内置成员管理、角色权限、任务分配 |
 | 格式灵活 | 内置 YOLO、COCO、VOC、JSON、CSV 导出 |
 | 本地部署 | 数据不出学校，开源免费 |
 ```
 传统方案（多工具切换）：
  图像 → LabelImg
  文本 → Doccano
  语音 → Audacity / ELAN
  协作 → Excel 邮件
 Label Studio 一站式：
  图像 / 文本 / 语音 / 协作 → Label Studio
 ```
 ### 1.3 与其他工具的对比
 | 工具 | 类型 | 适用场景 | 本课程 |
 |------|------|---------|--------|
 | **Label Studio** | 开源/多模态 | 课程学习 / 中小团队 / 综合项目 | 主选 |
 | LabelImg | 开源/图像 | 极简目标检测 | 仅做对比 |
 | CVAT | 开源/图像视频 | 大型分割、视频跟踪 | 了解 |
 | Doccano | 开源/文本 | 简单文本分类 | 已弃用 |
 | Scale AI | 商业 | 企业级标注 | 了解 |
 ---
 ## 2. Label Studio 安装与启动
 ### 2.1 环境要求
 - Python 3.8 及以上
 - 浏览器（Chrome / Edge / Firefox）
 - 建议 8G 以上内存
 ### 2.2 pip 安装（推荐）
 ```bash
 # 在命令行中执行
 pip install label-studio
 # 启动 Label Studio
 label-studio
 ```
 启动后命令行会显示：
 ```
 [INFO] Label Studio is running at http://localhost:8080
 [INFO] Open it in your browser to start labeling
 ```
 ### 2.3 第一次打开
 1. 浏览器访问 `http://localhost:8080`
 2. 第一次进入需要 **Sign Up** 注册管理员账号（用你的邮箱 + 密码）
 3. 注册后自动登录到主界面
 ```
 ┌────────────────────────────────────────────────────────┐
 │  Label Studio                                           │
 │  Sign Up                                                │
 ├────────────────────────────────────────────────────────┤
 │                                                         │
 │   Email:    [___________________________]               │
 │   Username: [___________________________]               │
 │   Password: [___________________________]               │
 │                                                         │
 │             [  Create Account  ]                        │
 │                                                         │
 └────────────────────────────────────────────────────────┘
 ```
 ### 2.4 安装常见问题
 | 问题 | 解决 |
 |------|------|
 | 端口 8080 被占用 | `label-studio --port 8001` |
 | 启动报错找不到模块 | `pip install --upgrade label-studio` |
 | 中文乱码 | 系统区域设置改为 UTF-8 |
 | 浏览器无法打开 | 检查防火墙、放行端口 |
 ---
 ## 3. 主界面导览
 登录后看到的主界面：
 ```
 ┌──────────────────────────────────────────────────────────────┐
 │ [Label Studio]  Projects  Members  Settings  [用户头像]      │
 ├──────────────────────────────────────────────────────────────┤
 │                                                              │
 │   My Projects                                                │
 │                                                              │
 │   ┌────────────────────────────────────────────────┐        │
 │   │  + Create Project                              │        │
 │   └────────────────────────────────────────────────┘        │
 │                                                              │
 │   没有任何项目，点上面按钮开始                              │
 │                                                              │
 └──────────────────────────────────────────────────────────────┘
 ```
 **主要功能区**：
 - **Projects**：项目列表，每个项目对应一个标注任务
 - **Members**：成员管理（管理员可见）
 - **Settings**：个人设置
 ---
 ## 4. 创建第一个项目：图像分类
 ### 4.1 任务说明
 **任务**：对 10 张动物图片进行分类，类别有：cat / dog / bird
 ### 4.2 创建项目
 1. 点击 `+ Create Project`
 2. 填写：
   - **Project Name**：`animal_classification`
   - **Description**：动物图片三分类
 3. 点击 `Save`
 ### 4.3 配置标注界面
 进入项目后，先点 `Settings` → `Labeling Interface` → `Code`：
 ```xml
 <View>
  <Image name="image" value="$image"/>
  <Choices name="label" toName="image" choice="single">
    <Choice value="cat"/>
    <Choice value="dog"/>
    <Choice value="bird"/>
  </Choices>
 </View>
 ```
 **逐行解释**：
 ```
 <View>            ← 整个标注界面的根标签
  <Image ...>     ← 显示图像（$image 是任务数据里的字段名）
  <Choices ...>   ← 单选/多选控件
    <Choice/>     ← 一个选项
 </View>
 ```
 **关键参数**：
 - `toName="image"`：告诉 Label Studio，这个控件是对上面 `Image` 控件的结果
 - `choice="single"`：单选（可选 `single-radio`、`multiple`）
 保存后点 `Label All Tasks` 就能看到标注界面。
 ### 4.4 导入数据
 在项目页 → `Settings` → `Data Import`：
 **方式 A：上传本地文件**
 ```
 1. 准备文件夹
   images/
     ├── cat_001.jpg
     ├── cat_002.jpg
     ├── dog_001.jpg
     └── bird_001.jpg
 2. 拖拽到上传区域
   或点击 Upload Files 选中文件夹
 ```
 **方式 B：上传 CSV / JSONL（推荐，标签稳定）**
 `tasks.csv`：
 ```csv
 image
 images/cat_001.jpg
 images/cat_002.jpg
 images/dog_001.jpg
 images/bird_001.jpg
 ```
 **方式 C：粘贴 URL**
 ```csv
 image
 https://example.com/cat_001.jpg
 https://example.com/dog_001.jpg
 ```
 上传完后点 `Save` → 任务列表里就会看到每一张图对应一行任务。
 ### 4.5 开始标注
 1. 点击 `Label All Tasks`
 2. 进入标注界面：
   - 上面是图片
   - 下面是三个单选按钮
 3. 选中正确类别
 4. 点击右下角 `Submit` 进入下一张
 5. 全部完成后回到项目页，可以看到完成进度
 ```
 ┌──────────────────────────────────────────────────┐
 │  Project: animal_classification                   │
 ├──────────────────────────────────────────────────┤
 │  Tasks:     10 total / 7 done / 3 skipped         │
 │  Progress:  ████████████░░░░░░  70%               │
 └──────────────────────────────────────────────────┘
 ```
 ### 4.6 导出数据
 项目页 → `Export`：
 - 格式选 `JSON`
 - 下载得到 `project-1-at-2024-05-20.json`
 导出内容示例：
 ```json
 [
  {
    "id": 1,
    "data": {"image": "images/cat_001.jpg"},
    "annotations": [{
      "result": [{
        "from_name": "label",
        "to_name": "image",
        "type": "choices",
        "value": {"choices": ["cat"]}
      }]
    }]
  }
 ]
 ```
 ---
 ## 5. 创建第二个项目：目标检测（边界框）
 ### 5.1 任务说明
 **任务**：对 10 张街景图进行目标检测，标出每张图中的 `person`、`car`、`bicycle`
 ### 5.2 项目配置 XML
 ```xml
 <View>
  <Image name="image" value="$image"/>
  <RectangleLabels name="label" toName="image" strokeWidth="3">
    <Label value="person" background="#FF0000"/>
    <Label value="car"    background="#00FF00"/>
    <Label value="bicycle" background="#0000FF"/>
  </RectangleLabels>
 </View>
 ```
 **新增标签**：
 - `<RectangleLabels>`：矩形框 + 标签（Label Studio 专门用于目标检测）
 - `<Label value="..." background="...">`：每个标签的颜色
 - `strokeWidth="3"`：边框线宽
 ### 5.3 标注操作
 进入标注界面后：
 ```
 ┌──────────────────────────────────────────────────┐
 │  [image]                                          │
 │  ┌────────┐                                       │
 │  │  人    │ ← 拖动鼠标画框                        │
 │  └────────┘                                       │
 │         ┌─────────┐                                │
 │         │   车    │                                │
 │         └─────────┘                                │
 ├──────────────────────────────────────────────────┤
 │  标签栏:                                          │
 │  [ person ]  [ car ]  [ bicycle ]                 │
 └──────────────────────────────────────────────────┘
 ```
 **操作步骤**：
 1. 选中上方标签（点击 person/car/bicycle 之一）
 2. 在图片上 **按住鼠标左键拖动**，画矩形框
 3. 松开后，框会自动带上刚才选中的标签
 4. 继续选下一个标签，再画下一个框
 5. 同一张图可以有多个框
 6. 标完后点 `Submit`
 ### 5.4 快捷键速查
 | 快捷键 | 功能 |
 |--------|------|
 | `Ctrl + Enter` | 提交当前任务 |
 | `H` | 切换显示已画框 |
 | `Ctrl + Z` | 撤销上一个框 |
 | `Delete` | 删除选中的框 |
 | 数字 `1-9` | 快速选择第 N 个标签 |
 | `+ / -` | 缩放图像 |
 | 滚轮 | 上下滚动 |
 ### 5.5 边界框标注规范
 **基本规则**：
 ```
 正确（紧贴目标）           错误（框太大）            错误（截断）
 ┌──────────┐               ┌────────────────┐        ┌──────────
 │ ▓▓▓▓▓▓▓ │               │ ▓▓▓▓▓▓▓▓▓▓▓▓▓ │        │ ▓▓▓▓▓▓▓ │
 │ ▓ 人 ▓▓ │               │ ▓  人  ▓▓▓▓▓▓ │        │ ▓ 人 ▓▓ │
 │ ▓▓▓▓▓▓▓ │               │ ▓▓▓▓▓▓▓▓▓▓▓▓▓ │        │ ▓▓▓▓▓▓▓ │
 └──────────┘               └────────────────┘        └──────────┘
 ```
 **多目标处理**：
 - 一张图有几个就标几个，每个独立画框
 - 互相重叠的目标也要分别标
 - 远处很小的目标可以标 "difficult" 标记
 **遮挡处理**：
 ```
 情况1：目标被部分遮挡
   → 标可见部分（标框框住能看到的人）
 情况2：目标被严重遮挡（< 20% 可见）
   → 建议不标（标记为非标注目标）
 情况3：多人重叠
   → 每个独立标，画框按可见边界
 ```
 ### 5.6 YOLO 格式导出
 项目页 → `Export` → 选 `YOLO`：
 下载得到压缩包，解压后结构：
 ```
 project-1-at-2024-05-20-yolo/
 ├── images/
 │   ├── street_001.jpg
 │   └── street_002.jpg
 ├── labels/
 │   ├── street_001.txt
 │   └── street_002.txt
 ├── classes.txt
 └── notes.json
 ```
 `classes.txt`（类别映射）：
 ```
 0: person
 1: car
 2: bicycle
 ```
 `street_001.txt`（一张图的标注）：
 ```
 # 格式: <class_id> <x_center> <y_center> <width> <height>
 # 所有值都是相对图片尺寸的归一化值 (0-1)
 0 0.35 0.45 0.18 0.55
 1 0.75 0.50 0.30 0.20
 ```
 **逐字段解释**：
 ```
 0      → 类别 ID（0=person）
 0.35   → 框中心点 x / 图片宽度
 0.45   → 框中心点 y / 图片高度
 0.18   → 框宽度 / 图片宽度
 0.55   → 框高度 / 图片高度
 ```
 ### 5.7 Pascal VOC 格式导出
 项目页 → `Export` → 选 `PascalVOC`：
 `street_001.xml`：
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
 <annotation>
    <filename>street_001.jpg</filename>
    <size>
        <width>1920</width>
        <height>1080</height>
        <depth>3</depth>
    </size>
    <object>
        <name>person</name>
        <bndbox>
            <xmin>134</xmin>
            <ymin>216</ymin>
            <xmax>478</xmax>
            <ymax>810</ymax>
        </bndbox>
    </object>
    <object>
        <name>car</name>
        <bndbox>
            <xmin>1100</xmin>
            <ymin>450</ymin>
            <xmax>1680</xmax>
        </bndbox>
    </object>
 </annotation>
 ```
 注意 VOC 用的是**绝对像素坐标**（xmin、ymin、xmax、ymax），而 YOLO 是**归一化坐标**（0-1）。
 ### 5.8 COCO 格式导出
 项目页 → `Export` → 选 `COCO`：
 `result.json`：
 ```json
 {
  "images": [
    {"id": 1, "file_name": "street_001.jpg", "width": 1920, "height": 1080},
    {"id": 2, "file_name": "street_002.jpg", "width": 1920, "height": 1080}
  ],
  "categories": [
    {"id": 0, "name": "person"},
    {"id": 1, "name": "car"},
    {"id": 2, "name": "bicycle"}
  ],
  "annotations": [
    {
      "id": 1, "image_id": 1, "category_id": 0,
      "bbox": [134, 216, 344, 594],
      "area": 204336,
      "iscrowd": 0
    }
  ]
 }
 ```
 注意 COCO 的 `bbox` 格式是 `[x_min, y_min, width, height]`（**前两个是左上角，后两个是宽高**），和 VOC 略有区别。
 ### 5.9 三种格式对比
 | 特性 | VOC | YOLO | COCO |
 |------|-----|------|------|
 | 文件类型 | 每个图一个 XML | 每个图一个 TXT | 所有图一个 JSON |
 | 坐标系 | 绝对像素 (xmin,ymin,xmax,ymax) | 归一化 0-1（中心点+宽高）| 绝对像素 (x,y,w,h) |
 | 多目标 | 一个 object 一对 bndbox | 一行一个目标 | 一个 annotation 一个目标 |
 | 适用框架 | Faster R-CNN, SSD | YOLO 系列 | Mask R-CNN, Detectron2 |
 | 优缺点 | 直观但文件多 | 紧凑、YOLO 专用 | 强大、适合大项目 |
 | 人类可读 | ⭐⭐⭐ | ⭐ | ⭐⭐ |
 **怎么选**：
 - 学 YOLO 模型 → 导 YOLO
 - 用 MMDetection / Detectron2 → 导 COCO
 - 通用、自己写训练脚本 → 导 VOC 或 JSON
 ---
 ## 6. 创建第三个项目：语义分割（多边形）
 ### 6.1 任务说明
 **任务**：对 5 张街景图做**像素级**语义分割，类别：road、building、sky、vegetation
 ### 6.2 项目配置 XML
 ```xml
 <View>
  <Image name="image" value="$image"/>
  <PolygonLabels name="label" toName="image" strokeWidth="2">
    <Label value="road"        background="#808080"/>
    <Label value="building"    background="#A52A2A"/>
    <Label value="sky"         background="#87CEEB"/>
    <Label value="vegetation"  background="#228B22"/>
  </PolygonLabels>
 </View>
 ```
 `<PolygonLabels>`：多边形 + 标签，专门用于语义分割。
 ### 6.3 标注操作
 1. 选中标签（点击 road / building / sky / vegetation）
 2. 在图像上**连续点击多个点**画出多边形
 3. **双击或按回车**结束当前多边形
 4. 一个类别画完，再选下一个类别继续
 5. 一张图可能有很多个多边形
 ```
 标注过程示意：
 点 1 ──→ 点 2
         │
         ↓
 点 4 ←── 点 3
 (双击结束)
 ┌──────────────────┐
 │                  │
 │   1────────2     │
 │   │        │     │
 │   │  区域  │     │
 │   │        │     │
 │   4────────3     │
 │                  │
 └──────────────────┘
 ```
 ### 6.4 分割标注注意事项
 | 情况 | 处理 |
 |------|------|
 | 两个区域紧贴 | 各画一个多边形，不要合成一个 |
 | 区域很小 | 至少 3 个点画出三角形 |
 | 形状不规则 | 多点描边，越细越准 |
 | 类别不确定 | 选最接近的，宁可错记也不要漏 |
 ### 6.5 导出多边形
 项目页 → `Export` → 选 `JSON`：
 ```json
 {
  "id": 1,
  "data": {"image": "street_001.jpg"},
  "annotations": [{
    "result": [{
      "from_name": "label",
      "to_name": "image",
      "type": "polygonlabels",
      "value": {
        "points": [[0.1, 0.8], [0.9, 0.8], [0.9, 1.0], [0.1, 1.0]],
        "polygonlabels": ["road"]
      }
    }]
  }]
 }
 ```
 `points` 数组里每个点都是 `[x, y]` 的归一化坐标（0-1），是按顺时针或逆时针排列的多边形顶点。
 > 💡 想转成 mask（像素级 PNG 图）？需要用 `label-studio-converter` 工具，详见 4-4 节。
 ---
 ## 7. 课堂演示：Python SDK
 ### 7.1 简介
 Label Studio 提供 `label-studio-sdk`，可以用 Python 编程式管理项目、查询任务、写入预标注。
 ### 7.2 安装
 ```bash
 pip install label-studio-sdk
 ```
 ### 7.3 常用代码
 ```python
 from label_studio_sdk import Client
 # 连接本地服务
 ls = Client(url='http://localhost:8080', api_key='YOUR_API_KEY')
 # 获取 API Key：
 # Label Studio → Settings → Account → Access Token
 # 列出所有项目
 projects = ls.list_projects()
 for p in projects:
    print(p.id, p.title)
 # 获取某个项目的任务
 project = ls.get_project(id=1)
 tasks = project.get_tasks()
 print(f"项目里有 {len(tasks)} 个任务")
 # 导入新任务
 project.import_tasks([
    {"image": "images/new_001.jpg"},
    {"image": "images/new_002.jpg"}
 ])
 # 导出标注
 project.export_tasks(export_type='JSON')
 ```
 > 这一节以了解为主，详细用法 4-4 节会展开。
 ---
 ## 8. 实战练习
 ### 8.1 任务一：图像分类（必做）
 **任务**：在 Label Studio 创建项目 `fruit_classification`
 **步骤**：
 1. 准备 10 张水果图片（apple、banana、orange）
 2. 启动 Label Studio，创建项目
 3. 配置 `<Choices>` 三分类界面
 4. 上传 10 张图
 5. 完成 10 张标注
 6. 导出 JSON 并截图
 ### 8.2 任务二：目标检测（必做）
 **任务**：创建项目 `vehicle_detection`
 **步骤**：
 1. 准备 10 张街景图
 2. 配置 `<RectangleLabels>` 目标检测界面
 3. 类别：person / car / bicycle / traffic_light
 4. 标完所有目标
 5. 导出 YOLO 格式
 6. 检查导出的 .txt 文件坐标是否正确
 ### 8.3 任务三（选做）：语义分割
 **任务**：创建项目 `scene_segmentation`
 **步骤**：
 1. 准备 3-5 张风景图
 2. 配置 `<PolygonLabels>` 分割界面
 3. 类别：sky / vegetation / road / building
 4. 画多边形
 5. 导出 JSON
 ### 8.4 标注自检清单
 ```
 图像分类：
 □ 类别选择是否正确
 □ 是否有漏标的任务
 □ 导出 JSON 是否完整
 目标检测：
 □ 边界框是否紧贴目标
 □ 是否每个目标都标了
 □ 框内类别是否正确
 □ 导出 YOLO 格式后坐标值是否在 0-1 之间
 □ classes.txt 是否齐全
 语义分割：
 □ 多边形顶点是否足够（至少 3 个）
 □ 类别判断是否准确
 □ 不同区域之间是否有遗漏
 ```
 ---
 ## 9. 本节知识小结
 ```
 ┌────────────────────────────────────────────────────────────┐
 │                4-2 图像标注实战（Label Studio）             │
 ├────────────────────────────────────────────────────────────┤
 │                                                            │
 │  📌 Label Studio 是多模态标注平台，一站式解决图像/文本/语音 │
 │                                                            │
 │  📌 安装：                                                  │
 │     pip install label-studio                               │
 │     label-studio                                           │
 │     浏览器访问 http://localhost:8080                       │
 │                                                            │
 │  📌 三种图像标注类型：                                       │
 │     分类      → <Choices>                                   │
 │     目标检测  → <RectangleLabels>                          │
 │     语义分割  → <PolygonLabels>                            │
 │                                                            │
 │  📌 三种导出格式：                                           │
 │     VOC    → XML，像素绝对坐标                              │
 │     YOLO   → TXT，归一化 0-1 坐标                          │
 │     COCO   → JSON，[x,y,w,h] 像素坐标                      │
 │                                                            │
 │  📌 标注规范：框要紧贴目标、不多不少                       │
 │                                                            │
 └────────────────────────────────────────────────────────────┘
 ```
 ---
 ## 课后任务
 1. 安装 Label Studio，截图证明能正常打开
 2. 完成"任务一"图像分类 10 张图
 3. 完成"任务二"目标检测 10 张图，导出 YOLO 格式
 4. （选做）完成"任务三"语义分割
 ---
 ## 下节预告
 下一节我们将学习 **4-3 文本标注与语音标注（Label Studio）**：
 - 文本分类、NER 命名实体识别
 - 意图识别与槽位标注
 - 语音转写 ASR
 - 说话人分离与音频分类