PaddleSeg EISeg 标注工具脚本实战指南:数据集转换、语义转实例标签与视频预处理
PaddleSeg EISeg 标注工具脚本实战指南:数据集转换、语义转实例标签与视频预处理
EISeg(Easy Interactive Segmentation)是 PaddleSeg 生态中的交互式标注工具,完成标注之后,如何把结果快速变成可训练的数据集,往往是决定工作流效率的关键。本文以 EISeg/docs/tools_en.md 为主线,系统讲解 EISeg/tool 目录下的五类配套脚本:PaddleX 数据集构建(eiseg2paddlex.py)、语义标签转实例标签(semantic2instance.py)、视频切帧(cut_video.py)、医学影像转视频(medical2video.py)与 LabelMe JSON 转 COCO(labelme-json2labelme-coco.py)。读完本文,你将掌握从标注产出到 PaddleX/PaddleSeg 训练数据、再到实例分割与医学 3D 标注的完整数据链路,并能直接复制命令投入实战。
一、工具脚本总览
所有工具脚本都位于仓库根目录下的 EISeg/tool 目录中:
| 脚本 | 核心用途 | 输入 | 输出 |
|---|---|---|---|
eiseg2paddlex.py |
把 EISeg 标注数据转换为 PaddleX 训练数据集 | 图像文件夹、标签文件夹 | JPEGImages、Annotations、labels.txt、train_list.txt、val_list.txt |
semantic2instance.py |
语义分割标签转实例分割标签 | 语义标签文件夹 | 带调色板的单通道实例标签 |
cut_video.py |
视频切帧成多段 mp4,防止标注时显存溢出 | 单个视频 | 按固定帧数切分的多段 mp4 |
medical2video.py |
医学影像(nii/dcm/mha/mhd/nrrd)转 mp4 视频 | 医学影像文件 | mp4 视频序列 |
labelme-json2labelme-coco.py |
LabelMe JSON 转 COCO 格式 | labelme json 文件夹 | annotations.json、JPEGImages、Visualization |
除上述五个标注工作流脚本外,目录中还包含 update_md5.py(为模型权重批量生成 .md5 校验文件,供下载校验使用)、pypi.sh(打包发布脚本)以及 translate/、ts/、translate.pro(界面多语言翻译相关文件),它们与标注数据转换链路无直接关系,本文不再展开。
二、用 eiseg2paddlex.py 构建 PaddleX 分割/检测数据集
2.1 背景与使用场景
EISeg 完成图像标注后,产出的是"图像文件夹 + 同名标签文件夹"的组织形式(标签默认保存在图像文件夹下的 label 子目录)。要直接送入 PaddleX 训练语义分割或检测模型,需要将数据重组为 PaddleX 标准格式。eiseg2paddlex.py 正是为此设计的一键转换脚本。
2.2 命令与参数
执行命令如下:
python eiseg2paddlex.py -d save_folder_path -o image_folder_path [-l label_folder_path] [-m mode -s split_rate]
各参数含义(与脚本中 argparse 定义一致,见 EISeg/tool/eiseg2paddlex.py):
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
-d, --save_path |
是 | 无 | PaddleX 格式数据的保存目录 |
-o, --image_path |
是 | 无 | 待转换的图像文件夹路径 |
-l, --label_path |
否 | image_folder_path/label |
标签文件夹路径,不传时默认取图像目录下的 label 子目录 |
-m, --mode |
否 | seg |
数据集类型:seg 表示语义分割,det 表示检测 |
-s, --split_rate |
否 | 0.9 |
训练集与验证集划分比例,即 90% 数据进入训练集、10% 进入验证集 |
2.3 转换流程的源码级拆解
从 Eiseg2paddlex() 的实现可以看到,转换分为三个关键阶段:
第一阶段:图像与标签搬运。 脚本会在保存目录下创建 JPEGImages 与 Annotations 两个子目录,遍历图像文件夹中所有扩展名匹配 FORMATS 列表(涵盖 .bmp、.jpg、.jpeg、.png、.webp、.tiff 乃至医学影像 .dcm 等二十余种格式)的文件,将其与对应的标签文件成对复制过去。标签路径的匹配规则与模式相关:
seg模式:优先寻找与图像同名的.png标签,若不存在则退回使用与图像同名的原扩展名文件(见 get_label_path);det模式:从标签目录下的VOC子目录中寻找同名.xml文件(检测标注为 VOC 格式的 XML)。
第二阶段:生成类别标签文件。 脚本会读取标签目录下的 autosave_label.txt(这是 EISeg 保存标注时自动导出的标签列表,对应 app.py 中的 exportLabelList 调用),在输出目录生成 labels.txt:首行固定写入 background(背景类,保证 PaddleX 的类别编号从背景开始),随后逐行追加标注中定义的类别名称。
第三阶段:生成数据列表。 脚本对复制后的图像列表做 random.shuffle 随机打乱,再按 split_rate 比例分别写入 train_list.txt 与 val_list.txt。每行内容为"相对路径 相对路径"的配对格式,例如:
JPEGImages/img_001.png Annotations/img_001.png
列表中的路径统一使用 / 分隔符(源码中对 \ 做了显式替换),保证在 Windows 与 Linux 下生成的列表文件均可被 PaddleX 直接解析。
2.4 实战示例
# 语义分割数据:图像在 mydata/img,标签在 mydata/img/label(默认路径),9:1 划分
python EISeg/tool/eiseg2paddlex.py -d paddlex_seg_data -o mydata/img
# 检测数据:标签为 VOC XML,位于 mydata/label/VOC
python EISeg/tool/eiseg2paddlex.py -d paddlex_det_data -o mydata/img -l mydata/label -m det
# 自定义划分比例:训练集 80%
python EISeg/tool/eiseg2paddlex.py -d paddlex_seg_data -o mydata/img -s 0.8
运行结束后,paddlex_seg_data 目录下的结构即为标准的 PaddleX 语义分割数据集:
paddlex_seg_data/
├── JPEGImages/ # 图像
├── Annotations/ # 标签
├── labels.txt # 类别列表(首行为 background)
├── train_list.txt # 训练列表
└── val_list.txt # 验证列表
三、semantic2instance.py:语义标签转实例标签
3.1 原理
语义分割标签中,同一类别的多个目标共享同一个像素值(取值范围为 [0, 255]),无法区分彼此。实例分割需要为每个独立目标分配唯一编号。semantic2instance.py 通过轮廓分析实现转换:对语义标签做连通域分析,每个独立连通区域被填充为递增的编号,最终输出带调色板的单通道 PNG 实例标签。
3.2 命令与参数
python semantic2instance.py -o label_path -d save_path
| 参数 | 必填 | 说明 |
|---|---|---|
-o, --label_path |
是 | 语义分割标签文件夹路径 |
-d, --save_path |
是 | 实例分割标签保存文件夹路径 |
3.3 算法细节
从 EISeg/tool/semantic2instance.py 的实现可以看到完整的转换逻辑:
- 轮廓提取:使用 OpenCV 的
cv2.findContours提取语义标签中所有轮廓,并通过cv2.contourArea按面积排序(_segMaskB2I); - 层级判定:利用轮廓的层级信息(
hierarchy)区分外轮廓与子轮廓——只有外轮廓(hierarchy[-1] == -1,即无父轮廓的顶层轮廓)被填充为实例编号,子轮廓(内部孔洞)被填充为 0,从而保证实例内部的中空区域不被误判为另一个实例; - 编号递增:每个外轮廓依次填充
1, 2, 3, ...,实现实例的逐一编号; - 调色板着色:通过
_savePalette(EISeg/tool/semantic2instance.py#L24-L31)为实例标签生成 256 色调色板,背景(值为 0)固定为黑色,其余实例随机着色,保存为标准 PNG(P模式 +putpalette),便于直接可视化查看。
脚本兼容不同 OpenCV 主版本:当 cv2.__version__ 以 "3" 开头时使用旧版返回值约定(results<a href="https://link.gitcode.com/i/8051c551a870c0916a075a181c732571" target="_blank">1] 为轮廓、results[2] 为层级),否则使用新版约定(results[0]、results[1]),见 [EISeg/tool/semantic2instance.py#L38-L40。
# 将语义标签 mydata/label 下所有 PNG 转为实例标签,保存至 mydata/instance_label
python EISeg/tool/semantic2instance.py -o mydata/label -d mydata/instance_label
四、cut_video.py:视频切分以缓解标注显存压力
4.1 使用背景
视频标注(如 PP-Tracking 流程)的计算量巨大,整段视频一次性加载容易导致显存不足。官方建议将视频切分为固定帧数(如 100 帧)的小段,逐段标注。
4.2 用法与参数
脚本位于 EISeg/tool/cut_video.py,它没有命令行参数,需直接修改脚本底部的三个变量后运行:
# EISeg/tool/cut_video.py 底部 __main__ 入口
video_path = '/PATH/TO/VIDEO' # 输入视频路径
save_path = "/PATH/TO/SAVE" # 切分结果保存目录
cut_length = 50 # 每段包含的帧数
python cut_video.py
4.3 实现要点
脚本通过 cv2.VideoCapture 读取视频的 FPS(get(5))、总帧数(get(7))与分辨率(get(3)/get(4)),随后用 cv2.VideoWriter 配合 mp4v 编码逐帧写入。切分逻辑为:当帧序号 frame_index 恰好是 cut_length 的整数倍时,开启一个新的输出文件(文件名为 帧序号整除cut_length 的结果,如 0.mp4、1.mp4、2.mp4……),从而把长视频均匀切分为多段等长短视频(见 video_cut)。
五、medical2video.py:医学切片转视频,支撑 3D 医学标注
5.1 背景
EISeg 的 3D 医学标注基于视频标注算法实现:先把医学影像的各个切片按序组织成 mp4 视频,再逐帧进行标注。因此医学影像数据在标注前必须先完成格式转换。
5.2 支持的医学格式与处理流程
脚本 EISeg/tool/medical2video.py 中的 load_medical_data 支持以下输入(EISeg/tool/medical2video.py#L10-L50):
.nii、.nii.gz、.dcm:通过 SimpleITK 读取,并统一用sitk.DICOMOrient将方向规整为 SLP(Superior-Left-Posterior);对 4D 数据按最后一维逐帧抽取;.mha、.mhd、nrrd:同样统一朝向 SLP 后转 numpy 数组;.raw:脚本明确拒绝,提示应提供对应的.mhd文件而非原始.raw文件;- 其他扩展名:抛出
NotImplementedError。
转换阶段由 array_to_video 完成(EISeg/tool/medical2video.py#L64-L75):每一切片经 normalize 做窗宽窗位(默认 ww=400, wc=0,即窗宽 400、窗位 0)裁剪与线性映射到 0-255 灰度,再通过 cv2.cvtColor(COLOR_GRAY2BGR) 转为三通道后写入 mp4(mp4v 编码,默认 FPS=15)。
5.3 使用方法
与 cut_video.py 类似,脚本通过修改 __main__ 中的路径变量运行:
# EISeg/tool/medical2video.py 底部 __main__ 入口
path = "/PATH/TO/nii_or_dcm_FILE"
video_path = "/PATH/TO/SAVE.mp4"
python medical2video.py
转换完成后,即可在 EISeg 中按视频标注流程对医学影像切片进行逐帧标注。
六、labelme-json2labelme-coco.py:LabelMe JSON 转 COCO
6.1 背景:EISeg 的 LabelMe 兼容输出
在 EISeg 中,如果勾选了"保存为 labelme 的 JSON 格式"选项(对应 app.py 中的 json_labelme 保存开关),保存标注时会在 label 文件夹下额外生成一个 labelme 子目录,其中包含与 LabelMe 完全同构的 JSON 文件(version、flags、shapes、imagePath、imageData、imageHeight、imageWidth 字段,见 app.py),同时目录下还会生成一份 labels.txt 类别列表。labelme-json2labelme-coco.py 负责把这批 LabelMe 格式的 JSON 统一转换为 COCO 格式。
6.2 命令与参数
python labelme-json2labelme-coco.py label_path save_path --labels txt_path
| 参数 | 必填 | 说明 |
|---|---|---|
label_path(位置参数) |
是 | 存放 LabelMe 格式 JSON 的文件夹 |
save_path(位置参数) |
是 | COCO 格式数据输出目录 |
--labels |
是 | labels.txt 类别文件路径 |
官方示例:
python labelme-json2labelme-coco.py mydata/label/labelme/ mydata/label/labelme/output --labels mydata/label/labelme/labels.txt
6.3 转换产物与实现细节
转换完成后,save_path 目录下生成与 LabelMe 官方工具一致的三个部分(main()):
annotations.json:COCO 格式标注文件,包含info、licenses、images、annotations、categories五个标准字段;JPEGImages/:从 JSON 内嵌的imageData(base64)解码出的原始图像,统一转存为.jpg;Visualization/:实例级可视化预览图(可通过--noviz参数关闭可视化生成,见 EISeg/tool/labelme-json2labelme-coco.py#L315)。
实现上的几个关键点:
- 类别编号:
categories的id从 0 开始递增,且脚本约定labels.txt首行为__ignore__(忽略类,编号 -1,不参与训练),其余行按顺序编号(EISeg/tool/labelme-json2labelme-coco.py#L352-L364); - 形状转掩膜:
shape_to_mask支持 polygon(多边形)、circle(圆)、rectangle(矩形)、line/linestrip(线)与 point(点)等 LabelMe 形状类型;矩形与圆形会被离散化为多边形点集写入 COCO 的segmentation字段(EISeg/tool/labelme-json2labelme-coco.py#L108-L139); - 实例聚合:以
(label, group_id)为实例键聚合同一实例的多个形状,通过pycocotools.mask计算area与bbox(EISeg/tool/labelme-json2labelme-coco.py#L428-L447)——因此运行前需要确保已安装pycocotools(脚本会在缺失时提示pip install pycocotools); - 输出目录保护:若输出目录已存在,脚本会直接退出并提示,避免覆盖既有数据(EISeg/tool/labelme-json2labelme-coco.py#L318-L320)。
七、完整数据链路小结
把五个脚本串联起来,就是一条从标注到训练的完整数据链路:
- 单张图像标注:在 EISeg 中完成交互式标注,产出语义标签 +
autosave_label.txt;如需后续做实例分割,可同时开启 LabelMe JSON 保存; - 语义分割训练:直接用
eiseg2paddlex.py生成 PaddleX 语义分割数据集(seg模式); - 检测训练:若标注的是检测框,用
eiseg2paddlex.py的det模式生成 VOC XML 布局的 PaddleX 检测数据集; - 实例分割训练:先用
semantic2instance.py把语义标签转为实例标签;或把 LabelMe JSON 经labelme-json2labelme-coco.py转为 COCO 格式; - 视频/3D 医学标注:长视频先用
cut_video.py切分,医学影像先用medical2video.py转为 mp4,再回到 EISeg 逐段标注。
每个脚本都保持"输入输出路径即参数"的极简设计,可以在命令行中直接调用,也可以嵌入到自定义的数据处理 pipeline 中批量执行。所有脚本均在 EISeg/tool 目录下,结合 EISeg/docs/tools.md(简体中文版)与 EISeg/docs/tools_en.md(英文版)即可快速上手。