3分钟搞定Labelme到VOC格式转换：labelme2voc.py工具全方位教程

你是否还在为图像标注数据格式转换而头疼？从Labelme标注的JSON文件到目标检测/分割常用的VOC格式，手动处理不仅耗时还容易出错。本文将带你掌握labelme2voc.py工具的全部用法，从基础转换到高级参数配置，让数据预处理效率提升10倍。读完本文你将学会：VOC格式核心构成、3步完成格式转换、常见错误排查以及高级应用技巧。

什么是VOC格式

VOC（Visual Object Classes）格式是PASCAL VOC挑战赛定义的一种图像标注数据格式，广泛应用于目标检测、图像分割等计算机视觉任务。它主要包含JPEGImages（原始图像）、Annotations（XML标注文件）和SegmentationClass/SegmentationObject（分割掩码）等目录结构。Labelme作为一款流行的图像标注工具，支持多边形、矩形等多种标注类型，而labelme2voc.py则是连接Labelme标注结果与VOC格式的桥梁工具。

项目中提供了多个VOC格式转换示例，涵盖边界框检测、实例分割和语义分割等任务：

• 边界框检测示例：examples/bbox_detection/
• 实例分割示例：examples/instance_segmentation/
• 语义分割示例：examples/semantic_segmentation/

准备工作

在开始转换前，需要确保你的环境中已安装Labelme及相关依赖。如果尚未安装，可以通过以下命令获取项目源码并安装：

git clone https://gitcode.com/gh_mirrors/la/labelme
cd labelme
pip install -e .

转换工具需要的核心文件包括：

• 标注工具：labelme/app.py
• 边界框转换脚本：examples/bbox_detection/labelme2voc.py
• 实例分割转换脚本：examples/instance_segmentation/labelme2voc.py
• 标签定义文件：examples/bbox_detection/labels.txt

快速开始：3步完成边界框检测数据转换

第1步：使用Labelme标注图像

首先使用Labelme对图像进行标注。以边界框检测为例，可以使用以下命令启动标注工具：

labelme examples/bbox_detection/data_annotated --labels examples/bbox_detection/labels.txt --nodata --autosave

标注界面如下所示，你可以使用矩形工具标注目标物体：

标注完成后，每个图像会生成一个对应的JSON文件，如examples/bbox_detection/data_annotated/2011_000003.json。

第2步：执行格式转换

使用labelme2voc.py脚本将标注结果转换为VOC格式：

python examples/bbox_detection/labelme2voc.py examples/bbox_detection/data_annotated examples/bbox_detection/data_dataset_voc --labels examples/bbox_detection/labels.txt

转换工具会自动创建VOC格式的目录结构，并生成以下文件：

• JPEGImages：examples/bbox_detection/data_dataset_voc/JPEGImages/
• Annotations：examples/bbox_detection/data_dataset_voc/Annotations/
• 可视化结果：examples/bbox_detection/data_dataset_voc/AnnotationsVisualization/

第3步：验证转换结果

转换完成后，可以查看生成的VOC格式文件。以下是原始图像和转换后的标注可视化结果对比：

图1：原始图像（左）与边界框标注可视化结果（右）

XML标注文件示例（examples/bbox_detection/data_dataset_voc/Annotations/2011_000003.xml）包含了图像尺寸、边界框坐标等信息，结构如下：

<annotation>
  <folder></folder>
  <filename>2011_000003.jpg</filename>
  <database></database>
  <annotation></annotation>
  <image></image>
  <size>
    <height>375</height>
    <width>500</width>
    <depth>3</depth>
  </size>
  <segmented></segmented>
  <object>
    <name>aeroplane</name>
    <pose></pose>
    <truncated></truncated>
    <difficult></difficult>
    <bndbox>
      <xmin>100</xmin>
      <ymin>100</ymin>
      <xmax>400</xmax>
      <ymax>300</ymax>
    </bndbox>
  </object>
</annotation>

高级用法：参数配置与定制化转换

labelme2voc.py提供了多种参数选项，以满足不同场景的转换需求。以下是主要参数说明：

参数	作用	示例
--labels	指定标签定义文件	--labels labels.txt
--noviz	禁用可视化结果生成	--noviz
--nonpy	不生成.npy格式掩码文件	--nonpy
--noobject	不生成实例分割相关文件	--noobject

实例分割转换示例

对于实例分割任务，可以使用实例分割专用的labelme2voc.py脚本：

python examples/instance_segmentation/labelme2voc.py examples/instance_segmentation/data_annotated examples/instance_segmentation/data_dataset_voc --labels examples/instance_segmentation/labels.txt

该脚本会生成语义分割和实例分割的掩码文件：

• 语义分割掩码：examples/instance_segmentation/data_dataset_voc/SegmentationClass/
• 实例分割掩码：examples/instance_segmentation/data_dataset_voc/SegmentationObject/
• 掩码可视化：examples/instance_segmentation/data_dataset_voc/SegmentationClassVisualization/

以下是语义分割掩码的可视化结果：

图2：原始图像（左）与语义分割可视化结果（右）

视频标注转换

项目还提供了视频标注转换示例，可以处理序列图像的标注结果：

python examples/video_annotation/labelme2voc.py examples/video_annotation/data_annotated examples/video_annotation/data_dataset_voc --labels examples/video_annotation/labels.txt

视频标注转换示例：examples/video_annotation/

常见问题与解决方案

问题1：转换时提示"Label not found in labels.txt"

这通常是因为标注中使用的标签没有在labels.txt中定义。解决方法是确保所有标注标签都已在标签文件中声明，标签文件格式示例：examples/bbox_detection/labels.txt。

问题2：生成的XML文件缺少目标信息

如果标注时使用了非矩形形状（如多边形），在边界框转换脚本中会被跳过。可以在输出日志中看到类似"Skipping shape: label=xxx, shape_type=polygon"的提示。解决方法是使用对应的分割转换脚本，如实例分割的labelme2voc.py。

问题3：中文标签显示乱码

确保标签文件使用UTF-8编码保存，并且转换环境支持中文显示。Labelme的配置文件labelme/config/default_config.yaml中可以设置字体相关参数。

总结与扩展

通过labelme2voc.py工具，我们可以轻松实现Labelme标注结果到VOC格式的转换，为后续的模型训练铺平道路。项目中还提供了其他实用工具，如转换为COCO格式的labelme2coco.py，以及视频标注工具examples/video_annotation/。

掌握这些工具的使用，将极大提高你的数据预处理效率。如果你在使用过程中遇到问题，可以参考项目官方教程examples/tutorial/README.md或查看源码实现examples/bbox_detection/labelme2voc.py进行深入学习。

希望本文对你有所帮助，祝你的计算机视觉项目顺利进行！