Labelme JSON转Mask：语义分割数据预处理核心技术与实战

1. 项目概述：从标注文件到像素级掩码的转换

在计算机视觉，特别是语义分割任务中，我们经常遇到一个看似简单却至关重要的环节：如何将标注工具（如Labelme）生成的JSON文件，转换成模型训练所需的Mask（掩码）图像。这不仅是数据预处理的第一步，更是决定模型能否“看懂”我们标注内容的关键。很多新手在拿到一个标注好的数据集时，面对一堆.json文件和原始图片，往往会感到无从下手。这个转换过程，本质上就是将人类可读的、结构化的标注信息，翻译成计算机视觉模型能够直接处理的、像素级的语义标签图。

我处理过大量来自遥感、医疗影像、自动驾驶等领域的语义分割数据，深知这个环节的痛点。一个标注文件里可能包含几十个甚至上百个多边形（polygon），每个多边形对应一个物体实例或一个语义类别。JSON文件记录了这些多边形的顶点坐标，但模型需要的是一个和原图尺寸相同、每个像素点都有一个类别ID（或实例ID）的矩阵。手动绘制？那是不可能的。我们需要一个自动化、可靠且高效的转换脚本。

这个过程的核心价值在于“桥梁”作用。它连接了标注人员的劳动成果（JSON）和深度学习模型的“食物”（Mask）。如果这座桥没搭好，标注得再精细也是白费功夫。无论是使用经典的U-Net，还是更现代的Transformer-based分割网络，如SegFormer或Mask2Former，它们的数据加载器（DataLoader）都期望输入是图像和对应的Mask对。因此，掌握JSON转Mask的技能，是进入语义分割实战领域的必备基础。接下来，我将拆解这个过程中的每一个技术细节、常见陷阱以及我的实战心得。

2. 核心原理与数据结构解析

要理解转换过程，首先必须吃透Labelme生成的JSON文件结构。这不是一个黑盒，它的设计直接决定了我们如何解析。

2.1 Labelme JSON文件结构深度解读

一个典型的Labelme JSON文件，其核心是一个嵌套的字典结构。我们可以把它想象成一棵“树”：

{ "version": "5.1.1", "flags": {}, "shapes": [ { "label": "car", "points": [[x1, y1], [x2, y2], ...], // 多边形顶点坐标 "group_id": null, "shape_type": "polygon", "flags": {} }, { "label": "person", "points": [[x1, y1], [x2, y2], ...], "group_id": null, "shape_type": "polygon", "flags": {} } ], "imagePath": "example.jpg", "imageData": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", // Base64编码的原图数据（可选） "imageHeight": 600, "imageWidth": 800 }

• shapes: 这是文件的灵魂，是一个列表，包含了所有标注的形状。每个形状是一个字典。
  • label: 字符串，表示该形状所属的类别，如“car”、“road”、“building”。这是语义信息的关键。
  • points: 列表的列表，存储了多边形每个顶点的[x, y]坐标。坐标是相对于图像左上角(0,0)的像素位置。这里有一个极易出错的点：points中的坐标是(x, y)，即（列，行），而在使用OpenCV或NumPy数组时，我们通常用(row, column)或(height, width)来索引。在转换时，需要特别注意坐标轴的对应关系，否则画出来的多边形会是错的。
  • shape_type: 通常是"polygon"，也可能是"rectangle"、"circle"等。对于语义分割，polygon是最常见的。
  • group_id: 如果为同一个物体的不同部分（如被遮挡的汽车）分配了相同的group_id，则可用于实例分割。在纯语义分割中通常为null。
• imageHeight&imageWidth: 这两个值至关重要！它们定义了我们要创建的Mask画布的大小。绝对不能直接从同名图片读取尺寸，因为图片可能在被标注后经过压缩或裁剪，而JSON里记录的是标注时的原始尺寸。以JSON中的尺寸为准，是保证对齐的唯一准则。
• imageData: 这是原图经过Base64编码后的字符串。有了它，即使原图丢失，也能从JSON中恢复图片。但在实际生产流程中，我们通常直接读取磁盘上的原图文件，因为这个字段会让JSON文件变得非常庞大，不利于版本管理。

2.2 Mask图像的实质与生成逻辑

Mask图像，在语义分割的语境下，通常是一张单通道（Grayscale）的8位或16位图像。图像中的每一个像素值，不再代表颜色强度，而是一个整数标签（Label ID）。

• 像素值 = 类别ID: 例如，我们可以定义：0代表背景（Background），1代表人（Person），2代表车（Car），3代表树（Tree）等等。这个映射关系需要我们自己维护一个字典，例如label_map = {"background": 0, "person": 1, "car": 2, "tree": 3}。
• 生成逻辑：转换脚本的核心任务就是创建一个全零（背景）的矩阵，其尺寸为(imageHeight, imageWidth)。然后，遍历shapes列表中的每一个多边形：
  1. 根据label字段，从label_map中查找对应的类别ID。
  2. 将这个多边形points描述的区域，在Mask矩阵的对应位置上，填充为该类别ID。
• 重叠处理：这是语义分割标注中的一个关键问题。如果两个不同类别的多边形有重叠区域，后绘制的会覆盖先绘制的。这通常符合标注逻辑（前景物体覆盖背景）。但在实例分割或需要处理“空洞”（如汽车玻璃）时，逻辑会更复杂，可能涉及group_id和绘制顺序的精心安排。

注意：务必使用int类型存储类别ID。虽然最终保存为图像时（如PNG格式）会被转换为uint8，但在内存中计算时使用整数可以避免许多中间过程的类型错误。

3. 工具选型与实战环境搭建

工欲善其事，必先利其器。选择正确的工具库能事半功倍。

3.1 核心库：为什么是OpenCV、NumPy和PIL？

1. OpenCV (cv2): 它是多边形填充和图像操作的不二之选。cv2.fillPoly()函数能够高效地将一个多边形区域填充为指定颜色（即我们的类别ID）。其输入要求坐标点格式为np.array，且数据类型为np.int32。OpenCV在处理图像I/O和几何运算上速度极快，是计算机视觉领域的标准库。
2. NumPy: 整个Mask在内存中就是一个NumPy数组。我们需要用它来创建画布（np.zeros）、进行数组操作和类型转换。NumPy的广播和向量化操作是高性能计算的基石。
3. PIL/Pillow: 虽然OpenCV也能读写图片，但PIL在保存索引色图像（即我们的Mask）时更为直观和可靠。特别是当我们需要将Mask保存为PNG格式并确保颜色表（Palette）正确时，PIL是更好的选择。OpenCV保存单通道灰度图也很方便。

安装非常简单，使用pip即可：

pip install opencv-python numpy pillow

如果使用Anaconda环境，也可以通过conda安装，环境隔离性更好。

3.2 辅助工具：JSON解析与路径管理

• 内置json库: Python自带的json库完全够用，json.load()和json.loads()可以轻松将JSON文件读入为Python字典。
• pathlib: 这是现代Python处理文件路径的推荐方式。相比传统的os.path，pathlib的面向对象API更清晰、更安全，能自动处理不同操作系统的路径分隔符问题。
• tqdm: 当需要批量处理成百上千个JSON文件时，在循环外加上tqdm可以提供一个美观的进度条，让你对处理进度一目了然。

pip install tqdm

3.3 项目目录结构设计

一个清晰的项目结构是高效协作和代码可维护性的基础。我建议采用如下结构：

semantic_segmentation_data/ ├── raw_images/ # 存放原始图像数据集 │ ├── image1.jpg │ ├── image2.jpg │ └── ... ├── labelme_annotations/ # 存放Labelme标注的JSON文件 │ ├── image1.json │ ├── image2.json │ └── ... ├── generated_masks/ # 脚本输出，存放生成的Mask图像 │ ├── image1_mask.png │ ├── image2_mask.png │ └── ... ├── label_map.json # 自定义的 类别名 -> ID 映射文件 └── json_to_mask.py # 核心转换脚本

这样设计的好处：输入（原图、JSON）、输出（Mask）、配置（label_map）和代码完全分离。无论是自己回顾，还是交给同事或实习生继续处理，都能立刻理解。

4. 核心转换脚本的逐行实现与详解

理论说得再多，不如一行代码。下面我将展示一个健壮、可配置的转换脚本，并逐段解释其设计意图和注意事项。

4.1 定义类别映射与参数配置

首先，我们需要一个明确的类别映射。我强烈建议将其放在一个独立的配置文件（如label_map.json）中，而不是硬编码在脚本里。

label_map.json内容示例：

{ "_background_": 0, "road": 1, "sidewalk": 2, "building": 3, "car": 4, "vegetation": 5 }

注意，我添加了一个"_background_"类别，并赋予ID 0。这是一个好习惯，因为所有未被任何多边形覆盖的像素，自然就是背景。在脚本中，我们会先创建一个全0的画布。

在Python脚本中，我们这样配置路径和参数：

import json import cv2 import numpy as np from pathlib import Path from tqdm import tqdm # ====== 用户配置区域 ====== # 1. 定义路径 json_dir = Path("./labelme_annotations") # JSON文件所在目录 image_dir = Path("./raw_images") # 原始图像目录（用于获取图片名，非必须） output_dir = Path("./generated_masks") # Mask输出目录 output_dir.mkdir(parents=True, exist_ok=True) # 自动创建输出目录 # 2. 加载类别映射 with open('label_map.json', 'r') as f: label_map = json.load(f) # 现在label_map是一个字典，如 {"road": 1, ...} # 3. 定义无效标签的处理方式（可选） # 如果JSON中出现label_map中不存在的类别，是报错、忽略还是归为某一类？ # 这里选择忽略并打印警告 ignore_unknown = True unknown_label_id = 0 # 如果选择归为某一类，则指定ID，例如归为背景

4.2 核心转换函数的编写

这是脚本的心脏。我们将转换逻辑封装成一个函数，便于复用和测试。

def json_to_mask(json_path, label_map, img_height, img_width): """ 将单个Labelme JSON文件转换为Mask numpy数组。 参数: json_path: Path对象，指向JSON文件。 label_map: 字典，类别名到类别ID的映射。 img_height: 整数，Mask的高度。 img_width: 整数，Mask的宽度。 返回: mask: NumPy数组，形状为 (img_height, img_width)， dtype=np.uint8。 """ # 1. 创建全零画布（背景） mask = np.zeros((img_height, img_width), dtype=np.uint8) # 2. 读取JSON数据 with open(json_path, 'r', encoding='utf-8') as f: data = json.load(f) # 3. 遍历所有标注形状 for shape in data['shapes']: label_name = shape['label'] points = shape['points'] # 格式: [[x1, y1], [x2, y2], ...] # 3.1 获取当前形状的类别ID if label_name in label_map: class_id = label_map[label_name] else: # 处理未知类别 if ignore_unknown: print(f"警告: 在文件 {json_path.name} 中发现未知标签 '{label_name}'，已忽略。") continue else: class_id = unknown_label_id print(f"警告: 在文件 {json_path.name} 中发现未知标签 '{label_name}'，已归为ID {class_id}。") # 3.2 将点列表转换为OpenCV需要的格式 # points中的每个点是 [x, y]，需要转换为NumPy数组，并指定为整数类型。 # 注意：OpenCV的fillPoly要求数组形状为 (n_points, 1, 2)，且dtype=np.int32。 pts = np.array(points, dtype=np.int32) # 形状: (n, 2) pts = pts.reshape((-1, 1, 2)) # 重塑为: (n, 1, 2) # 3.3 使用OpenCV填充多边形 # cv2.fillPoly会在原图上操作，将pts多边形内部填充为class_id颜色。 # 这里mask是单通道图，所以填充值就是标量class_id。 cv2.fillPoly(mask, [pts], color=class_id) return mask

关键点解析：

• dtype=np.uint8: 对于类别数少于256的语义分割任务，8位无符号整数足够。如果类别超过255，需要使用np.uint16。
• 坐标转换 (pts.reshape): 这是最容易出错的一步。cv2.fillPoly接受的参数是一个“包含多边形顶点列表的列表”，即[polygon1, polygon2, ...]，其中每个polygon是一个形状为(n, 1, 2)的数组。即使我们只画一个多边形，也要用[pts]把它包起来。
• 填充顺序:cv2.fillPoly是“覆盖式”的。后绘制的多边形会覆盖先绘制的。这符合大多数语义分割标注的预期（前面的物体会遮挡后面的）。

4.3 批量处理与主流程控制

单个文件的转换函数写好后，我们需要一个主函数来组织批量处理流程。

def process_all_jsons(json_dir, output_dir, label_map): """ 批量处理目录下所有JSON文件。 """ # 获取所有json文件路径 json_paths = list(json_dir.glob("*.json")) if not json_paths: print(f"在目录 {json_dir} 中未找到任何JSON文件。") return print(f"找到 {len(json_paths)} 个JSON文件，开始转换...") # 使用tqdm显示进度条 for json_path in tqdm(json_paths, desc="Processing JSONs"): try: # 1. 从JSON中读取图像尺寸（这是最可靠的方式） with open(json_path, 'r', encoding='utf-8') as f: data = json.load(f) img_h = data['imageHeight'] img_w = data['imageWidth'] # 2. 调用核心函数生成Mask数组 mask_array = json_to_mask(json_path, label_map, img_h, img_w) # 3. 构建输出文件名并保存 # 通常我们保留原图名称，加上后缀如 '_mask' 或 '_label' stem_name = json_path.stem # 去掉.json后缀的文件名 # 假设JSON文件名为 'image1.json'，则stem_name为 'image1' output_filename = f"{stem_name}_mask.png" output_path = output_dir / output_filename # 使用OpenCV保存Mask # cv2.imwrite(str(output_path), mask_array) # 简单保存 # 更推荐使用PIL保存，可以更好地控制PNG压缩和色彩模式 from PIL import Image mask_image = Image.fromarray(mask_array, mode='L') # 'L' 表示8位灰度图 mask_image.save(output_path, format='PNG', optimize=True) # 可选：保存为彩色可视化图像（用于检查） # vis_path = output_dir / f"{stem_name}_vis.png" # color_mask = visualize_mask(mask_array, label_map) # 需要自定义可视化函数 # cv2.imwrite(str(vis_path), color_mask) except KeyError as e: print(f"错误: 文件 {json_path.name} 缺少关键字段 {e}，已跳过。") except Exception as e: print(f"处理文件 {json_path.name} 时发生未知错误: {e}，已跳过。") import traceback traceback.print_exc() # 打印详细错误栈，便于调试 print("所有文件处理完成！") # 执行主函数 if __name__ == "__main__": process_all_jsons(json_dir, output_dir, label_map)

这里有几个非常重要的实战经验：

1. 异常处理：批量处理必须加入健壮的异常处理（try...except）。一个损坏的JSON文件不应该导致整个程序崩溃。我们捕获KeyError（缺少字段）和通用的Exception，打印错误信息后跳过该文件，保证其他文件能继续处理。
2. 尺寸来源：务必从JSON文件内的imageHeight和imageWidth读取尺寸，而不是去读同名的图片文件。这是保证Mask和原图空间对齐的生命线。
3. 输出格式：保存为PNG格式。PNG是无损压缩，非常适合保存Mask这类索引图像。避免使用JPG，因为JPG的有损压缩会严重破坏Mask的边界和类别值。
4. 文件命名：保持输出Mask文件名与原始图片或JSON文件的关联性至关重要。通常采用{原图基名}_mask.png的格式，这样在后续构建数据集（如PyTorch的Dataset类）时，可以很容易地通过图片名找到对应的Mask。

5. 高级话题与常见问题深度排查

掌握了基础转换后，我们会遇到更复杂的需求和各种各样的“坑”。

5.1 处理多类别与实例重叠

在更复杂的场景中，比如实例分割或带有“空洞”的物体（甜甜圈、汽车车窗），简单的覆盖逻辑就不够了。

• 实例分割：Labelme的group_id字段就是为此设计的。同一个物体的不同部分（即使被遮挡成多个多边形）共享同一个group_id。在转换时，你需要为每个唯一的(label, group_id)对分配一个唯一的实例ID。通常做法是：语义ID + 实例偏移量。例如，所有“车”的语义ID是2，那么第一辆车实例ID为20001，第二辆为20002，以此类推。
• 空洞处理：对于有洞的多边形（如环形），Labelme本身不直接支持。一种变通方法是标注两个多边形：一个大的外圈和一个小的内圈，并赋予它们相同的label但不同的group_id（或通过绘制顺序）。在转换时，先画外圈填充ID，再在内圈位置填充背景ID（0）。这需要更精细的控制绘制顺序。

5.2 坐标系统与图像对齐的陷阱

这是错误的重灾区，务必反复检查。

• 坐标原点：图像处理中常见的坐标系有两个原点：左上角(0,0)和左下角(0,0)。Labelme、OpenCV、PIL、Matplotlib使用的坐标系并不完全相同。
  • Labelme: 使用左上角为原点(0,0)，x轴向右，y轴向下。
  • OpenCV (cv2): 同样使用左上角为原点。所以从Labelme的points直接给OpenCV用，在坐标系上是对齐的。
  • Matplotlib (plt.imshow): 默认原点在左下角。如果你用Matplotlib显示Mask发现上下颠倒，就是因为这个原因。需要设置plt.imshow(mask, origin='upper')。
• 验证对齐：生成Mask后，必须进行可视化验证。最直接的方法是用OpenCV或PIL将原图和Mask半透明叠加显示。

def check_alignment(image_path, mask_path): import cv2 img = cv2.imread(str(image_path)) mask = cv2.imread(str(mask_path), cv2.IMREAD_GRAYSCALE) # 将Mask转换为彩色以便叠加 colored_mask = cv2.applyColorMap(mask, cv2.COLORMAP_JET) # 将Mask二值化，只对非零区域进行叠加 _, binary_mask = cv2.threshold(mask, 0, 255, cv2.THRESH_BINARY) binary_mask = binary_mask.astype(bool) # 创建叠加图像 overlay = img.copy() overlay[binary_mask] = colored_mask[binary_mask] * 0.5 + overlay[binary_mask] * 0.5 cv2.imshow('Original', img) cv2.imshow('Mask', mask) cv2.imshow('Overlay', overlay) cv2.waitKey(0) cv2.destroyAllWindows()

运行这个检查函数，确保物体的轮廓和原图边缘完美贴合。

5.3 性能优化与大规模处理

当处理数万张高分辨率图像（如遥感影像）时，纯Python循环可能成为瓶颈。

• 向量化操作（有限）：cv2.fillPoly本身是高度优化的C++实现，瓶颈通常不在这里，而在JSON解析和循环开销。对于极大量数据，可以考虑：
• 并行处理：使用Python的multiprocessing模块或多线程（注意GIL限制）。将文件列表分块，交给多个进程同时处理。

  from multiprocessing import Pool def process_single(args): json_path, output_dir, label_map = args # ... 单个文件处理逻辑 ... return result if __name__ == '__main__': json_args = [(p, output_dir, label_map) for p in json_paths] with Pool(processes=4) as pool: # 使用4个进程 pool.map(process_single, json_args)

• 使用更快的JSON库：如orjson（Rust实现）或ujson，比标准库的json快数倍。
• 缓存label_map：确保它在内存中，不要每次处理都去读文件。

5.4 常见错误与排查清单

下表总结了转换过程中最常见的错误、原因和解决方法：

6. 集成到深度学习Pipeline

生成Mask不是终点，而是起点。接下来需要将其集成到训练流程中。

6.1 构建PyTorch Dataset

一个标准的PyTorch Dataset类，用于加载图像-Mask对。

import torch from torch.utils.data import Dataset from PIL import Image import torchvision.transforms as T class SegmentationDataset(Dataset): def __init__(self, image_dir, mask_dir, transform=None): self.image_dir = Path(image_dir) self.mask_dir = Path(mask_dir) self.transform = transform # 假设图片名为 image1.jpg, 对应Mask为 image1_mask.png # 收集所有图片文件路径 self.image_paths = sorted(list(self.image_dir.glob("*.jpg"))) # 根据实际格式调整 def __len__(self): return len(self.image_paths) def __getitem__(self, idx): img_path = self.image_paths[idx] # 根据约定构建Mask路径 mask_path = self.mask_dir / f"{img_path.stem}_mask.png" # 使用PIL打开，确保一致性 image = Image.open(img_path).convert("RGB") mask = Image.open(mask_path).convert("L") # 灰度模式 if self.transform: # 注意：对图像和Mask应用相同的空间变换（如裁剪、翻转） # 但颜色变换（如归一化）只应用于图像 image = self.transform(image) mask = self.transform(mask) # 对于Mask，transform应只包含几何变换 # 更精细的控制可能需要自定义transform else: # 至少转换为Tensor to_tensor = T.ToTensor() image = to_tensor(image) mask = torch.from_numpy(np.array(mask)).long() # Mask需要是Long类型 return image, mask

关键点：对图像和Mask进行数据增强（如随机翻转、旋转）时，必须确保两者同步变换。torchvision.transforms中的RandomHorizontalFlip等是随机的，需要将它们包装在同一个Compose里，或者使用albumentations库，它原生支持对图像和Mask进行同步增强。

6.2 验证数据一致性

在投入训练前，务必进行最终检查。

1. 类别平衡检查：统计所有Mask中每个类别ID的像素数量。这能帮你发现数据是否严重不平衡（例如90%都是背景）。

   import numpy as np from collections import Counter from pathlib import Path mask_dir = Path("./generated_masks") all_pixel_counts = Counter() for mask_file in mask_dir.glob("*.png"): mask = np.array(Image.open(mask_file)) unique, counts = np.unique(mask, return_counts=True) all_pixel_counts.update(dict(zip(unique, counts))) print("各类别像素统计:", all_pixel_counts)

2. 完整性检查：确保每个原图都有对应的Mask，并且没有多余的Mask文件。
3. 可视化抽查：随机选择一些样本，用叠加显示的方法肉眼检查，这是最后一道，也是最可靠的防线。

走到这一步，你的高质量语义分割数据集就已经准备就绪了。从杂乱的JSON标注到规整的Mask图像，再到可直接喂给模型的Dataset，这个过程虽然繁琐，但每一步的严谨都会在模型训练和最终效果上得到回报。记住，垃圾数据进，垃圾模型出。在数据预处理上多花一小时，可能在调参上节省一整天。