EISeg 数据处理工具脚本全指南:从交互式标注到 PaddleX / 实例分割 / COCO 训练数据集

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

EISeg 数据处理工具脚本全指南:从交互式标注到 PaddleX / 实例分割 / COCO 训练数据集

EISeg(Efficient Interactive Segmentation)是飞桨生态下的高效交互式分割标注工具,完成图像标注只是第一步,将标注结果转换成可直接用于模型训练的数据集格式,才是打通"数据标注 → 模型训练"全流程的关键一环。本文基于 EISeg/docs/tools.md 的说明,结合 EISeg/tool 目录下各脚本的真实实现,系统讲解 EISeg 配套的 5 个数据处理脚本:如何把 EISeg 标注结果一键转成 PaddleX 语义分割/目标检测数据集、如何把语义标签转成实例标签、如何切分视频防止显存不足、如何把医疗切片转成视频、以及如何把 labelme 格式 JSON 转成 COCO 格式。读完本文,你将掌握从标注产物到各类训练数据格式的完整转换方法,并理解每个脚本的底层实现原理。

一、工具总览:EISeg/tool 目录下的脚本家族

所有工具脚本均位于仓库的 EISeg/tool 目录下,共包含 5 个核心数据处理脚本(另有 translate、ts、pypi.sh、update_md5.py 等翻译与发布辅助脚本,不属于本文范围):

脚本 功能 适用场景
eiseg2paddlex.py 将 EISeg 标注数据转换为 PaddleX 语义分割(seg)或目标检测(det)训练格式 网络爬取图像标注完成后,快速构建 PaddleX 数据集
semantic2instance.py 将语义分割标签(0/255 二值)转为实例分割标签(单通道调色板图像) 实例分割任务数据准备
cut_video.py 按帧数将长视频切分为多个短视频片段 视频标注前的数据预处理
medical2video.py 将 NIfTI/DICOM/MHA 等医疗切片数据转为 mp4 视频 3D 医疗图像标注前的数据预处理
labelme-json2labelme-coco.py 将 labelme 格式 JSON 标签转换为 COCO 格式 实例分割 / 检测数据集的 COCO 格式转换

这些脚本大多以 argparse 解析命令行参数,可直接以 python xxx.py 方式运行;部分脚本(如 cut_video.py、medical2video.py)则采用在主函数中直接改写路径变量的方式,使用时需要修改脚本内的路径常量。

二、eiseg2paddlex.py:EISeg 标注数据一键转 PaddleX 训练格式

2.1 适用场景与调用方式

当使用 EISeg 对(例如网络爬取的)图像完成标注后,通过 EISeg/tool/eiseg2paddlex.py 可以快速将数据转换为 PaddleX 的训练格式,脚本实现参考了 PaddleX 的数据准备文档(语义分割数据要求 JPEGImages + Annotations 目录与 train_list.txt / val_list.txt 列表文件的结构)。

python eiseg2paddlex.py -d save_folder_path -o image_folder_path [-l label_folder_path] [-m mode -s split_rate]

2.2 命令行参数说明

参数 必填 默认值 说明
-d / --save_path 是 无 PaddleX 数据的保存路径,脚本会在此创建 JPEGImages、Annotations 等子目录
-o / --image_path 是 无 图像所在文件夹路径
-l / --label_path 否 image_folder_path/label 标签文件夹路径;不填时自动定位到图像目录下的 label 子目录
-m / --mode 否 seg 数据集类型:seg 为语义分割,det 为目标检测
-s / --split_rate 否 0.9 训练集与验证集划分比例,即前 90% 数据作为训练集

2.3 源码实现细节:转换流程深度解析

从 eiseg2paddlex.py 源码 可以看到,转换过程分为三步:

第一步:拷贝图像与标签。 脚本定义了 FORMATS 列表(.bmp、.cur、.gif、.icns、.ico、.jpeg、.jpg、.pbm、.pgm、.png、.ppm、.svg、.svgz、.tga、.tif、.tiff、.wbmp、.webp、.xpm、.dcm),仅处理扩展名命中该列表的图像。标签路径的解析逻辑(get_label_path 函数)体现了 seg 与 det 两种模式的差异:

  • seg 模式:先尝试 label_folder/同名.png,若该路径不存在则回退为与图像同名的原文件(兼容灰度/伪彩色标签直接改名的情况);
  • det 模式:从 label_folder/VOC/同名.xml 读取检测标注(与 VOC 检测格式对齐)。

第二步:生成 labels.txt 类别文件。 脚本读取标签目录下的 autosave_label.txt(EISeg 自动保存的标签类别记录),在第一行写入 background(背景类,对应 PaddleX 分割数据集约定背景为第一类),随后逐行取 autosave_label.txt 中每行按空格切分后的第二个字段作为类别名写入。

第三步:生成训练/验证列表。 脚本将拷贝后的图像文件名 random.shuffle 随机打乱,然后按索引比例 idx / lens <= split_rate 写入 train_list.txt 与 val_list.txt,每行内容为 JPEGImages/xxx.jpg Annotations/xxx.png 的相对路径对(seg 模式标签扩展名统一替换为 .png,det 模式替换为 .xml,并处理 Windows 反斜杠路径为 /)。

转换完成后,save_folder 下将得到标准的 PaddleX 语义分割数据集结构:

save_folder/
├── JPEGImages/          # 图像
├── Annotations/         # 标签
├── labels.txt           # 类别列表(首行为 background)
├── train_list.txt       # 训练列表
└── val_list.txt         # 验证列表

三、semantic2instance.py:语义分割标签转实例分割标签

3.1 调用方式

语义分割标签(原标签为 0/255 的二值图)通过 EISeg/tool/semantic2instance.py 可转换为实例分割标签,结果为单通道图像并使用调色板着色,每个连通目标被赋予独立编号:

python semantic2instance.py -o label_path -d save_path

参数说明:

参数 必填 说明
-o / --label_path 是 语义标签存放路径(文件夹)
-d / --save_path 是 实例标签保存路径(文件夹)

脚本会遍历 label_path 下全部文件,逐一调用 _segMaskB2I 转换后按同名写入 save_path。

3.2 转换原理:轮廓层级与挖孔填充

从源码实现看,该脚本的核心算法是基于轮廓层级关系的实例分离(semantic2instance.py 源码):

  1. 读取语义掩膜为 numpy 数组,调用 cv2.findContours(img, cv2.RETR_CCOMP, cv2.CHAIN_APPROX_NONE) 提取轮廓及层级隶属关系(hierarchy),并兼容 OpenCV 3 与 4+ 的返回值差异;
  2. 计算每个轮廓的面积并按面积降序排序,保证大目标先编号;
  3. 遍历所有轮廓:若某轮廓的父轮廓不存在(hierarchy[-1] == -1,即最外层轮廓),用 cv2.fillPoly 以递增的颜色值填充,实现实例编号;反之,若存在父轮廓(属于"洞"的内层轮廓),则以 0 填充,实现空心区域(孔洞)的正确表达;
  4. 最后通过 _savePalette 将结果保存为带调色板的单通道 PNG——调色板由随机生成的颜色构成,并将索引 0(背景)固定为黑色。

这一实现使得包含孔洞的语义掩膜(例如环形目标)也能被正确转换为带编号的实例标签,而非简单的连通域标记。

四、cut_video.py:视频切分脚本

由于视频数据计算量巨大,交互式标注时整段长视频会占用大量显存,因此 EISeg 官方推荐将视频切分成 100 帧以内的片段再标注。脚本位置为 EISeg/tool/cut_video.py。

该脚本不是命令行参数化的,而是通过修改 __main__ 块中的三个变量来使用(源码):

video_path = '/PATH/TO/VIDEO'   # 输入视频路径
save_path = "/PATH/TO/SAVE"     # 切分后视频保存目录
cut_length = 50                 # 每段帧数
video_cut(video_path, save_path, cut_length)

其实现使用 cv2.VideoCapture 读取视频,读取 FPS(get(5))、总帧数(get(7))与宽高尺寸(get(3) / get(4)),以 mp4v 编码(cv2.VideoWriter_fourcc('m','p','4','v'))逐帧写入。切分逻辑按帧序号 frame_index // cut_length 命名输出文件(即第 0~49 帧写入 0.mp4,第 50~99 帧写入 1.mp4,以此类推),输出片段与输入视频保持相同的 FPS 和分辨率。实际使用时可将 cut_length 设为 100 以内(默认示例为 50),以满足 EISeg 视频标注对片段长度的要求。

五、medical2video.py:医疗切片图转视频脚本

3D 医疗标注是基于 EISeg 的视频标注算法实现的,因此在医疗图像标注前,需要先把医疗图像转换成 mp4 格式的视频。脚本位置为 EISeg/tool/medical2video.py。

5.1 支持的医疗数据格式

从源码的 load_medical_data 函数(medical2video.py 源码)看,脚本通过文件扩展名分发处理,支持以下格式:

  • .nii、.nii.gz、.dcm(NIfTI 与 DICOM):通过 SimpleITK 读取,统一用 sitk.DICOMOrient(img, "SLP") 矫正为 SLP 空间方向;若是 4 维数据(如多期相 DICOM 序列),会用 ExtractImageFilter 沿最后一维拆分为多个 3D 体数据;
  • .mha、.mhd、.nrrd:同样经 DICOMOrient 矫正,若为 4 维则按最后一维拆分为多个体数据;
  • .raw:明确拒绝,提示应提供 .mhd 文件路径而非 .raw(因为 .raw 无头信息)。

5.2 窗宽窗位归一化与视频输出

每个 3D 体数据经 array_to_video 沿切片方向逐帧写入视频(源码):

  • 默认帧率 fps=15,编码格式为 mp4v,输出分辨率取单张切片的 (w, h);
  • 每帧切片先经 normalize(frame, ww=400, wc=0) 做窗宽窗位(WW/WL)归一化:按 wc - ww/2 与 wc + ww/2 裁剪灰度范围,再线性映射到 0~255 并转为 uint8,最后用 cv2.cvtColor 转成三通道 BGR 供视频写入——默认 400/0 为 CT 常用的窗宽窗位,保证软组织对比度清晰;
  • 切片顺序即视频帧顺序,标注时逐帧标注即等价于对 3D 体数据逐层标注。

脚本同样通过在 __main__ 块中修改 path(医疗文件完整路径)与 video_path(输出 mp4 路径)来使用。

六、labelme-json2labelme-coco.py:JSON 标签转 COCO 格式

6.1 背景:EISeg 的 labelme 保存格式

EISeg 在标签保存后,会在 label 文件夹下生成一个 labelme 子文件夹,其中包含与 labelme 格式相同的 JSON 文件以及 labels.txt 类别文件。若希望将这些 JSON 转换为与 labelme 相同格式的 COCO 文件,可执行 EISeg/tool/labelme-json2labelme-coco.py。

6.2 调用方式与参数

python labelme-json2labelme-coco.py label_path save_path --labels txt_path

# 例如
# python labelme-json2labelme-coco.py mydata/label/labelme/ mydata/label/labelme/output --labels mydata/label/labelme/labels.txt
参数 必填 说明
label_path(位置参数) 是 labelme 格式 JSON 标签保存路径
save_path(位置参数) 是 转换后的 COCO 格式标签保存路径
--labels txt_path 是 labels.txt 文件路径
--noviz 否 是否跳过可视化图生成(默认生成)

转换完成后会在 save_path 中生成三个文件/目录,格式同 labelme:

  • annotations.json:COCO 格式标注文件(instances 类型,含 images、annotations、categories 三个核心字段);
  • JPEGImages/:由各 JSON 内嵌 imageData 解码后统一转为 JPG 的图像目录;
  • Visualization/:标注叠加在图像上的可视化效果图(通过 imgviz.instances2rgb 绘制类别与 mask)。

6.3 源码要点:类别编号约定与运行依赖

从 labelme-json2labelme-coco.py 源码 可以看出,类别 ID 从 -1 开始递增,labels.txt 的第一行必须是 __ignore__(该行会被跳过且断言其内容),之后每行一个类别名,类别 ID 从 0 开始。这与 EISeg 生成的 labels.txt 首行为 background 的语义不同——转换到 COCO 前需要确认 labels.txt 首行符合脚本约定,否则类别映射会整体偏移。

此外,脚本运行依赖 pycocotools(用于 mask 编码、面积与 bbox 计算,缺失时会提示 pip install pycocotools)、imgviz(可视化)与 PIL。脚本还完整兼容了 labelme 的多边形(polygon)、矩形(rectangle,会重排为四角点坐标)、圆形(circle,会按误差容限拟合成多边形点序列)、线段(line / linestrip)与点(point)等 shape 类型,并按 (label, group_id) 组合合并同一实例的多段标注,group_id 为空时自动以 uuid1() 生成。若 save_path 已存在,脚本会直接报错退出,避免覆盖。

七、工具链协同:从标注到训练的标准工作流

将上述脚本串联,即可形成一条完整的 EISeg 数据生产流水线:

  1. 图像标注:使用 EISeg 对图像(图像分割标注教程)、视频与 3D 医疗数据(视频及 3D 医疗分割标注教程)、遥感图像(遥感分割特色功能)或医学图像(医疗分割特色功能)进行交互式标注;
  2. 数据预处理:长视频先用 cut_video.py 切分为 100 帧以内片段;医疗图像先用 medical2video.py 转为 mp4 后再进入标注环节;
  3. 格式转换:
    • 训练语义分割模型 → eiseg2paddlex.py -m seg 生成 PaddleX 分割数据集,直接对接 PaddleSeg / PaddleX 训练;
    • 训练目标检测模型 → eiseg2paddlex.py -m det(或结合 图像检测标注 生成的检测结果)生成带 VOC XML 的检测数据集;
    • 训练实例分割模型 → 先用 semantic2instance.py 将语义标签转为实例标签,或用 labelme-json2labelme-coco.py 将 labelme JSON 转为 COCO 实例格式;
  4. 模型训练:将生成的 train_list.txt / val_list.txt(或 COCO 标注)配置到 PaddleSeg 训练流程中,获得定制化场景的高精度模型。

八、总结

EISeg 配套的 5 个工具脚本覆盖了标注后数据处理的绝大多数场景:eiseg2paddlex.py 负责打通到 PaddleX 训练格式的主干路径,semantic2instance.py 提供语义到实例标签的转换能力,cut_video.py 与 medical2video.py 解决视频与 3D 医疗数据的预处理难题,labelme-json2labelme-coco.py 则让 EISeg 标注结果无缝汇入 labelme/COCO 生态。理解这些脚本的参数约定与源码实现,可以让你在构建数据集时少走弯路,也能根据自身数据特点对脚本进行二次调整。更多细节可参阅 EISeg 官方 README 及英文版 tools_en.md。

登录后查看全文
PaddleSeg