PaddleX 实例分割数据集标注全指南:Labelme 标注流程与 COCO 数据格式深度解析
PaddleX 实例分割数据集标注全指南:Labelme 标注流程与 COCO 数据格式深度解析
导读
实例分割任务要求为图像中每个目标实例输出像素级掩模(mask)与类别,而这一切的起点是一份高质量、格式规范的标注数据。本文围绕 PaddleX 仓库中的 实例分割数据标注教程,系统讲解如何借助开源图形化标注工具 Labelme 完成实例分割数据集的制作,并深入解析 PaddleX 实例分割模块所要求的 COCOInstSegDataset 数据组织规范与 COCO 标注格式细节。读完后,你将能够独立完成从原始图片准备、多边形绘制标注,到生成标准 Labelme 数据集、再到通过 PaddleX 数据校验与 LabelMe→COCO 自动格式转换的完整闭环,为后续模型训练与产线集成打下扎实的数据基础。
一、实例分割数据标注的整体思路
PaddleX 实例分割模块的训练、评估与推理统一基于 COCO 格式 的数据集(仓库中数据集类型名称为 COCOInstSegDataset)。官方推荐的标注工具是 Labelme——一个使用 Python 编写、带图形界面的开源图像标注软件,可同时胜任图像分类、目标检测、图像分割等任务的数据标注。在实例分割标注场景中,Labelme 以多边形(Polygon)描绘每个目标实例的边界,并将标注结果保存为 JSON 文件。
整个数据准备流程可以概括为:
- 用 Labelme 在每张图片上为每个目标实例绘制多边形并指定类别;
- 整理目录与标注清单,得到标准 Labelme 格式数据集;
- 通过 PaddleX 的数据校验/格式转换能力,将 Labelme 格式转换为 PaddleX 训练所需的 COCO 格式(
instance_train.json/instance_val.json); - 通过数据校验(
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 后的标注操作步骤如下:
- 点击菜单
Edit选择标注类型,选择Create Polygons; - 在图片上沿目标实例边界逐点点击,创建多边形以描绘分割区域边界;
- 多边形闭合后,再次点击以选择该分割区域所属类别;
- 标注好后点击存储(若启动时未指定
output字段,会在第一次存储时提示选择存储路径;若指定了autosave字段使用自动保存,则无需点击存储按钮); - 点击
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 高效完成实例分割开发的第一步。