Labelme标注数据转YOLOv5格式从原理到实践的完整指南在计算机视觉项目中数据标注是模型训练前的关键步骤。Labelme作为一款开源的图像标注工具因其简单易用而广受欢迎。然而当我们需要将Labelme生成的JSON标注文件转换为YOLOv5训练所需的TXT格式时往往会遇到一些技术障碍。本文将深入解析这一转换过程不仅提供完整的代码实现还会详细讲解背后的数学原理和实际应用中的注意事项。1. 理解数据格式差异在开始转换之前我们需要清楚地了解Labelme和YOLOv5使用不同数据格式的原因及其本质区别。Labelme生成的JSON文件采用绝对坐标系统记录了多边形或矩形框的顶点坐标。这种格式的优势在于保留了完整的几何信息便于人工检查和修改。一个典型的Labelme JSON文件包含以下关键信息{ version: 4.5.6, flags: {}, shapes: [ { label: person, points: [[100, 150], [300, 150], [300, 400], [100, 400]], shape_type: polygon } ], imagePath: example.jpg, imageHeight: 640, imageWidth: 480 }相比之下YOLOv5需要的TXT格式则采用相对坐标系统每个标注行包含class_id x_center y_center width height其中所有坐标值都是相对于图像宽度和高度的比例值范围在0到1之间。这种设计使YOLOv5模型能够处理不同尺寸的输入图像而无需调整标注数据。注意YOLO格式使用中心点坐标而非顶点坐标这是与许多其他目标检测框架的重要区别。2. 转换过程的核心算法从Labelme的JSON到YOLOv5的TXT格式转换核心在于坐标系的转换和归一化处理。让我们分解这一过程的数学原理。2.1 边界框提取对于矩形标注shape_type为rectangleLabelme通常存储两个对角点的坐标。我们需要先确定边界框的四个极值x_min min(points[0][0], points[1][0]) y_min min(points[0][1], points[1][1]) x_max max(points[0][0], points[1][0]) y_max max(points[0][1], points[1][1])对于多边形标注shape_type为polygon则需要遍历所有顶点找出最小和最大的x、y值x_coords [p[0] for p in points] y_coords [p[1] for p in points] x_min, x_max min(x_coords), max(x_coords) y_min, y_max min(y_coords), max(y_coords)2.2 坐标归一化获取绝对坐标的边界框后我们需要将其转换为YOLO格式的相对坐标。转换公式如下x_center (x_min x_max) / (2 * image_width) y_center (y_min y_max) / (2 * image_height) width (x_max - x_min) / image_width height (y_max - y_min) / image_height这一转换确保了无论原始图像尺寸如何变化标注数据都能保持一致性。以下是Python实现def xyxy2xywh(size, box): image_width, image_height size x_min, y_min, x_max, y_max box x_center (x_min x_max) / 2 / image_width y_center (y_min y_max) / 2 / image_height width (x_max - x_min) / image_width height (y_max - y_min) / image_height return (x_center, y_center, width, height)3. 完整转换代码实现基于上述原理我们开发了一个健壮的转换脚本支持批量处理和多类别转换。以下是完整的代码实现import json import os from pathlib import Path import cv2 class Labelme2YOLOv5Converter: def __init__(self, class_mappingNone): 初始化转换器 :param class_mapping: 类别名称到ID的映射字典如 {person: 0, car: 1} self.class_mapping class_mapping or {} def convert_file(self, json_path, image_dir, output_dir): 转换单个JSON文件 :param json_path: JSON文件路径 :param image_dir: 图像文件目录 :param output_dir: 输出TXT目录 with open(json_path, r) as f: data json.load(f) image_path os.path.join(image_dir, data[imagePath]) image cv2.imread(image_path) if image is None: raise FileNotFoundError(f无法加载图像: {image_path}) height, width image.shape[:2] txt_lines [] for shape in data[shapes]: label shape[label] class_id self.class_mapping.get(label, -1) if class_id -1: continue points shape[points] if shape[shape_type] rectangle: x_coords [p[0] for p in points] y_coords [p[1] for p in points] x_min, x_max min(x_coords), max(x_coords) y_min, y_max min(y_coords), max(y_coords) else: x_coords [p[0] for p in points] y_coords [p[1] for p in points] x_min, x_max min(x_coords), max(x_coords) y_min, y_max min(y_coords), max(y_coords) x_center, y_center, w, h self.xyxy2xywh((width, height), (x_min, y_min, x_max, y_max)) txt_lines.append(f{class_id} {x_center:.6f} {y_center:.6f} {w:.6f} {h:.6f}) # 保存TXT文件 txt_filename os.path.splitext(data[imagePath])[0] .txt txt_path os.path.join(output_dir, txt_filename) os.makedirs(output_dir, exist_okTrue) with open(txt_path, w) as f: f.write(\n.join(txt_lines)) staticmethod def xyxy2xywh(size, box): 将绝对坐标转换为YOLO格式的相对坐标 width, height size x_min, y_min, x_max, y_max box x_center (x_min x_max) / 2 / width y_center (y_min y_max) / 2 / height w (x_max - x_min) / width h (y_max - y_min) / height return x_center, y_center, w, h def convert_folder(self, json_dir, image_dir, output_dir): 批量转换目录下的所有JSON文件 :param json_dir: JSON文件目录 :param image_dir: 图像文件目录 :param output_dir: 输出TXT目录 json_files [f for f in os.listdir(json_dir) if f.endswith(.json)] for json_file in json_files: try: self.convert_file( os.path.join(json_dir, json_file), image_dir, output_dir ) print(f成功转换: {json_file}) except Exception as e: print(f转换失败 {json_file}: {str(e)}) # 使用示例 if __name__ __main__: # 定义类别映射 CLASS_MAPPING { person: 0, car: 1, dog: 2 } # 初始化转换器 converter Labelme2YOLOv5Converter(CLASS_MAPPING) # 设置路径 JSON_DIR path/to/json_files IMAGE_DIR path/to/images OUTPUT_DIR path/to/output_txt # 执行转换 converter.convert_folder(JSON_DIR, IMAGE_DIR, OUTPUT_DIR)4. 实际应用中的优化技巧在实际项目中我们积累了一些优化转换过程的经验技巧4.1 多类别处理策略自动类别发现当类别较多时可以修改代码自动发现所有类别并生成映射def discover_classes(json_dir): classes set() for json_file in os.listdir(json_dir): if json_file.endswith(.json): with open(os.path.join(json_dir, json_file), r) as f: data json.load(f) for shape in data[shapes]: classes.add(shape[label]) return {name: idx for idx, name in enumerate(sorted(classes))}类别验证在转换前检查所有类别是否都有映射避免数据丢失missing_classes [shape[label] for shape in data[shapes] if shape[label] not in self.class_mapping] if missing_classes: print(f警告: 发现未映射的类别: {set(missing_classes)})4.2 性能优化对于大规模数据集可以采用以下优化措施并行处理使用Python的multiprocessing模块加速批量转换from multiprocessing import Pool def process_file(args): json_file, image_dir, output_dir, converter args try: converter.convert_file( os.path.join(json_dir, json_file), image_dir, output_dir ) return (json_file, True) except Exception as e: return (json_file, False, str(e)) # 在convert_folder方法中使用 with Pool(processes4) as pool: # 使用4个进程 args_list [(f, image_dir, output_dir, self) for f in json_files] results pool.map(process_file, args_list)增量处理记录已处理的文件避免重复工作processed_file os.path.join(output_dir, .processed_files.txt) def get_processed_files(): if os.path.exists(processed_file): with open(processed_file, r) as f: return set(f.read().splitlines()) return set() def update_processed_files(file_list): existing get_processed_files() with open(processed_file, a) as f: for file in file_list: if file not in existing: f.write(file \n) # 在convert_folder中调用 processed get_processed_files() json_files [f for f in os.listdir(json_dir) if f.endswith(.json) and f not in processed] update_processed_files([f for f in json_files])4.3 数据验证转换完成后建议进行数据验证以确保质量可视化检查编写脚本将YOLO格式标注绘制到图像上验证import matplotlib.pyplot as plt import matplotlib.patches as patches def visualize_yolo_annotation(image_path, txt_path, class_names): image cv2.imread(image_path) image cv2.cvtColor(image, cv2.COLOR_BGR2RGB) height, width image.shape[:2] fig, ax plt.subplots(1) ax.imshow(image) with open(txt_path, r) as f: for line in f: class_id, x, y, w, h map(float, line.strip().split()) # 转换回绝对坐标 x_abs x * width y_abs y * height w_abs w * width h_abs h * height # 计算矩形框左上角坐标 x_min x_abs - w_abs/2 y_min y_abs - h_abs/2 rect patches.Rectangle( (x_min, y_min), w_abs, h_abs, linewidth2, edgecolorr, facecolornone ) ax.add_patch(rect) label class_names[int(class_id)] if class_names else str(int(class_id)) ax.text(x_min, y_min-5, label, colorr, fontsize12) plt.show()统计检查生成标注统计报告def generate_stats_report(txt_dir, class_namesNone): class_counts {} total_boxes 0 for txt_file in os.listdir(txt_dir): if txt_file.endswith(.txt): with open(os.path.join(txt_dir, txt_file), r) as f: for line in f: class_id int(line.strip().split()[0]) class_counts[class_id] class_counts.get(class_id, 0) 1 total_boxes 1 print(f总标注框数: {total_boxes}) print(各类别分布:) for class_id, count in sorted(class_counts.items()): class_name class_names[class_id] if class_names else str(class_id) print(f {class_name}: {count} ({count/total_boxes:.1%}))5. 常见问题与解决方案在实际应用中我们总结了几个常见问题及其解决方法坐标越界问题现象转换后的x_center、y_center、w或h值超出[0,1]范围原因原始标注超出了图像边界解决方案在转换前对坐标进行裁剪def clip_coordinates(box, width, height): x_min, y_min, x_max, y_max box x_min max(0, min(x_min, width-1)) y_min max(0, min(y_min, height-1)) x_max max(0, min(x_max, width-1)) y_max max(0, min(y_max, height-1)) return (x_min, y_min, x_max, y_max)图像与JSON不匹配问题现象JSON中记录的imageHeight/imageWidth与实际图像尺寸不符解决方案优先使用实际图像尺寸# 在convert_file方法中替换 height, width image.shape[:2] # 替代 # height data[imageHeight] # width data[imageWidth]多对象标注处理现象一个JSON文件中包含多个对象的标注解决方案我们的完整代码已经支持每个shape会生成一行记录特殊形状处理现象Labelme支持circle、linestrip等特殊形状解决方案转换为边界框或扩展转换逻辑if shape[shape_type] circle: center_x, center_y shape[points][0] radius_x abs(shape[points][1][0] - center_x) radius_y abs(shape[points][1][1] - center_y) x_min, x_max center_x - radius_x, center_x radius_x y_min, y_max center_y - radius_y, center_y radius_y中文路径问题现象在Windows系统上可能遇到中文路径问题解决方案使用Pathlib处理路径from pathlib import Path image_path Path(image_dir) / data[imagePath] with open(image_path, rb) as f: bytes bytearray(f.read()) numpyarray np.asarray(bytes, dtypenp.uint8) image cv2.imdecode(numpyarray, cv2.IMREAD_UNCHANGED)