PaddleX 实例分割数据集标注全指南:Labelme 标注流程与 COCO 数据格式深度解析

原创2026-10-05 20:25:371,614 阅读
文章标签:人工智能深度学习机器学习计算机视觉OCR语音模型推理服务本地部署多模态

PaddleX 实例分割数据集标注全指南:Labelme 标注流程与 COCO 数据格式深度解析

导读

实例分割任务要求为图像中每个目标实例输出像素级掩模(mask)与类别,而这一切的起点是一份高质量、格式规范的标注数据。本文围绕 PaddleX 仓库中的 实例分割数据标注教程,系统讲解如何借助开源图形化标注工具 Labelme 完成实例分割数据集的制作,并深入解析 PaddleX 实例分割模块所要求的 COCOInstSegDataset 数据组织规范与 COCO 标注格式细节。读完后,你将能够独立完成从原始图片准备、多边形绘制标注,到生成标准 Labelme 数据集、再到通过 PaddleX 数据校验与 LabelMe→COCO 自动格式转换的完整闭环,为后续模型训练与产线集成打下扎实的数据基础。

一、实例分割数据标注的整体思路

PaddleX 实例分割模块的训练、评估与推理统一基于 COCO 格式 的数据集(仓库中数据集类型名称为 COCOInstSegDataset)。官方推荐的标注工具是 Labelme——一个使用 Python 编写、带图形界面的开源图像标注软件,可同时胜任图像分类、目标检测、图像分割等任务的数据标注。在实例分割标注场景中,Labelme 以多边形(Polygon)描绘每个目标实例的边界,并将标注结果保存为 JSON 文件。

整个数据准备流程可以概括为:

  1. 用 Labelme 在每张图片上为每个目标实例绘制多边形并指定类别;
  2. 整理目录与标注清单,得到标准 Labelme 格式数据集;
  3. 通过 PaddleX 的数据校验/格式转换能力,将 Labelme 格式转换为 PaddleX 训练所需的 COCO 格式(instance_train.json / instance_val.json);
  4. 通过数据校验(check_dataset)后即可进入模型训练环节。

二、标注数据示例:水果实例分割数据集

教程中给出的示例是一个 水果实例分割数据集,涵盖五种不同的水果,图片包含目标不同角度的拍摄照片。这类"少量类别、实例边界清晰"的数据集非常适合作为上手实例分割标注的练习素材,也便于在标注完成后快速验证格式转换、数据校验与模型训练的全链路。

在开始标注之前,你需要确认自己的标注目标与类别集合。PaddleX 的数据校验与统计分析均以类别为单位进行统计,因此类别清单(label.txt)的设计直接决定后续模型输出类别,应在标注前一次性规划完整。

三、Labelme 标注工具介绍与安装

3.1 工具简介

Labelme 是 Python 语言编写、带有图形界面的图像标注软件,可用于图像分类、目标检测、图像分割等任务。在实例分割的标注任务中,标签存储为 JSON 文件。其标注产物(JSON 文件)中记录了图片路径、图片尺寸、每个形状(shape)的类型与多边形角点坐标、类别名称等关键信息,后续 PaddleX 的格式转换模块正是解析这些字段来重建 COCO 标注。

3.2 安装步骤

为避免环境冲突,建议在 conda 环境下安装 Labelme:

conda create -n labelme python=3.10
conda activate labelme
pip install pyqt5
pip install labelme

其中 pyqt5 用于提供图形界面运行所需的 Qt 绑定,labelme 为标注工具本体。完成安装后即可通过 labelme 命令启动图形界面。

四、Labelme 标注全过程实操

4.1 准备待标注数据

在开始标注前,需要先搭建数据集的目录骨架,并准备类别清单:

  • 创建数据集根目录,如 fruit;
  • 在 fruit 中创建 images 目录(必须命名为 images),并将待标注图片存储在该目录下;
  • 在 fruit 文件夹中创建类别标签文件 label.txt,按行写入待标注数据集的全部类别。以水果实例分割数据集为例,label.txt 内容大致为每行一个水果类别名称。

这一目录组织方式与后续 Labelme 数据集→COCO 格式转换的约定强相关:images 目录与 label.txt 是 PaddleX 识别标准 Labelme 数据集的关键标志。

4.2 启动 Labelme

终端进入数据集根目录,并启动 labelme 标注工具:

cd path/to/fruit
labelme images --labels label.txt --nodata --autosave --output annotations

各命令行参数含义如下:

参数 含义
images 待标注图片所在目录(即 fruit/images)
--labels label.txt 指定类别标签文件路径,标注时可直接从预置类别列表中选择
--nodata 停止将图像数据存储到 JSON 文件,使标注文件更精简
--autosave 自动存储,标注完成后无需手动点击保存按钮
--output annotations 标注 JSON 文件输出目录

4.3 开始图片标注

启动 labelme 后的标注操作步骤如下:

  1. 点击菜单 Edit 选择标注类型,选择 Create Polygons;
  2. 在图片上沿目标实例边界逐点点击,创建多边形以描绘分割区域边界;
  3. 多边形闭合后,再次点击以选择该分割区域所属类别;
  4. 标注好后点击存储(若启动时未指定 output 字段,会在第一次存储时提示选择存储路径;若指定了 autosave 字段使用自动保存,则无需点击存储按钮);
  5. 点击 Next Image 进行下一张图片的标注。

重复上述过程,直至 images 目录下的所有图片都完成标注。需要注意:同一张图片中同一类别的多个实例,需要分别绘制各自独立的多边形——这正是"实例分割"与"语义分割"在标注层面的核心区别,每个多边形在转换后将对应 COCO 标注中的一条独立 annotation 记录。

4.4 整理标准 Labelme 格式数据集

完成全部图片的标注后,annotations 目录下会生成与图片一一对应的 JSON 标注文件。接下来需要整理标注清单并确认最终目录结构:

  • 在数据集根目录创建 train_anno_list.txt 和 val_anno_list.txt 两个文本文件;
  • 将 annotations 目录下的全部 json 文件路径按一定比例分别写入 train_anno_list.txt 和 val_anno_list.txt;
  • 也可以将全部标注路径写入 train_anno_list.txt,同时创建一个空的 val_anno_list.txt 文件,待上传零代码平台后使用数据划分功能重新划分。

整理得到的最终目录结构如下:

fruit
├── images                      # 待标注/已标注图片目录(名称不可改变)
│   ├── 01.jpg
│   └── ...
├── label.txt                   # 类别标签文件,每行一个类别
├── annotations                 # Labelme 标注 JSON 输出目录
│   ├── 01.json
│   └── ...
├── train_anno_list.txt         # 训练集标注清单(每行一个 json 文件路径)
└── val_anno_list.txt           # 验证集标注清单(每行一个 json 文件路径)

最后将 fruit 目录打包压缩为 .tar 或 .zip 格式压缩包,即可得到水果实例分割标准 Labelme 格式数据集,可用于上传零代码平台或通过 PaddleX 命令行进行格式转换与训练。

五、PaddleX 实例分割数据集格式:COCOInstSegDataset

5.1 目录结构规范

PaddleX 针对实例分割任务定义的数据集名称为 COCOInstSegDataset,组织结构和标注格式如下:

dataset_dir                  # 数据集根目录,目录名称可以改变
├── annotations              # 标注文件的保存目录,目录名称不可改变
│   ├── instance_train.json  # 训练集标注文件,文件名称不可改变,采用COCO标注格式
│   └── instance_val.json    # 验证集标注文件,文件名称不可改变,采用COCO标注格式
└── images                   # 图像的保存目录,目录名称不可改变

标注文件采用 COCO 格式。官方提供了标准示例数据集(COCO 格式的 instance_seg_coco_examples.tar 与 Labelme 格式的 instance_seg_labelme_examples.tar),建议严格参照示例数据集的文件命名和组织方式来准备自己的数据。

5.2 COCO 标注格式细节

实例分割数据要求采用 COCO 数据格式,标注出数据集中每张图像各个目标区域的像素边界和类别:

  • 采用 [x1, y1, x2, y2, ..., xn, yn] 表示物体的多边形边界(segmentation),其中 (xn, yn) 表示多边形各个角点坐标;
  • 标注信息存放到 annotations 目录下的 json 文件中,训练集 instance_train.json 和验证集 instance_val.json 分开存放。

从仓库源码看,PaddleX 在 check_dataset.py 中直接使用 pycocotools 读取 annotations/instance_train.json 与 annotations/instance_val.json:这两个文件必须同时存在,否则会抛出 DatasetFileNotFoundError;随后通过 COCO(file_list) 加载标注、统计 getCatIds() 得到类别数,并抽样渲染"检测框 + 掩模"可视化图。这从实现层面印证了目录与文件命名的强约束。

5.3 标注注意事项

  • 如果你有一批未标注数据,官方推荐使用 LabelMe 进行数据标注。对于使用 LabelMe 标注的数据集,PaddleX 产线支持进行数据格式转换(详见下一节);
  • 为确保格式转换顺利完成,请严格遵循示例数据集的文件命名和组织方式(images 目录、label.txt、train_anno_list.txt/val_anno_list.txt、annotations 目录);
  • 若你使用的是 PaddleX 2.x 版本的实例分割数据集(VOC 格式),请参考 实例分割模块使用教程 中对应的格式转换部分,将 VOC 格式数据集转换为 COCO 数据集。

六、LabelMe 标注数据到 COCO 格式的自动转换

6.1 转换原理与源码实现

PaddleX 实例分割模块的数据检查器(COCOInstSegDatasetChecker,见 dataset_checker/init.py)内置了 LabelMe→COCO 的转换能力,其核心实现在 convert_dataset.py 中。从源码结构看,转换逻辑可以拆解为三个环节:

(1)源格式校验(check_src_dataset):目前仅支持 LabelMe 格式作为源格式。转换器会逐一核对 train_anno_list.txt 与 val_anno_list.txt 中列出的每个 JSON 标注文件是否真实存在,缺失任一文件都会抛出 ConvertFailedError。

(2)LabelMe JSON → COCO 标注(labelme2coco):逐条读取标注清单中的 JSON 文件,并完成字段映射:

  • 通过 Indexer 为图片与类别分配全局唯一的 id,生成 COCO 的 images 与 categories 数组;
  • 仅接受 shape_type == "polygon" 的形状,将 points 展平为 [x1, y1, x2, y2, ..., xn, yn] 形式作为 segmentation 字段——与原文档中的 COCO 格式约定完全一致;
  • 调用 points_to_mask 将多边形栅格化为掩模,再借助 pycocotools.mask 计算 area(面积)与 bbox(外接框);
  • 最终组装 annotations 数组(含 image_id、bbox、segmentation、category_id、id、iscrowd=0、area、ignore=0),写入 annotations/instance_train.json 或 instance_val.json。

(3)训练/验证清单兜底划分(split_anno_list):如果待转换数据只有 train_anno_list.txt 而没有 val_anno_list.txt,转换器会自动将原清单随机打乱后按 80% / 20% 划分为训练与验证两份,并将原始 train_anno_list.txt 重命名为 train_anno_list.txt.bak 备份。

6.2 通过 PaddleX 命令行执行转换

转换操作挂在数据校验(check_dataset)流程中,通过修改配置文件或追加命令行参数开启。首先下载 LabelMe 格式示例数据集并解压:

cd /path/to/paddlex
wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/instance_seg_labelme_examples.tar -P ./dataset
tar -xf ./dataset/instance_seg_labelme_examples.tar -C ./dataset/

修改配置文件 Mask-RT-DETR-L.yaml 中 CheckDataset 下的 convert 字段:

CheckDataset:
  convert:
    enable: True          # 开启数据集格式转换
    src_dataset_type: LabelMe   # 源数据集格式

随后执行:

python main.py -c paddlex/configs/modules/instance_segmentation/Mask-RT-DETR-L.yaml \
    -o Global.mode=check_dataset \
    -o Global.dataset_dir=./dataset/instance_seg_labelme_examples

数据转换执行之后,原有标注文件会被在原路径下重命名为 xxx.bak。以上参数同样支持通过追加命令行参数的方式设置,无需修改配置文件:

python main.py -c paddlex/configs/modules/instance_segmentation/Mask-RT-DETR-L.yaml \
    -o Global.mode=check_dataset \
    -o Global.dataset_dir=./dataset/instance_seg_labelme_examples \
    -o CheckDataset.convert.enable=True \
    -o CheckDataset.convert.src_dataset_type=LabelMe

6.3 训练/验证数据集比例重划分

如果已经拥有 COCO 格式的 instance_train.json / instance_val.json,但希望重新划分训练验证比例,可通过 CheckDataset.split 字段实现:

CheckDataset:
  split:
    enable: True
    train_percent: 90    # 训练集占比,0-100 之间的整数
    val_percent: 10      # 验证集占比,需与 train_percent 之和为 100

随后执行与格式转换相同的 check_dataset 命令即可完成划分。划分过程(见 split_dataset.py 的 split_dataset 函数)会将两个标注文件中的全部图片记录合并、随机打乱,再按比例重新组装写入 annotations/instance_train.json 与 annotations/instance_val.json,同时把原文件备份为 *.bak。源码中还对参数做了强校验:train_percent + val_percent 必须等于 100,且两者都必须大于 0。

对应的命令行写法:

python main.py -c paddlex/configs/modules/instance_segmentation/Mask-RT-DETR-L.yaml \
    -o Global.mode=check_dataset \
    -o Global.dataset_dir=./dataset/instance_seg_labelme_examples \
    -o CheckDataset.split.enable=True \
    -o CheckDataset.split.train_percent=90 \
    -o CheckDataset.split.val_percent=10

七、数据校验与统计分析:训练前的质量关卡

在完成标注与格式转换后,PaddleX 要求只有通过数据校验的数据才可以进行模型训练。对实例分割模块执行数据校验的命令为:

python main.py -c paddlex/configs/modules/instance_segmentation/Mask-RT-DETR-L.yaml \
    -o Global.mode=check_dataset \
    -o Global.dataset_dir=./dataset/instance_seg_coco_examples

校验过程(源码见 check_dataset.py)会依次完成:目录存在性检查 → 训练/验证标注文件存在性检查 → 通过 pycocotools 加载并统计类别数与样本数 → 抽样渲染带检测框与掩模的可视化样本图。统计分析部分(见 analyse_dataset.py)还会统计训练集与验证集中每个类别的实例数量,并绘制样本分布直方图 histogram.png,帮助判断类别是否均衡。

命令运行成功后,日志中会打印 Check dataset passed ! 信息,校验结果文件保存在 ./output/check_dataset_result.json,可视化产出保存在 ./output/check_dataset 目录下。校验结果中 check_pass 为 True 表示数据集格式符合要求,attributes 字段给出了类别数(num_classes)、训练集样本数(train_samples)、验证集样本数(val_samples)及抽样可视化图片的相对路径列表。

八、PaddleX 2.x 旧版 VOC 数据集的升级路径

如果你的标注数据来自 PaddleX 2.x 时代的实例分割模块(当时采用 VOC 风格数据集),则需要先完成 VOC→COCO 的格式迁移,再接入 PaddleX 3.x 的训练流程。这一部分请参照 实例分割模块使用教程 中的格式转换章节,将 VOC 格式数据集转换为符合 COCOInstSegDataset 规范的 instance_train.json / instance_val.json 结构后,即可与本文所述的数据校验、模型训练流程无缝衔接。

九、从标注到训练:数据准备的完整链路小结

以 PaddleX 仓库内的工具链为依托,一份可用于实例分割模型训练的数据集通常需要经历以下阶段:

阶段 工具/环节 关键产物
图片与类别准备 手工整理 images 目录、label.txt
实例边界标注 Labelme(Create Polygons) annotations/*.json
标注清单整理 手工/脚本 train_anno_list.txt、val_anno_list.txt
格式转换 PaddleX check_dataset + CheckDataset.convert annotations/instance_train.json、annotations/instance_val.json
比例重划分 PaddleX check_dataset + CheckDataset.split 重新切分的 COCO 标注文件
质量校验 PaddleX check_dataset check_dataset_result.json、可视化样本、类别分布直方图
模型训练 python main.py -c ...yaml -o Global.mode=train 训练权重与评估指标

后续若要继续深入,可以进一步参考 PaddleX 通用模型配置文件参数说明 了解 Global、Train、Evaluate、Predict 各字段的完整语义,或查阅 通用实例分割产线教程 将训练好的模型快速集成进产线。数据集标注质量直接决定实例分割模型的精度上限,掌握 Labelme 标注细节与 COCOInstSegDataset 格式规范,是使用 PaddleX 高效完成实例分割开发的第一步。

登录后查看全文
PaddleX