告别手动转换！用Python脚本一键将Labelme关键点标注转为YOLO格式（附完整代码）

告别手动转换用Python脚本一键将Labelme关键点标注转为YOLO格式附完整代码在计算机视觉项目中数据标注的格式转换往往是开发者最头疼的环节之一。特别是当项目涉及人体姿态估计、面部关键点检测等复杂任务时标注工作本身就耗时费力而不同框架之间的格式差异更让这个过程雪上加霜。想象一下这样的场景你已经在Labelme中精心标注了数百张图片的关键点信息每个JSON文件都包含了精确的坐标数据但YOLO模型训练却要求完全不同的TXT格式——手动转换不仅容易出错效率也极其低下。这就是为什么我们需要一个智能化的转换工具。本文将带你深入开发一个Python脚本它能自动解析Labelme生成的JSON标注文件精确提取关键点坐标和边界框信息并转换为YOLO姿态检测所需的标准化格式。更重要的是这个方案支持批量处理无论你有几十还是上万张标注都能一键完成转换。我们将从YOLO格式规范解析开始逐步构建转换脚本的核心逻辑最后分享实际项目中的优化技巧和常见问题解决方案。1. 理解YOLO姿态检测的数据格式要求在开始编写转换脚本前必须透彻理解目标格式的规范。YOLO对于姿态检测任务的数据标注有着严格而特殊的结构要求这与普通的物体检测有着显著区别。1.1 基础格式解析YOLO姿态检测的标注文件采用TXT文本格式每个图像对应一个同名文本文件。文件中的每一行代表图像中的一个对象实例包含以下关键信息class_id x_center y_center width height px1 py1 px2 py2 ... pxn pyn其中class_id整数类型表示对象的类别索引x_center, y_center边界框中心的归一化坐标0-1范围width, height边界框的归一化尺寸px1, py1, ..., pxn, pyn关键点的归一化坐标关键点坐标的归一化是转换过程中最容易出错的部分。与边界框的归一化不同关键点坐标是相对于整个图像宽度和高度进行归一化而不是相对于边界框。这意味着我们需要原始图像的尺寸信息才能正确计算。1.2 高级格式变体在实际项目中你可能会遇到YOLO格式的两种变体DIM2格式基础版0 0.45 0.32 0.12 0.23 0.44 0.31 0.46 0.33 ... 0.47 0.35DIM3格式带可见性标记0 0.45 0.32 0.12 0.23 0.44 0.31 2 0.46 0.33 1 ... 0.47 0.35 0可见性标记的取值含义0关键点不可见1关键点被遮挡2关键点清晰可见在医疗影像分析等专业领域DIM3格式尤为有用因为它可以记录关键点的可见性状态为模型提供更丰富的监督信息。1.3 配套YAML配置文件完整的YOLO姿态检测数据集还需要一个描述性的YAML文件通常命名为data.yaml其典型结构如下path: ../datasets/custom-pose train: images/train val: images/val test: kpt_shape: [17, 3] flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15] names: 0: person这个配置文件定义了数据集路径结构关键点数量和维度如17个关键点每个点3个值水平翻转时关键点的对应关系类别名称映射我们的转换脚本需要同时生成这个配套文件确保转换后的数据集可以直接用于YOLO训练。2. 解析Labelme的JSON标注结构Labelme作为一款流行的图像标注工具生成的JSON文件包含了丰富的标注信息。要准确转换到YOLO格式我们需要深入理解这些数据的组织方式。2.1 JSON文件的核心字段一个典型的Labelme标注JSON文件包含以下顶层字段{ version: 5.1.1, flags: {}, shapes: [ { label: person, points: [[x1, y1], [x2, y2]], group_id: null, shape_type: rectangle }, { label: keypoint, points: [[x, y]], group_id: 1, shape_type: point } ], imagePath: image_001.jpg, imageData: null, imageHeight: 1080, imageWidth: 1920 }其中最关键的是shapes数组它包含了所有的标注形状。对于姿态检测任务通常会包含一个shape_type为rectangle的边界框标注多个shape_type为point的关键点标注注意Labelme本身不强制关键点与边界框的关联关系这需要通过group_id字段或标注顺序来推断。在实际项目中清晰的标注规范至关重要。2.2 关键点与边界框的关联在转换过程中最大的挑战是如何正确关联关键点与它们所属的边界框。Labelme提供了两种可能的机制group_id匹配属于同一对象的标注共享相同的group_id值标注顺序依赖假设第一个矩形框对应后续的所有关键点直到下一个矩形框出现我们的脚本需要处理这两种情况以下是对应的处理逻辑def associate_keypoints(shapes): objects [] current_obj None for shape in shapes: if shape[shape_type] rectangle: if current_obj is not None: objects.append(current_obj) current_obj { bbox: shape[points], keypoints: [] } elif shape[shape_type] point and current_obj is not None: current_obj[keypoints].extend(shape[points]) if current_obj is not None: objects.append(current_obj) return objects这个函数将原始的shapes数组转换为更结构化的对象列表每个对象包含一个边界框和对应的多个关键点。2.3 图像尺寸的重要性Labelme的JSON文件中直接包含了imageHeight和imageWidth字段这是我们进行坐标归一化必不可少的参数。但在实际应用中需要注意某些Labelme版本可能不自动包含这些字段当这些字段缺失时我们需要从图像文件直接读取尺寸信息图像路径可能使用相对路径或绝对路径需要正确处理在脚本中我们添加了健壮性检查def get_image_dimensions(json_data, image_dir): if imageHeight in json_data and imageWidth in json_data: return json_data[imageWidth], json_data[imageHeight] image_path Path(image_dir) / json_data[imagePath] with Image.open(image_path) as img: return img.size这种双重检查机制确保了在各种情况下都能获取正确的图像尺寸。3. 构建Python转换脚本的核心逻辑现在我们已经理解了两种格式的细节可以开始构建转换脚本的核心部分。这个脚本需要完成三个主要任务解析Labelme的JSON文件执行坐标转换和归一化生成YOLO格式的TXT文件和配套YAML3.1 脚本整体架构我们采用模块化设计将功能分解为多个函数import json import os from pathlib import Path from PIL import Image import yaml def convert_labelme_to_yolo( json_dir: str, output_dir: str, image_dir: str, class_mapping: dict, kpt_shape: list, flip_idx: list None ): 主转换函数 # 创建输出目录 os.makedirs(output_dir, exist_okTrue) # 处理每个JSON文件 for json_file in Path(json_dir).glob(*.json): with open(json_file, r) as f: data json.load(f) # 获取图像尺寸 img_width, img_height get_image_dimensions(data, image_dir) # 解析并关联标注 objects parse_labelme_objects(data[shapes]) # 转换为YOLO格式 yolo_lines [] for obj in objects: line convert_object( obj, img_width, img_height, class_mapping ) yolo_lines.append(line) # 写入输出文件 output_path Path(output_dir) / f{json_file.stem}.txt with open(output_path, w) as f: f.write(\n.join(yolo_lines)) # 生成YAML配置文件 generate_yaml_config( json_dir, output_dir, class_mapping, kpt_shape, flip_idx )3.2 坐标转换的关键算法坐标转换是脚本的核心算法需要精确处理以下计算边界框中心点计算边界框宽度和高度计算所有坐标的归一化关键点与边界框的对应关系def convert_object(obj, img_width, img_height, class_mapping): 将单个对象转换为YOLO格式行 # 解析边界框 (x1, y1), (x2, y2) obj[bbox] # 计算归一化边界框参数 x_center ((x1 x2) / 2) / img_width y_center ((y1 y2) / 2) / img_height width abs(x2 - x1) / img_width height abs(y2 - y1) / img_height # 获取类别ID class_id class_mapping.get(obj[label], 0) # 处理关键点 kpt_str for x, y in obj[keypoints]: x_norm x / img_width y_norm y / img_height kpt_str f {x_norm:.6f} {y_norm:.6f} # 组合成YOLO格式行 return f{class_id} {x_center:.6f} {y_center:.6f} {width:.6f} {height:.6f}{kpt_str}提示使用.6f格式化浮点数可以确保足够的精度同时避免科学计数法表示这是YOLO训练所要求的格式。3.3 批量处理与进度反馈当处理大量文件时我们需要为用户提供进度反馈。使用tqdm库可以轻松添加进度条from tqdm import tqdm # 在主函数中修改循环 for json_file in tqdm( list(Path(json_dir).glob(*.json)), descConverting JSON files ): # 转换逻辑...此外我们还应该添加错误处理机制跳过损坏或格式不正确的文件而不是让整个脚本失败try: with open(json_file, r) as f: data json.load(f) # 验证必要字段 if shapes not in data or imagePath not in data: raise ValueError(Invalid Labelme JSON structure) # 继续处理... except Exception as e: print(fSkipping {json_file.name}: {str(e)}) continue4. 高级功能与实战优化基础转换功能实现后我们可以添加一些高级特性来提升脚本的实用性和健壮性。4.1 支持自定义关键点配置不同的项目可能需要不同数量和配置的关键点。我们可以通过外部配置文件来实现灵活性# keypoints_config.yaml face_keypoints: kpt_shape: [68, 2] flip_idx: [...] # 面部关键点的对称关系 human_pose: kpt_shape: [17, 3] flip_idx: [0, 2, 1, 4, 3, 6, 5, 8, 7, 10, 9, 12, 11, 14, 13, 16, 15]然后在脚本中加载配置def load_keypoints_config(config_path): with open(config_path, r) as f: config yaml.safe_load(f) return config # 使用方式 config load_keypoints_config(keypoints_config.yaml) convert_labelme_to_yolo(..., kpt_shapeconfig[human_pose][kpt_shape])4.2 可视化验证工具转换后我们需要验证结果是否正确。一个简单的可视化脚本可以帮助我们快速检查import cv2 import numpy as np def visualize_yolo_annotation(image_path, label_path, class_names): image cv2.imread(str(image_path)) height, width image.shape[:2] with open(label_path, r) as f: lines f.readlines() for line in lines: parts line.strip().split() class_id int(parts[0]) x_center float(parts[1]) * width y_center float(parts[2]) * height box_width float(parts[3]) * width box_height float(parts[4]) * height # 绘制边界框 x1 int(x_center - box_width/2) y1 int(y_center - box_height/2) x2 int(x_center box_width/2) y2 int(y_center box_height/2) cv2.rectangle(image, (x1, y1), (x2, y2), (0, 255, 0), 2) # 绘制关键点 for i in range(5, len(parts), 2): x float(parts[i]) * width y float(parts[i1]) * height cv2.circle(image, (int(x), int(y)), 3, (0, 0, 255), -1) cv2.imshow(Verification, image) cv2.waitKey(0)4.3 性能优化技巧当处理数千个标注文件时性能变得重要。以下是几个优化建议并行处理使用多进程加速from multiprocessing import Pool def process_file(json_file): # 单个文件的处理逻辑 pass with Pool(processesos.cpu_count()) as pool: list(tqdm( pool.imap(process_file, Path(json_dir).glob(*.json)), totallen(list(Path(json_dir).glob(*.json))) ))内存优化避免同时加载所有文件缓存机制对于大型数据集缓存已经处理过的文件4.4 常见问题解决方案在实际项目中我们可能会遇到以下典型问题问题1关键点与边界框不匹配检查Labelme标注时是否使用了group_id确认标注顺序是否符合预期添加验证步骤检查关键点是否在边界框内问题2坐标归一化错误确认使用的是图像尺寸而不是边界框尺寸进行归一化检查图像尺寸读取是否正确验证归一化后的值是否在0-1范围内问题3YAML配置文件不完整确保包含所有必要字段检查路径是否使用正斜杠(/)而不是反斜杠()验证关键点形状与标注数据是否一致# 完整的YAML生成函数示例 def generate_yaml_config( json_dir, output_dir, class_mapping, kpt_shape, flip_idxNone ): config { path: str(Path(json_dir).parent), train: images/train, val: images/val, test: None, kpt_shape: kpt_shape, names: {v: k for k, v in class_mapping.items()} } if flip_idx is not None: config[flip_idx] flip_idx with open(Path(output_dir) / data.yaml, w) as f: yaml.dump(config, f, sort_keysFalse)在医疗影像分析项目中这个脚本帮助团队将标注转换时间从数小时缩短到几分钟同时消除了人为错误。一个特别有用的增强功能是添加了关键点可见性标记的支持这对于处理X光片等可能存在遮挡的影像至关重要。