PaddleSeg EISeg 标注工具脚本实战指南:数据集转换、语义转实例标签与视频预处理

原创2026-09-24 12:04:331,834 阅读
文章标签:计算机视觉深度学习人工智能图像处理预训练模型量化模型蒸馏模型优化数据标注机器学习

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 的实现可以看到完整的转换逻辑:

  1. 轮廓提取:使用 OpenCV 的 cv2.findContours 提取语义标签中所有轮廓,并通过 cv2.contourArea 按面积排序(_segMaskB2I);
  2. 层级判定:利用轮廓的层级信息(hierarchy)区分外轮廓与子轮廓——只有外轮廓(hierarchy[-1] == -1,即无父轮廓的顶层轮廓)被填充为实例编号,子轮廓(内部孔洞)被填充为 0,从而保证实例内部的中空区域不被误判为另一个实例;
  3. 编号递增:每个外轮廓依次填充 1, 2, 3, ...,实现实例的逐一编号;
  4. 调色板着色:通过 _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)。

实现上的几个关键点:

  1. 类别编号:categories 的 id 从 0 开始递增,且脚本约定 labels.txt 首行为 __ignore__(忽略类,编号 -1,不参与训练),其余行按顺序编号(EISeg/tool/labelme-json2labelme-coco.py#L352-L364);
  2. 形状转掩膜:shape_to_mask 支持 polygon(多边形)、circle(圆)、rectangle(矩形)、line/linestrip(线)与 point(点)等 LabelMe 形状类型;矩形与圆形会被离散化为多边形点集写入 COCO 的 segmentation 字段(EISeg/tool/labelme-json2labelme-coco.py#L108-L139);
  3. 实例聚合:以 (label, group_id) 为实例键聚合同一实例的多个形状,通过 pycocotools.mask 计算 area 与 bbox(EISeg/tool/labelme-json2labelme-coco.py#L428-L447)——因此运行前需要确保已安装 pycocotools(脚本会在缺失时提示 pip install pycocotools);
  4. 输出目录保护:若输出目录已存在,脚本会直接退出并提示,避免覆盖既有数据(EISeg/tool/labelme-json2labelme-coco.py#L318-L320)。

七、完整数据链路小结

把五个脚本串联起来,就是一条从标注到训练的完整数据链路:

  1. 单张图像标注:在 EISeg 中完成交互式标注,产出语义标签 + autosave_label.txt;如需后续做实例分割,可同时开启 LabelMe JSON 保存;
  2. 语义分割训练:直接用 eiseg2paddlex.py 生成 PaddleX 语义分割数据集(seg 模式);
  3. 检测训练:若标注的是检测框,用 eiseg2paddlex.py 的 det 模式生成 VOC XML 布局的 PaddleX 检测数据集;
  4. 实例分割训练:先用 semantic2instance.py 把语义标签转为实例标签;或把 LabelMe JSON 经 labelme-json2labelme-coco.py 转为 COCO 格式;
  5. 视频/3D 医学标注:长视频先用 cut_video.py 切分,医学影像先用 medical2video.py 转为 mp4,再回到 EISeg 逐段标注。

每个脚本都保持"输入输出路径即参数"的极简设计,可以在命令行中直接调用,也可以嵌入到自定义的数据处理 pipeline 中批量执行。所有脚本均在 EISeg/tool 目录下,结合 EISeg/docs/tools.md(简体中文版)与 EISeg/docs/tools_en.md(英文版)即可快速上手。

登录后查看全文
PaddleSeg