1. 项目概述从标注文件到像素级掩码的必经之路在计算机视觉特别是语义分割任务的实际开发流程中我们常常会遇到一个看似简单却至关重要的环节如何将标注工具如Labelme生成的JSON文件转换为模型训练所需的Mask掩码图像。这不仅是数据预处理的核心步骤更是连接“人工标注”与“算法训练”的桥梁。很多新手朋友在初次接触时往往会被JSON文件里复杂的多边形坐标、层次结构弄得晕头转向而网上零散的代码片段又常常因为版本、库依赖或数据结构差异而无法直接运行。今天我就结合自己处理过成千上万张标注数据的经验把这个过程掰开揉碎了讲清楚让你不仅能跑通流程更能理解背后的每一个细节和可能遇到的“坑”。简单来说这个过程的目标是将人类可读的标注信息JSON转化为机器可识别的像素级标签图Mask。生成的Mask通常是一张单通道的灰度图其中每个像素点的值代表其所属的类别ID例如0代表背景1代表“猫”2代表“狗”。这项工作直接关系到后续模型训练数据的质量。一个转换错误比如像素错位或类别混淆就可能导致模型学习到错误的信息轻则影响精度重则让整个训练过程失效。因此掌握一套稳健、高效的转换方法是语义分割项目落地的基础。2. 核心思路与工具选型解析2.1 理解数据流转从Labelme JSON到Mask首先我们必须透彻理解源头数据的结构。以最常用的标注工具Labelme为例它保存的JSON文件并非一个简单的坐标列表而是一个包含了图像信息、标注形状、类别标签等丰富信息的结构化文档。一个典型的Labelme JSON文件主要包含以下部分version Labelme的版本号不同版本可能有细微差异。flags 一些全局标志。shapes 这是一个数组也是我们关注的核心。每个元素代表一个标注对象其中包含label 该对象的类别名称如“person”、“car”。points 一个列表存储了构成该形状的多边形各个顶点的[x, y]坐标。注意这里的坐标通常是浮点数对应图像中的像素位置。shape_type 形状类型如“polygon”多边形、“rectangle”矩形等语义分割中最常用的是多边形。imagePath 原始图像的文件名。imageData 可选项有时会直接以Base64编码格式内嵌图像数据。但我们通常更倾向于根据imagePath去读取独立的图像文件这样更灵活。我们的任务就是遍历shapes数组中的每一个多边形根据其label确定填充的像素值类别ID然后在一个与原始图像尺寸相同的空白画布上将这些多边形区域“绘制”出来最终生成一张Mask。2.2 工具链选择为什么是OpenCV NumPy要实现这个“绘制”过程我们需要强大的图像处理库。这里首推OpenCV和NumPy的组合这是计算机视觉领域的“黄金搭档”。OpenCV (cv2) 它提供了cv2.fillPoly()这个关键函数。这个函数能够根据一组多边形顶点坐标在指定的图像上填充出实心区域。这正好完美对应了我们的需求将多边形的轮廓内部填充为指定的颜色即类别ID。NumPy Mask本质上是一个二维数组单通道或三维数组多通道。NumPy提供了高效的数组创建、操作和保存功能。我们可以轻松地创建一个全零背景的数组然后利用索引将OpenCV填充的区域值修改为对应的类别ID。为什么不直接用PILPython Imaging LibraryPIL当然也可以做到使用ImageDraw模块但OpenCV在处理多边形填充、特别是复杂多边形或带孔洞多边形时其底层实现的效率和鲁棒性通常更优且与整个CV技术栈的集成度更高。此外OpenCV保存图像格式如PNG对单通道16位或8位灰度图的支持非常直接方便后续训练框架如PyTorch, TensorFlow读取。一个重要的注意事项OpenCV的坐标系统原点在左上角x轴向右y轴向下。这与我们常见的数学坐标系不同但与图像像素的索引方式一致img[y, x]。Labelme JSON中的坐标[x, y]可以直接用于OpenCV但要注意数据类型转换浮点数转整数。3. 核心代码实现与逐行详解理论清晰后我们来看代码。下面我将提供一个功能完整、注释详细的转换函数并逐一解释关键步骤。import json import os import numpy as np import cv2 from pathlib import Path def labelme_json_to_mask(json_path, class_name_to_id, output_dirNone): 将Labelme生成的JSON标注文件转换为语义分割Mask图像。 参数 json_path (str): Labelme JSON文件的路径。 class_name_to_id (dict): 类别名称到类别ID的映射字典。例如{background: 0, cat: 1, dog: 2}。 注意务必包含background类别且ID通常为0。 output_dir (str, optional): Mask图像的输出目录。如果为None则保存在JSON文件同目录。 返回 mask (numpy.ndarray): 生成的Mask数组。 mask_save_path (str): Mask图像保存的完整路径。 # 1. 加载并解析JSON文件 with open(json_path, r, encodingutf-8) as f: data json.load(f) # 2. 获取图像尺寸信息 # 注意JSON中可能没有直接的imageHeight/Width需要从imageData或读取原图获取。 # 更稳健的方式是读取原始图像。 image_path os.path.join(os.path.dirname(json_path), data[imagePath]) if not os.path.exists(image_path): # 如果找不到原图尝试从JSON的imageData解码如果存在 if imageData in data and data[imageData] is not None: # 这里省略了Base64解码的代码通常建议直接使用原图文件 raise FileNotFoundError(f原始图像未找到且未处理内嵌图像数据。请检查路径: {image_path}) else: raise FileNotFoundError(f原始图像未找到: {image_path}) # 读取原图仅为了获取尺寸不处理颜色信息 img cv2.imread(image_path, cv2.IMREAD_UNCHANGED) # IMREAD_UNCHANGED 可以读取带透明通道的图 if img is None: raise ValueError(f无法读取图像文件: {image_path}) height, width img.shape[:2] # 获取图像的高和宽 # 3. 创建空的Mask画布 # 使用uint8数据类型最多支持256类。如果类别超过255请使用uint16。 mask np.zeros((height, width), dtypenp.uint8) # 4. 遍历所有标注形状shapes for shape in data[shapes]: label_name shape[label] points shape[points] shape_type shape.get(shape_type, polygon) # 检查当前标签是否在预定义的类别映射中 if label_name not in class_name_to_id: print(f警告: 在文件 {json_path} 中发现了未定义类别 {label_name}已跳过。) continue class_id class_name_to_id[label_name] # 将浮点数坐标点转换为OpenCV所需的整数格式和特定形状 # points 格式: [[x1, y1], [x2, y2], ...] pts np.array(points, dtypenp.int32) # 转换为整数坐标 # OpenCV的fillPoly要求输入是三维数组形状为 (1, N, 2) pts pts.reshape((-1, 1, 2)) # 5. 使用OpenCV填充多边形 # 参数目标图像多边形列表填充颜色类别ID cv2.fillPoly(mask, [pts], colorclass_id) # 注意如果有多个多边形属于同一类别fillPoly会多次填充后填充的会覆盖先填充的。 # 这符合标注逻辑后来标注的可能是修正。 # 6. 处理输出路径并保存Mask json_filename Path(json_path).stem # 获取不带扩展名的JSON文件名 mask_filename f{json_filename}_mask.png if output_dir is not None: os.makedirs(output_dir, exist_okTrue) mask_save_path os.path.join(output_dir, mask_filename) else: mask_save_path os.path.join(os.path.dirname(json_path), mask_filename) # 保存为PNG格式。PNG是无损压缩适合保存索引图。 # 使用cv2.IMWRITE_PNG_COMPRESSION参数控制压缩级别0为无压缩9为最大压缩默认为3。 cv2.imwrite(mask_save_path, mask, [cv2.IMWRITE_PNG_COMPRESSION, 3]) print(fMask已保存至: {mask_save_path}) return mask, mask_save_path # 使用示例 if __name__ __main__: # 定义你的类别映射 CLASS_DICT { background: 0, # 背景必须存在且ID通常为0 cat: 1, dog: 2, car: 3, } # 单个文件转换 json_file path/to/your/annotation.json mask_array, save_path labelme_json_to_mask(json_file, CLASS_DICT, output_dir./masks) # 批量转换一个目录下的所有JSON文件 # import glob # json_files glob.glob(path/to/annotations/*.json) # for jf in json_files: # try: # labelme_json_to_mask(jf, CLASS_DICT, ./masks) # except Exception as e: # print(f处理文件 {jf} 时出错: {e})关键点解析与实操心得图像尺寸获取的稳健性代码中优先通过读取原始图像文件来获取高宽。这是最可靠的方法。虽然JSON中有时会包含imageHeight和imageWidth字段但并非绝对存在。依赖原图文件可以确保Mask尺寸100%匹配。数据类型选择np.uint8意味着Mask每个像素的值范围是0-255这足以应对绝大多数语义分割场景类别数256。如果你的项目有超过255个类别如某些精细的部件分割则需要使用dtypenp.uint16。坐标转换的陷阱np.array(points, dtypenp.int32)和pts.reshape((-1, 1, 2))这两步至关重要。int32是OpenCV处理轮廓时常用的数据类型。reshape操作将[N, 2]的数组变为[1, N, 2]是因为cv2.fillPoly期望接收一个“多边形列表”即使我们只填充一个多边形也需要将其放在一个列表中。-1是NumPy的语法表示自动推断该维度的大小。覆盖顺序cv2.fillPoly会按照遍历shapes的顺序进行绘制。如果两个多边形有重叠区域后绘制的会覆盖先绘制的。在标注时这通常用于处理物体遮挡被挡的部分后标或标注修正。你需要确保这个逻辑符合你的标注规范。输出格式保存为PNG是首选因为它支持无损压缩且能正确存储单通道的索引图像。避免使用JPG因为JPG的有损压缩会严重破坏Mask边缘的像素值导致类别信息出错。4. 进阶处理与常见问题排查4.1 处理复杂情况多部件实例与孔洞现实世界的标注往往更复杂。例如一个“人”可能由身体、左臂、右臂等多个分离的多边形组成多部件实例或者一个“甜甜圈”物体中间有一个洞孔洞。多部件实例对于属于同一物体的多个分离部分在Labelme中会被标注为多个拥有相同label的独立shape。我们上面的代码逻辑已经天然支持了这种情况因为它是遍历所有shape并根据label填充相同ID。最终这些分离的部分在Mask中会显示为同一类别的不同区域。带孔洞的多边形Labelme本身不支持直接标注带孔洞的多边形。一种常见的变通方法是分别标注外轮廓和内轮廓孔洞并给内轮廓赋予一个特殊的标签如“holeobject”。在转换时你需要更复杂的逻辑先填充外轮廓再用背景色或特定颜色填充内轮廓。这需要你在遍历shapes时根据标签名称识别出孔洞关系并调整填充顺序和颜色。# 简化的孔洞处理思路假设孔洞标签为“_hole”后缀 for shape in data[shapes]: label_name shape[label] if label_name.endswith(_hole): # 这是一个孔洞找到其对应的主体标签 main_label label_name.replace(_hole, ) if main_label in class_name_to_id: # 先填充主体假设主体已填充过 # 然后用背景色0再次填充孔洞区域实现“挖空”效果 # 注意这要求主体填充在先孔洞填充在后 pts np.array(shape[points], dtypenp.int32).reshape((-1, 1, 2)) cv2.fillPoly(mask, [pts], color0) # 用背景色覆盖 else: # 正常填充主体 ... # 正常填充逻辑注意孔洞处理逻辑强烈依赖于你的标注规范必须在标注前就和标注人员约定清楚。4.2 类别映射的管理与验证class_name_to_id字典是这个转换过程的“宪法”。管理不善会导致类别混乱。统一映射文件不要在每个转换脚本里硬编码这个字典。应该将其保存为一个独立的配置文件如class_mapping.json或classes.txt并在所有相关环节转换、训练、评估中引用同一份文件。包含背景类务必明确包含background类别且ID通常设为0。这是语义分割任务的标准做法。验证标签在转换前或转换过程中加入标签校验。统计所有JSON文件中出现的唯一标签并与你的映射字典对比及时发现未定义或拼写错误的标签。4.3 批量处理与自动化脚本实际项目动辄成千上万的图片手动转换不现实。我们需要批量处理脚本。import glob import concurrent.futures from tqdm import tqdm # 用于显示进度条需安装pip install tqdm def batch_convert(json_dir, class_dict, mask_output_dir, num_workers4): 批量转换一个目录下的所有Labelme JSON文件。 参数 json_dir (str): 存放JSON文件的目录。 class_dict (dict): 类别映射字典。 mask_output_dir (str): Mask输出目录。 num_workers (int): 并行处理的进程数。 json_pattern os.path.join(json_dir, *.json) json_files glob.glob(json_pattern) if not json_files: print(f在目录 {json_dir} 中未找到JSON文件。) return os.makedirs(mask_output_dir, exist_okTrue) # 使用进程池并行处理加速转换 with concurrent.futures.ProcessPoolExecutor(max_workersnum_workers) as executor: # 提交任务 future_to_file {executor.submit(labelme_json_to_mask, jf, class_dict, mask_output_dir): jf for jf in json_files} # 使用tqdm创建进度条 for future in tqdm(concurrent.futures.as_completed(future_to_file), totallen(json_files), desc转换进度): json_file future_to_file[future] try: future.result() # 获取结果如果出错会在这里抛出异常 except Exception as exc: print(f\n处理文件 {json_file} 时产生异常: {exc})使用多进程ProcessPoolExecutor而非多线程是因为转换任务主要是CPU密集型NumPy/OpenCV计算多进程能更好地利用多核CPU。tqdm库提供的进度条能让你直观了解处理进度。4.4 常见问题排查速查表在实际操作中你几乎一定会遇到下面这些问题。这里我整理了一个快速排查指南。问题现象可能原因解决方案生成的Mask全黑全是01.class_name_to_id字典中类别名称与JSON中的label不匹配大小写、空格、拼写。2. 多边形坐标点pts转换或reshape出错导致cv2.fillPoly未执行有效填充。3. 图像尺寸获取错误创建了错误尺寸的Mask画布。1. 打印JSON中的label和你的字典键值进行比对。2. 在cv2.fillPoly前后打印pts的形状和class_id检查数据是否正确。3. 打印height, width并与原图实际尺寸核对。Mask区域错位坐标系统理解错误。误用了行/列索引或坐标原点。牢记OpenCV和NumPy的索引是[y, x]即行, 列。Labelme的[x, y]对应列, 行。确保在创建pts时顺序正确。保存的Mask图片打开后是纯色块用图片查看软件打开单通道灰度图时软件可能将其拉伸显示。像素值0和1的视觉对比度很低看起来像全黑或全白。这是显示问题不是数据问题。可以用OpenCV或Matplotlib以彩色映射colormap方式显示或直接打印Mask数组的独特值np.unique(mask)来确认内容。处理速度非常慢1. 图像分辨率过高。2. 多边形顶点数量极多。3. 使用循环逐个像素处理错误方法。1. 确认是否使用了上述基于cv2.fillPoly的向量化操作它比逐像素循环快几个数量级。2. 对于超大图可考虑先缩放多边形坐标在小尺寸画布上生成Mask再上采样会损失精度。3. 使用上述的批量并行处理脚本。遇到“Assertion failed”等OpenCV错误传递给cv2.fillPoly的pts数组格式不正确或者坐标值超出了画布边界负数或大于宽高。1. 检查pts的维度是否为(1, N, 2)。2. 在填充前对坐标进行裁剪pts[:, :, 0] np.clip(pts[:, :, 0], 0, width-1);pts[:, :, 1] np.clip(pts[:, :, 1], 0, height-1)。类别ID在Mask中不连续转换过程中跳过了某些未定义类别或者class_name_to_id字典的ID本身不连续。这通常不影响模型训练模型通过查找表读取ID但可能影响可视化。确保映射字典的ID从0开始连续递增。如果为了保留某些中间类别不连续也是可以的但需要在训练代码中正确处理。5. 可视化与质量检查生成Mask后绝对不能直接扔给模型训练。必须进行严格的质量检查。最有效的方法就是可视化。import matplotlib.pyplot as plt def visualize_mask_and_image(image_path, mask_path): 并排显示原始图像和对应的Mask标签。 img cv2.imread(image_path) img_rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) # OpenCV读取为BGR转为RGB用于显示 mask cv2.imread(mask_path, cv2.IMREAD_GRAYSCALE) fig, axes plt.subplots(1, 2, figsize(12, 6)) axes[0].imshow(img_rgb) axes[0].set_title(Original Image) axes[0].axis(off) # 使用特定的colormap显示Mask让不同类别颜色区分明显 im axes[1].imshow(mask, cmaptab20) # tab20是一个有20种明显区别颜色的cmap axes[1].set_title(Segmentation Mask) axes[1].axis(off) plt.colorbar(im, axaxes[1], fraction0.046, pad0.04) # 添加颜色条以指示类别ID plt.show() # 打印基本信息 print(f图像尺寸: {img.shape}) print(fMask尺寸: {mask.shape}) print(fMask中存在的唯一类别ID: {np.unique(mask)}) # 使用示例 visualize_mask_and_image(path/to/original.jpg, path/to/mask.png)可视化能帮你一眼发现那些“隐藏”的问题Mask是否与物体边缘对齐是否有奇怪的像素块可能是坐标错误类别颜色是否与预期相符养成生成后必抽查的习惯能节省大量后期调试模型的时间。6. 集成到训练管道与格式考量生成的Mask最终要喂给深度学习框架。这里有几个关键格式考量文件命名与配对确保Mask文件与原始图像文件有明确的对应关系。上述代码生成的{json_filename}_mask.png是一种方式。更常见的做法是放在单独的masks或labels文件夹但保持与图像相同的文件名仅扩展名不同。读取与转换在PyTorch或TensorFlow的Dataset类中你需要同时读取图像和Mask。Mask通常以单通道灰度图读入然后可能需要将其转换为LongTensorPyTorch或int32TensorFlow类型的标签。# PyTorch Dataset 示例片段 import torch from torch.utils.data import Dataset from PIL import Image class SegmentationDataset(Dataset): def __init__(self, img_dir, mask_dir, transformNone): self.img_dir img_dir self.mask_dir mask_dir self.transform transform self.img_names os.listdir(img_dir) # 假设图片和mask文件名相同 def __getitem__(self, idx): img_name self.img_names[idx] img_path os.path.join(self.img_dir, img_name) mask_path os.path.join(self.mask_dir, img_name.replace(.jpg, _mask.png)) # 根据命名规则调整 image Image.open(img_path).convert(RGB) mask Image.open(mask_path).convert(L) # L模式表示灰度 if self.transform: image self.transform(image) # 注意对mask的变换通常只用几何变换如裁剪、翻转不能用颜色变换 mask self.transform(mask) # 将PIL Image或Tensor转换为LongTensor mask torch.from_numpy(np.array(mask, dtypenp.int64)).long() return image, mask类别平衡检查在批量转换后建议统计一下每个类别在数据集中所占的像素比例。如果某个类别如“背景”占据了绝大多数像素模型可能会倾向于忽略小物体。这时就需要考虑使用加权损失函数如torch.nn.CrossEntropyLoss的weight参数或过采样策略。整个从JSON到Mask的转换流程虽然只是语义分割项目中的一个预处理环节但其稳定性和准确性是项目成功的基石。我个人的经验是在这个阶段多花一些时间构建稳健的脚本、建立严格的质量检查流程远比在模型训练陷入僵局后再回头排查数据问题要高效得多。希望这份详细的拆解能帮你扫清障碍把精力更多地投入到更有创造性的模型设计和调优工作中去。
Labelme JSON转Mask：语义分割数据预处理核心代码与实战
1. 项目概述从标注文件到像素级掩码的必经之路在计算机视觉特别是语义分割任务的实际开发流程中我们常常会遇到一个看似简单却至关重要的环节如何将标注工具如Labelme生成的JSON文件转换为模型训练所需的Mask掩码图像。这不仅是数据预处理的核心步骤更是连接“人工标注”与“算法训练”的桥梁。很多新手朋友在初次接触时往往会被JSON文件里复杂的多边形坐标、层次结构弄得晕头转向而网上零散的代码片段又常常因为版本、库依赖或数据结构差异而无法直接运行。今天我就结合自己处理过成千上万张标注数据的经验把这个过程掰开揉碎了讲清楚让你不仅能跑通流程更能理解背后的每一个细节和可能遇到的“坑”。简单来说这个过程的目标是将人类可读的标注信息JSON转化为机器可识别的像素级标签图Mask。生成的Mask通常是一张单通道的灰度图其中每个像素点的值代表其所属的类别ID例如0代表背景1代表“猫”2代表“狗”。这项工作直接关系到后续模型训练数据的质量。一个转换错误比如像素错位或类别混淆就可能导致模型学习到错误的信息轻则影响精度重则让整个训练过程失效。因此掌握一套稳健、高效的转换方法是语义分割项目落地的基础。2. 核心思路与工具选型解析2.1 理解数据流转从Labelme JSON到Mask首先我们必须透彻理解源头数据的结构。以最常用的标注工具Labelme为例它保存的JSON文件并非一个简单的坐标列表而是一个包含了图像信息、标注形状、类别标签等丰富信息的结构化文档。一个典型的Labelme JSON文件主要包含以下部分version Labelme的版本号不同版本可能有细微差异。flags 一些全局标志。shapes 这是一个数组也是我们关注的核心。每个元素代表一个标注对象其中包含label 该对象的类别名称如“person”、“car”。points 一个列表存储了构成该形状的多边形各个顶点的[x, y]坐标。注意这里的坐标通常是浮点数对应图像中的像素位置。shape_type 形状类型如“polygon”多边形、“rectangle”矩形等语义分割中最常用的是多边形。imagePath 原始图像的文件名。imageData 可选项有时会直接以Base64编码格式内嵌图像数据。但我们通常更倾向于根据imagePath去读取独立的图像文件这样更灵活。我们的任务就是遍历shapes数组中的每一个多边形根据其label确定填充的像素值类别ID然后在一个与原始图像尺寸相同的空白画布上将这些多边形区域“绘制”出来最终生成一张Mask。2.2 工具链选择为什么是OpenCV NumPy要实现这个“绘制”过程我们需要强大的图像处理库。这里首推OpenCV和NumPy的组合这是计算机视觉领域的“黄金搭档”。OpenCV (cv2) 它提供了cv2.fillPoly()这个关键函数。这个函数能够根据一组多边形顶点坐标在指定的图像上填充出实心区域。这正好完美对应了我们的需求将多边形的轮廓内部填充为指定的颜色即类别ID。NumPy Mask本质上是一个二维数组单通道或三维数组多通道。NumPy提供了高效的数组创建、操作和保存功能。我们可以轻松地创建一个全零背景的数组然后利用索引将OpenCV填充的区域值修改为对应的类别ID。为什么不直接用PILPython Imaging LibraryPIL当然也可以做到使用ImageDraw模块但OpenCV在处理多边形填充、特别是复杂多边形或带孔洞多边形时其底层实现的效率和鲁棒性通常更优且与整个CV技术栈的集成度更高。此外OpenCV保存图像格式如PNG对单通道16位或8位灰度图的支持非常直接方便后续训练框架如PyTorch, TensorFlow读取。一个重要的注意事项OpenCV的坐标系统原点在左上角x轴向右y轴向下。这与我们常见的数学坐标系不同但与图像像素的索引方式一致img[y, x]。Labelme JSON中的坐标[x, y]可以直接用于OpenCV但要注意数据类型转换浮点数转整数。3. 核心代码实现与逐行详解理论清晰后我们来看代码。下面我将提供一个功能完整、注释详细的转换函数并逐一解释关键步骤。import json import os import numpy as np import cv2 from pathlib import Path def labelme_json_to_mask(json_path, class_name_to_id, output_dirNone): 将Labelme生成的JSON标注文件转换为语义分割Mask图像。 参数 json_path (str): Labelme JSON文件的路径。 class_name_to_id (dict): 类别名称到类别ID的映射字典。例如{background: 0, cat: 1, dog: 2}。 注意务必包含background类别且ID通常为0。 output_dir (str, optional): Mask图像的输出目录。如果为None则保存在JSON文件同目录。 返回 mask (numpy.ndarray): 生成的Mask数组。 mask_save_path (str): Mask图像保存的完整路径。 # 1. 加载并解析JSON文件 with open(json_path, r, encodingutf-8) as f: data json.load(f) # 2. 获取图像尺寸信息 # 注意JSON中可能没有直接的imageHeight/Width需要从imageData或读取原图获取。 # 更稳健的方式是读取原始图像。 image_path os.path.join(os.path.dirname(json_path), data[imagePath]) if not os.path.exists(image_path): # 如果找不到原图尝试从JSON的imageData解码如果存在 if imageData in data and data[imageData] is not None: # 这里省略了Base64解码的代码通常建议直接使用原图文件 raise FileNotFoundError(f原始图像未找到且未处理内嵌图像数据。请检查路径: {image_path}) else: raise FileNotFoundError(f原始图像未找到: {image_path}) # 读取原图仅为了获取尺寸不处理颜色信息 img cv2.imread(image_path, cv2.IMREAD_UNCHANGED) # IMREAD_UNCHANGED 可以读取带透明通道的图 if img is None: raise ValueError(f无法读取图像文件: {image_path}) height, width img.shape[:2] # 获取图像的高和宽 # 3. 创建空的Mask画布 # 使用uint8数据类型最多支持256类。如果类别超过255请使用uint16。 mask np.zeros((height, width), dtypenp.uint8) # 4. 遍历所有标注形状shapes for shape in data[shapes]: label_name shape[label] points shape[points] shape_type shape.get(shape_type, polygon) # 检查当前标签是否在预定义的类别映射中 if label_name not in class_name_to_id: print(f警告: 在文件 {json_path} 中发现了未定义类别 {label_name}已跳过。) continue class_id class_name_to_id[label_name] # 将浮点数坐标点转换为OpenCV所需的整数格式和特定形状 # points 格式: [[x1, y1], [x2, y2], ...] pts np.array(points, dtypenp.int32) # 转换为整数坐标 # OpenCV的fillPoly要求输入是三维数组形状为 (1, N, 2) pts pts.reshape((-1, 1, 2)) # 5. 使用OpenCV填充多边形 # 参数目标图像多边形列表填充颜色类别ID cv2.fillPoly(mask, [pts], colorclass_id) # 注意如果有多个多边形属于同一类别fillPoly会多次填充后填充的会覆盖先填充的。 # 这符合标注逻辑后来标注的可能是修正。 # 6. 处理输出路径并保存Mask json_filename Path(json_path).stem # 获取不带扩展名的JSON文件名 mask_filename f{json_filename}_mask.png if output_dir is not None: os.makedirs(output_dir, exist_okTrue) mask_save_path os.path.join(output_dir, mask_filename) else: mask_save_path os.path.join(os.path.dirname(json_path), mask_filename) # 保存为PNG格式。PNG是无损压缩适合保存索引图。 # 使用cv2.IMWRITE_PNG_COMPRESSION参数控制压缩级别0为无压缩9为最大压缩默认为3。 cv2.imwrite(mask_save_path, mask, [cv2.IMWRITE_PNG_COMPRESSION, 3]) print(fMask已保存至: {mask_save_path}) return mask, mask_save_path # 使用示例 if __name__ __main__: # 定义你的类别映射 CLASS_DICT { background: 0, # 背景必须存在且ID通常为0 cat: 1, dog: 2, car: 3, } # 单个文件转换 json_file path/to/your/annotation.json mask_array, save_path labelme_json_to_mask(json_file, CLASS_DICT, output_dir./masks) # 批量转换一个目录下的所有JSON文件 # import glob # json_files glob.glob(path/to/annotations/*.json) # for jf in json_files: # try: # labelme_json_to_mask(jf, CLASS_DICT, ./masks) # except Exception as e: # print(f处理文件 {jf} 时出错: {e})关键点解析与实操心得图像尺寸获取的稳健性代码中优先通过读取原始图像文件来获取高宽。这是最可靠的方法。虽然JSON中有时会包含imageHeight和imageWidth字段但并非绝对存在。依赖原图文件可以确保Mask尺寸100%匹配。数据类型选择np.uint8意味着Mask每个像素的值范围是0-255这足以应对绝大多数语义分割场景类别数256。如果你的项目有超过255个类别如某些精细的部件分割则需要使用dtypenp.uint16。坐标转换的陷阱np.array(points, dtypenp.int32)和pts.reshape((-1, 1, 2))这两步至关重要。int32是OpenCV处理轮廓时常用的数据类型。reshape操作将[N, 2]的数组变为[1, N, 2]是因为cv2.fillPoly期望接收一个“多边形列表”即使我们只填充一个多边形也需要将其放在一个列表中。-1是NumPy的语法表示自动推断该维度的大小。覆盖顺序cv2.fillPoly会按照遍历shapes的顺序进行绘制。如果两个多边形有重叠区域后绘制的会覆盖先绘制的。在标注时这通常用于处理物体遮挡被挡的部分后标或标注修正。你需要确保这个逻辑符合你的标注规范。输出格式保存为PNG是首选因为它支持无损压缩且能正确存储单通道的索引图像。避免使用JPG因为JPG的有损压缩会严重破坏Mask边缘的像素值导致类别信息出错。4. 进阶处理与常见问题排查4.1 处理复杂情况多部件实例与孔洞现实世界的标注往往更复杂。例如一个“人”可能由身体、左臂、右臂等多个分离的多边形组成多部件实例或者一个“甜甜圈”物体中间有一个洞孔洞。多部件实例对于属于同一物体的多个分离部分在Labelme中会被标注为多个拥有相同label的独立shape。我们上面的代码逻辑已经天然支持了这种情况因为它是遍历所有shape并根据label填充相同ID。最终这些分离的部分在Mask中会显示为同一类别的不同区域。带孔洞的多边形Labelme本身不支持直接标注带孔洞的多边形。一种常见的变通方法是分别标注外轮廓和内轮廓孔洞并给内轮廓赋予一个特殊的标签如“holeobject”。在转换时你需要更复杂的逻辑先填充外轮廓再用背景色或特定颜色填充内轮廓。这需要你在遍历shapes时根据标签名称识别出孔洞关系并调整填充顺序和颜色。# 简化的孔洞处理思路假设孔洞标签为“_hole”后缀 for shape in data[shapes]: label_name shape[label] if label_name.endswith(_hole): # 这是一个孔洞找到其对应的主体标签 main_label label_name.replace(_hole, ) if main_label in class_name_to_id: # 先填充主体假设主体已填充过 # 然后用背景色0再次填充孔洞区域实现“挖空”效果 # 注意这要求主体填充在先孔洞填充在后 pts np.array(shape[points], dtypenp.int32).reshape((-1, 1, 2)) cv2.fillPoly(mask, [pts], color0) # 用背景色覆盖 else: # 正常填充主体 ... # 正常填充逻辑注意孔洞处理逻辑强烈依赖于你的标注规范必须在标注前就和标注人员约定清楚。4.2 类别映射的管理与验证class_name_to_id字典是这个转换过程的“宪法”。管理不善会导致类别混乱。统一映射文件不要在每个转换脚本里硬编码这个字典。应该将其保存为一个独立的配置文件如class_mapping.json或classes.txt并在所有相关环节转换、训练、评估中引用同一份文件。包含背景类务必明确包含background类别且ID通常设为0。这是语义分割任务的标准做法。验证标签在转换前或转换过程中加入标签校验。统计所有JSON文件中出现的唯一标签并与你的映射字典对比及时发现未定义或拼写错误的标签。4.3 批量处理与自动化脚本实际项目动辄成千上万的图片手动转换不现实。我们需要批量处理脚本。import glob import concurrent.futures from tqdm import tqdm # 用于显示进度条需安装pip install tqdm def batch_convert(json_dir, class_dict, mask_output_dir, num_workers4): 批量转换一个目录下的所有Labelme JSON文件。 参数 json_dir (str): 存放JSON文件的目录。 class_dict (dict): 类别映射字典。 mask_output_dir (str): Mask输出目录。 num_workers (int): 并行处理的进程数。 json_pattern os.path.join(json_dir, *.json) json_files glob.glob(json_pattern) if not json_files: print(f在目录 {json_dir} 中未找到JSON文件。) return os.makedirs(mask_output_dir, exist_okTrue) # 使用进程池并行处理加速转换 with concurrent.futures.ProcessPoolExecutor(max_workersnum_workers) as executor: # 提交任务 future_to_file {executor.submit(labelme_json_to_mask, jf, class_dict, mask_output_dir): jf for jf in json_files} # 使用tqdm创建进度条 for future in tqdm(concurrent.futures.as_completed(future_to_file), totallen(json_files), desc转换进度): json_file future_to_file[future] try: future.result() # 获取结果如果出错会在这里抛出异常 except Exception as exc: print(f\n处理文件 {json_file} 时产生异常: {exc})使用多进程ProcessPoolExecutor而非多线程是因为转换任务主要是CPU密集型NumPy/OpenCV计算多进程能更好地利用多核CPU。tqdm库提供的进度条能让你直观了解处理进度。4.4 常见问题排查速查表在实际操作中你几乎一定会遇到下面这些问题。这里我整理了一个快速排查指南。问题现象可能原因解决方案生成的Mask全黑全是01.class_name_to_id字典中类别名称与JSON中的label不匹配大小写、空格、拼写。2. 多边形坐标点pts转换或reshape出错导致cv2.fillPoly未执行有效填充。3. 图像尺寸获取错误创建了错误尺寸的Mask画布。1. 打印JSON中的label和你的字典键值进行比对。2. 在cv2.fillPoly前后打印pts的形状和class_id检查数据是否正确。3. 打印height, width并与原图实际尺寸核对。Mask区域错位坐标系统理解错误。误用了行/列索引或坐标原点。牢记OpenCV和NumPy的索引是[y, x]即行, 列。Labelme的[x, y]对应列, 行。确保在创建pts时顺序正确。保存的Mask图片打开后是纯色块用图片查看软件打开单通道灰度图时软件可能将其拉伸显示。像素值0和1的视觉对比度很低看起来像全黑或全白。这是显示问题不是数据问题。可以用OpenCV或Matplotlib以彩色映射colormap方式显示或直接打印Mask数组的独特值np.unique(mask)来确认内容。处理速度非常慢1. 图像分辨率过高。2. 多边形顶点数量极多。3. 使用循环逐个像素处理错误方法。1. 确认是否使用了上述基于cv2.fillPoly的向量化操作它比逐像素循环快几个数量级。2. 对于超大图可考虑先缩放多边形坐标在小尺寸画布上生成Mask再上采样会损失精度。3. 使用上述的批量并行处理脚本。遇到“Assertion failed”等OpenCV错误传递给cv2.fillPoly的pts数组格式不正确或者坐标值超出了画布边界负数或大于宽高。1. 检查pts的维度是否为(1, N, 2)。2. 在填充前对坐标进行裁剪pts[:, :, 0] np.clip(pts[:, :, 0], 0, width-1);pts[:, :, 1] np.clip(pts[:, :, 1], 0, height-1)。类别ID在Mask中不连续转换过程中跳过了某些未定义类别或者class_name_to_id字典的ID本身不连续。这通常不影响模型训练模型通过查找表读取ID但可能影响可视化。确保映射字典的ID从0开始连续递增。如果为了保留某些中间类别不连续也是可以的但需要在训练代码中正确处理。5. 可视化与质量检查生成Mask后绝对不能直接扔给模型训练。必须进行严格的质量检查。最有效的方法就是可视化。import matplotlib.pyplot as plt def visualize_mask_and_image(image_path, mask_path): 并排显示原始图像和对应的Mask标签。 img cv2.imread(image_path) img_rgb cv2.cvtColor(img, cv2.COLOR_BGR2RGB) # OpenCV读取为BGR转为RGB用于显示 mask cv2.imread(mask_path, cv2.IMREAD_GRAYSCALE) fig, axes plt.subplots(1, 2, figsize(12, 6)) axes[0].imshow(img_rgb) axes[0].set_title(Original Image) axes[0].axis(off) # 使用特定的colormap显示Mask让不同类别颜色区分明显 im axes[1].imshow(mask, cmaptab20) # tab20是一个有20种明显区别颜色的cmap axes[1].set_title(Segmentation Mask) axes[1].axis(off) plt.colorbar(im, axaxes[1], fraction0.046, pad0.04) # 添加颜色条以指示类别ID plt.show() # 打印基本信息 print(f图像尺寸: {img.shape}) print(fMask尺寸: {mask.shape}) print(fMask中存在的唯一类别ID: {np.unique(mask)}) # 使用示例 visualize_mask_and_image(path/to/original.jpg, path/to/mask.png)可视化能帮你一眼发现那些“隐藏”的问题Mask是否与物体边缘对齐是否有奇怪的像素块可能是坐标错误类别颜色是否与预期相符养成生成后必抽查的习惯能节省大量后期调试模型的时间。6. 集成到训练管道与格式考量生成的Mask最终要喂给深度学习框架。这里有几个关键格式考量文件命名与配对确保Mask文件与原始图像文件有明确的对应关系。上述代码生成的{json_filename}_mask.png是一种方式。更常见的做法是放在单独的masks或labels文件夹但保持与图像相同的文件名仅扩展名不同。读取与转换在PyTorch或TensorFlow的Dataset类中你需要同时读取图像和Mask。Mask通常以单通道灰度图读入然后可能需要将其转换为LongTensorPyTorch或int32TensorFlow类型的标签。# PyTorch Dataset 示例片段 import torch from torch.utils.data import Dataset from PIL import Image class SegmentationDataset(Dataset): def __init__(self, img_dir, mask_dir, transformNone): self.img_dir img_dir self.mask_dir mask_dir self.transform transform self.img_names os.listdir(img_dir) # 假设图片和mask文件名相同 def __getitem__(self, idx): img_name self.img_names[idx] img_path os.path.join(self.img_dir, img_name) mask_path os.path.join(self.mask_dir, img_name.replace(.jpg, _mask.png)) # 根据命名规则调整 image Image.open(img_path).convert(RGB) mask Image.open(mask_path).convert(L) # L模式表示灰度 if self.transform: image self.transform(image) # 注意对mask的变换通常只用几何变换如裁剪、翻转不能用颜色变换 mask self.transform(mask) # 将PIL Image或Tensor转换为LongTensor mask torch.from_numpy(np.array(mask, dtypenp.int64)).long() return image, mask类别平衡检查在批量转换后建议统计一下每个类别在数据集中所占的像素比例。如果某个类别如“背景”占据了绝大多数像素模型可能会倾向于忽略小物体。这时就需要考虑使用加权损失函数如torch.nn.CrossEntropyLoss的weight参数或过采样策略。整个从JSON到Mask的转换流程虽然只是语义分割项目中的一个预处理环节但其稳定性和准确性是项目成功的基石。我个人的经验是在这个阶段多花一些时间构建稳健的脚本、建立严格的质量检查流程远比在模型训练陷入僵局后再回头排查数据问题要高效得多。希望这份详细的拆解能帮你扫清障碍把精力更多地投入到更有创造性的模型设计和调优工作中去。
