EISeg 数据处理工具脚本全指南:从交互式标注到 PaddleX / 实例分割 / COCO 训练数据集
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 源码):
- 读取语义掩膜为 numpy 数组,调用
cv2.findContours(img, cv2.RETR_CCOMP, cv2.CHAIN_APPROX_NONE)提取轮廓及层级隶属关系(hierarchy),并兼容 OpenCV 3 与 4+ 的返回值差异; - 计算每个轮廓的面积并按面积降序排序,保证大目标先编号;
- 遍历所有轮廓:若某轮廓的父轮廓不存在(
hierarchy[-1] == -1,即最外层轮廓),用cv2.fillPoly以递增的颜色值填充,实现实例编号;反之,若存在父轮廓(属于"洞"的内层轮廓),则以 0 填充,实现空心区域(孔洞)的正确表达; - 最后通过
_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 数据生产流水线:
- 图像标注:使用 EISeg 对图像(图像分割标注教程)、视频与 3D 医疗数据(视频及 3D 医疗分割标注教程)、遥感图像(遥感分割特色功能)或医学图像(医疗分割特色功能)进行交互式标注;
- 数据预处理:长视频先用
cut_video.py切分为 100 帧以内片段;医疗图像先用medical2video.py转为 mp4 后再进入标注环节; - 格式转换:
- 训练语义分割模型 →
eiseg2paddlex.py -m seg生成 PaddleX 分割数据集,直接对接 PaddleSeg / PaddleX 训练; - 训练目标检测模型 →
eiseg2paddlex.py -m det(或结合 图像检测标注 生成的检测结果)生成带 VOC XML 的检测数据集; - 训练实例分割模型 → 先用
semantic2instance.py将语义标签转为实例标签,或用labelme-json2labelme-coco.py将 labelme JSON 转为 COCO 实例格式;
- 训练语义分割模型 →
- 模型训练:将生成的
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。