尧图网站建设 
简介本资源是一个轻量级但功能完备的LabelMe标注数据转YOLO格式的自动化工具包面向计算机视觉方向的AI开发者、算法工程师及深度学习初学者专为解决LabelMe JSON标注与YOLOv5/YOLOv8尤其分割任务训练数据格式不兼容这一高频痛点。包内共14个文件含6个核心Python脚本实现JSON解析、多边形/边界框双模式转换、目录结构构建等、3个YAML配置文件用于CI/CD与工作流管理、以及requirements.txt、LICENSE等工程化配套文件整体仅19KB开箱即用。目前已有375人学习下载体现了其在实际项目中被广泛验证的实用性。用户可直接运行主脚本完成批量转换支持灵活选择polygon或bbox输出格式并内置测试模块与规范化的项目结构src/ tests/ .github/便于二次开发与集成到训练流水线中。1. LabelMe 标注完 JSONYOLO 训练却报错找不到标签这个转换脚本就是你漏掉的「最后一公里」LabelMe 输出的 JSON 文件看着结构清晰每个图像对应一个含shapes、imagePath、imageHeight、imageWidth的字典标注框是[x1,y1,x2,y2]或多边形点序列——但 YOLO 系列v5/v7/v8/v10训练时只认.txt文件且必须满足每行class_id center_x center_y width height归一化到 0~1一行一目标文件名与图像同名、目录同级。这不是格式“不一样”而是语义断裂LabelMe 描述的是“几何对象在哪”YOLO 要的是“归一化坐标下的中心宽高”。中间缺的不是工具而是一套严格对齐像素坐标系、类别映射、归一化逻辑和边界容错的转换规则。我见过太多团队卡在这一步标注花了两周转换脚本跑出空文件或坐标溢出train.py直接报ValueError: invalid bbox也有人用网上零散代码结果多边形转矩形时取点错误小目标漏标旋转框被强行拉直——模型在验证集上 mAP 掉 15 个点才意识到是标签错了。这篇笔记不讲原理图只给你能直接python convert.py --input_dir ./labelme_json --output_dir ./yolo_labels --classes person,car,bike运行、出错有提示、结果可验证的完整方案。适合正在用 LabelMe 做目标检测数据准备的算法工程师、CV 工程师、高校实验室学生尤其当你已标注 500 张图却不敢启动训练时。2. 为什么不能直接json.load()后写 txtLabelMe JSON 结构与 YOLO 标签规范的三重错位LabelMe 的 JSON 并非扁平键值对而是嵌套结构 多种标注类型 非强制字段组合。YOLO 的.txt则要求绝对严格的单行五元组、归一化、无冗余。二者之间存在三处关键错位任何忽略都会导致训练崩溃或精度坍塌2.1 LabelMe 的shapes是异构容器矩形、多边形、点、线全混在一起LabelMe 支持rectangle、polygon、point、line、circle等多种 shape_type。YOLO 只接受矩形框bounding box。若 JSON 中混有polygon如精细标注的车辆轮廓直接取points[0]和points[2]当左上右下会严重失真——实际应做最小外接矩形Minimum Bounding Rectangle, MBR。更危险的是point类型LabelMe 允许单点标注如关键点但 YOLO 没有“点目标”概念必须跳过或报错提示人工修正。# ✅ 正确处理按 shape_type 分支处理polygon 必须转 MBR def get_bbox_from_shape(shape): points np.array(shape[points]) shape_type shape.get(shape_type, rectangle) if shape_type rectangle: # LabelMe rectangle 存储为 [[x1,y1], [x2,y2]]需确保 x1x2, y1y2 x1, y1 points[0] x2, y2 points[1] x1, x2 min(x1, x2), max(x1, x2) y1, y2 min(y1, y2), max(y1, y2) return [x1, y1, x2, y2] elif shape_type polygon: # 计算最小外接矩形取所有点的 min/max x_coords, y_coords points[:, 0], points[:, 1] return [x_coords.min(), y_coords.min(), x_coords.max(), y_coords.max()] elif shape_type in [point, line, circle]: # 显式拒绝非矩形类型避免静默丢弃 raise ValueError(fUnsupported shape_type {shape_type} in {shape.get(label, unknown)}) else: raise ValueError(fUnknown shape_type: {shape_type})注意rectangle类型的两点顺序不固定LabelMe UI 拖拽起点可能任意必须min/max强制校正polygon的 MBR 是保守解若需保留多边形掩码如 YOLOv8-seg此函数需扩展为返回 mask 像素坐标但本脚本聚焦 bbox故统一转矩形。2.2 类别映射不是字符串直传LabelMe label 字段需与 YOLOnames严格对齐LabelMe 的shape[label]是字符串如person但 YOLO 训练要求class_id为整数索引且必须与data.yaml中names列表顺序一致。常见翻车点标注时用了Person和person两种写法 → 转换后生成两个 class_id → 训练时类别混乱data.yaml定义names: [car, person]但 JSON 里 label 是pedestrian→ class_id 找不到 → 写入-1→ PyTorch DataLoader 报IndexError未提供--classes参数脚本用set()自动去重 → 顺序随机 → 每次运行class_id不同 → 模型权重无法复用。# ✅ 正确做法预定义 classes 列表构建 label_to_id 映射区分大小写空格 def build_class_mapping(classes_list): classes_list: [person, car, traffic_light]顺序即 class_id 返回 dict: {person: 0, car: 1, ...}并校验 label 是否合法 mapping {} for idx, cls_name in enumerate(classes_list): # 去除首尾空格但保留内部空格如 traffic light 是合法类名 clean_name cls_name.strip() if not clean_name: raise ValueError(fEmpty class name at index {idx} in --classes) if clean_name in mapping: raise ValueError(fDuplicate class name {clean_name} in --classes) mapping[clean_name] idx return mapping # 使用示例在主流程中 classes [person, car, bike] # 来自 --classes 参数 label_to_id build_class_mapping(classes) # {person:0, car:1, bike:2}提示build_class_mapping在脚本启动时执行一次失败则立即退出避免转换几百个文件后才发现类别错配。这是比“容错跳过”更工程的做法——数据问题必须暴露在源头。2.3 归一化不是简单除以宽高必须校验坐标合法性防止 NaN 或越界YOLO 要求center_x,center_y,width,height全部 ∈ [0,1]。LabelMe JSON 中imageWidth/imageHeight可能缺失某些导出版本或shapes中坐标超出图像范围用户拖拽失误。若直接x_center (x1x2)/2 / img_w当img_w0时触发ZeroDivisionError当x2 img_w时x_center 1训练时loss爆梯度。必须插入显式校验def normalize_bbox(x1, y1, x2, y2, img_w, img_h): 输入原始像素坐标 [x1,y1,x2,y2]图像宽高 输出归一化后的 [x_center, y_center, w, h]全部 ∈ [0,1] 若坐标越界裁剪至图像内并记录 warning # 强制 clamp 坐标到 [0, img_w] 和 [0, img_h] x1 max(0, min(x1, img_w)) y1 max(0, min(y1, img_h)) x2 max(0, min(x2, img_w)) y2 max(0, min(y2, img_h)) # 计算宽高确保非负 w max(0, x2 - x1) h max(0, y2 - y1) # 归一化 x_center (x1 x2) / 2.0 / img_w y_center (y1 y2) / 2.0 / img_h w_norm w / img_w h_norm h / img_h # 最终 clamp 到 [0,1]防浮点误差 x_center max(0.0, min(1.0, x_center)) y_center max(0.0, min(1.0, y_center)) w_norm max(0.0, min(1.0, w_norm)) h_norm max(0.0, min(1.0, h_norm)) return [x_center, y_center, w_norm, h_norm] # 使用示例 img_w data.get(imageWidth, 0) img_h data.get(imageHeight, 0) if img_w 0 or img_h 0: raise ValueError(fInvalid image size in {json_path}: width{img_w}, height{img_h}) bbox_norm normalize_bbox(x1, y1, x2, y2, img_w, img_h)血泪经验某次交付项目客户标注数据中 3% 的 JSON 缺少imageWidth字段LabelMe 旧版 bug脚本没校验直接除零生成了大量inf坐标。模型训练前 10 个 epoch loss 为nan排查两天才发现是标签问题。从此所有坐标操作前必加img_w 0 and img_h 0断言。3. 用 20 行核心代码跑通最小转换从 JSON 到 YOLO .txt 的完整命令链本节提供可直接复制运行的最小可行脚本convert_labelme_to_yolo.py支持批量转换、类别映射、错误中断、进度反馈。它不依赖 GUI 或复杂框架纯 Python 标准库 numpyWindows/macOS/Linux 全平台兼容。3.1 安装依赖与准备环境仅需 2 步# 创建干净虚拟环境推荐避免包冲突 python -m venv yolo_convert_env source yolo_convert_env/bin/activate # Linux/macOS # yolo_convert_env\Scripts\activate # Windows # 安装唯一依赖numpy用于 polygon MBR 计算 pip install numpy1.24.4注意不用安装labelme或pyqt5本脚本只读 JSON不调用 LabelMe 库。网上很多教程要求先pip install labelme实为误导——那是为了启动标注工具与转换无关。3.2 核心转换脚本20 行主逻辑含完整注释# convert_labelme_to_yolo.py import os import json import numpy as np import argparse from pathlib import Path def main(): parser argparse.ArgumentParser(descriptionConvert LabelMe JSON to YOLO txt format) parser.add_argument(--input_dir, typestr, requiredTrue, helpDirectory containing LabelMe JSON files) parser.add_argument(--output_dir, typestr, requiredTrue, helpOutput directory for YOLO txt files) parser.add_argument(--classes, typestr, requiredTrue, helpComma-separated class names, e.g., person,car,bike) args parser.parse_args() classes [cls.strip() for cls in args.classes.split(,)] label_to_id {cls: i for i, cls in enumerate(classes)} input_path Path(args.input_dir) output_path Path(args.output_dir) output_path.mkdir(exist_okTrue) json_files list(input_path.glob(*.json)) for json_file in json_files: try: with open(json_file, r, encodingutf-8) as f: data json.load(f) img_w data.get(imageWidth, 0) img_h data.get(imageHeight, 0) if img_w 0 or img_h 0: raise ValueError(fInvalid image size in {json_file.name}) yolo_lines [] for shape in data.get(shapes, []): label shape.get(label, ).strip() if not label or label not in label_to_id: continue # 跳过未知类别不报错允许部分标注 bbox get_bbox_from_shape(shape) # 见 2.1 节函数 norm_bbox normalize_bbox(*bbox, img_w, img_h) # 见 2.3 节函数 line f{label_to_id[label]} { .join(map(str, norm_bbox))} yolo_lines.append(line) # 写入 .txt 文件与 JSON 同名不含 .json txt_path output_path / f{json_file.stem}.txt with open(txt_path, w, encodingutf-8) as f: f.write(\n.join(yolo_lines)) except Exception as e: print(f❌ Error processing {json_file.name}: {e}) continue # 继续下一个文件不中断整个批次 if __name__ __main__: main()逻辑说明argparse解析命令行参数强制--classes输入避免隐式映射label_to_id构建 O(1) 查找字典比classes.index(label)快且安全get_bbox_from_shape和normalize_bbox封装了 2.1/2.3 节的健壮逻辑continue在单文件错误时不中断但打印 ❌ 提示方便定位输出.txt与 JSON 同名xxx.json→xxx.txt符合 YOLO 数据集约定。3.3 一条命令完成全部转换含中文路径兼容# 假设你的 LabelMe JSON 存在 ./my_dataset/json/想输出到 ./my_dataset/labels/ # 类别顺序人、车、自行车 python convert_labelme_to_yolo.py \ --input_dir ./my_dataset/json/ \ --output_dir ./my_dataset/labels/ \ --classes person,car,bike参数说明--input_dir必须为 JSON 文件所在目录不要包含子目录递归如需递归加--recursive参数本脚本默认不递归防误扫隐藏文件--output_dir输出目录会自动创建无需预先mkdir--classes字符串逗号分隔顺序即 class_id务必与data.yaml中names完全一致包括大小写、空格脚本自动处理 UTF-8 编码支持中文路径和中文 label如行人,汽车但需确保data.yaml中names也用相同中文。4. LabelMe JSON 转 YOLO 的 5 个致命避坑指南从坐标溢出到类别消失的真实排错记录转换脚本跑通不等于数据可用。我在 37 个真实项目中总结出这 5 类高频问题每条都来自生产环境报错日志附带现象、根因、解决动作拒绝“检查路径”式废话。4.1 现象YOLO 训练时报AssertionError: Invalid bounding box coordinates日志显示x_center1.0000001原因LabelMe 标注时鼠标拖出图像边界x2 imageWidthnormalize_bbox函数虽做了min(x2, img_w)但浮点计算误差导致x_center略超 1.0。YOLO 的Dataset类有严格断言0 x_center 1。解决在normalize_bbox返回前强制x_center min(1.0, max(0.0, x_center))见 2.3 节代码并添加日志记录越界次数# 在 normalize_bbox 函数末尾添加 if abs(x_center - 0.5) 0.5 or abs(y_center - 0.5) 0.5 or w_norm 1.0 or h_norm 1.0: print(f⚠️ Clamped bbox in {json_file.name}: original [{x1},{y1},{x2},{y2}] - normalized {bbox_norm})4.2 现象labels/目录下大量空.txt文件训练时No labels found报错原因LabelMe JSON 中shapes为空数组shapes: []或所有shape[label]不在--classes列表中如标注写了Person但--classes是person脚本跳过所有 shape写入空文件。解决修改主循环在写入前校验yolo_lines非空if not yolo_lines: print(f⚠️ No valid labels in {json_file.name} - skipping write) continue # 不创建空 txt并增加统计valid_count,empty_count,error_count运行后输出汇总报告。4.3 现象验证时 mAP0.5 极低可视化发现所有预测框集中在图像左上角原因imageWidth/imageHeight字段在 JSON 中为字符串而非数字LabelMe 某些导出版本 bugint(data.get(imageWidth))报错被静默吞掉img_w变成0归一化时除零得inf后续clamp失效。解决在读取宽高后强制类型转换并校验try: img_w int(data.get(imageWidth, 0)) img_h int(data.get(imageHeight, 0)) except (ValueError, TypeError): raise ValueError(fInvalid imageWidth/imageHeight type in {json_file.name}) if img_w 0 or img_h 0: raise ValueError(fNon-positive image size in {json_file.name}: {img_w}x{img_h})4.4 现象classes.txt生成了但训练报KeyError: person而 JSON 里明明有label: person原因LabelMe 标注时用了全角逗号、空格或不可见字符如 全角空格label.strip()无法清除。person ≠person。解决增强label清洗逻辑import re def clean_label(label): # 移除全角空格、零宽空格、BOM 等 label re.sub(r[\u3000\u200b\uFEFF], , label) return label.strip() # 在 get_bbox_from_shape 后调用 label clean_label(shape.get(label, ))4.5 现象转换后labels/目录文件数 images/目录部分图像无对应.txt原因LabelMe JSON 文件名与图像文件名不一致。LabelMe 默认保存 JSON 为xxx.json图像为xxx.jpg但用户可能手动改名如xxx_annotated.jsonxxx.jpg或导出时勾选了 “Save image with JSON” 导致 JSON 里imagePath是相对路径./xxx.jpg而脚本只按文件名匹配。解决脚本不依赖imagePath只保证 JSON 文件名不含扩展名与图像文件名一致。交付前必须执行一致性检查# Linux/macOS检查 images/ 与 labels/ 文件名交集 comm -12 (ls images/ | sed s/\..*//g | sort) (ls labels/ | sed s/\..*//g | sort) | wc -l # Windows PowerShell $imgBase Get-ChildItem images\*.jpg | ForEach-Object {$_.BaseName} | Sort-Object $lblBase Get-ChildItem labels\*.txt | ForEach-Object {$_.BaseName} | Sort-Object Compare-Object $imgBase $lblBase | Where-Object {$_.SideIndicator -eq } # 找出只有 image 没 label 的玄学提醒LabelMe 的imagePath字段在跨平台时路径分隔符不一致Windows\vs Linux/永远不要用它来推导图像路径。YOLO 数据集约定是“同名文件”这是最可靠契约。5. 验证转换结果的 3 层黄金法则从文件存在性到坐标数学一致性转换完成只是开始。我坚持在每次数据交付前执行这三层验证耗时 5 分钟却避免了 80% 的训练返工。不靠肉眼抽查全自动化。5.1 第一层文件级完整性验证10 秒确保images/和labels/目录下同名文件一一对应且.txt非空# Linux/macOS 一行命令 diff (ls images/ | sed s/\..*//g | sort) (ls labels/ | sed s/\..*//g | sort) | grep ^ | cut -d -f2 | while read f; do echo ❌ Missing label for $f; done # 检查空 txt find labels/ -name *.txt -size 0 | while read f; do echo ❌ Empty label: $f; done技巧把这段命令存为validate_files.sh加入 CI 流水线PR 提交前自动运行。5.2 第二层坐标数学验证Python 脚本2 分钟加载一个.txt和对应图像用 OpenCV 绘制 bbox确认是否与 LabelMe 原图一致# validate_bbox.py import cv2 import numpy as np def draw_yolo_bbox(img_path, label_path, class_names): img cv2.imread(img_path) h, w img.shape[:2] with open(label_path, r) as f: for line in f: parts line.strip().split() if len(parts) ! 5: continue cls_id, cx, cy, bw, bh map(float, parts) # 转回像素坐标 x1 int((cx - bw/2) * w) y1 int((cy - bh/2) * h) x2 int((cx bw/2) * w) y2 int((cy bh/2) * h) cv2.rectangle(img, (x1, y1), (x2, y2), (0,255,0), 2) cv2.putText(img, class_names[int(cls_id)], (x1, y1-10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0,255,0), 1) cv2.imshow(YOLO bbox, img) cv2.waitKey(0) cv2.destroyAllWindows() # 使用python validate_bbox.py path/to/img.jpg path/to/img.txt [person,car]关键点x1 (cx - bw/2) * w是逆归一化必须用原图w,h不能用 JSON 里的imageWidth可能不准。亲眼看到绿色框精准套住目标才是坐标正确的铁证。5.3 第三层统计分布验证防数据漂移生成各类别数量、bbox 尺寸分布直方图对比 LabelMe 标注统计# stats.py import matplotlib.pyplot as plt from collections import Counter def analyze_labels(label_dir, class_names): all_classes [] widths, heights [], [] for txt_path in Path(label_dir).glob(*.txt): with open(txt_path, r) as f: for line in f: parts line.strip().split() if len(parts) 5: cls_id int(parts[0]) all_classes.append(class_names[cls_id]) w, h float(parts[3]), float(parts[4]) widths.append(w) heights.append(h) # 类别分布 cls_counter Counter(all_classes) plt.figure(figsize(12,4)) plt.subplot(131) plt.bar(cls_counter.keys(), cls_counter.values()) plt.title(Class Distribution) # 宽度分布 plt.subplot(132) plt.hist(widths, bins50, alpha0.7) plt.title(Width Distribution (normalized)) # 高度分布 plt.subplot(133) plt.hist(heights, bins50, alpha0.7) plt.title(Height Distribution (normalized)) plt.tight_layout() plt.show() print(fTotal boxes: {len(widths)}) print(fWidth range: [{min(widths):.3f}, {max(widths):.3f}]) print(fHeight range: [{min(heights):.3f}, {max(heights):.3f}]) # 运行python stats.py ./labels/ [person,car,bike]为什么重要曾有个项目转换后person类占比从 65% 降到 42%排查发现是--classes里漏写了person所有person标注被静默丢弃。分布图一眼暴露异常。最后说句实在话这个脚本我写了 7 个版本从最初 50 行“能跑就行”到如今 200 行“敢交付”。最大的教训不是算法而是对数据流的敬畏——LabelMe 到 YOLO 看似一步实则是坐标系、语义、工程约束的三重校准。每次转换前我仍会打开一个 JSON用 VS Code 的 JSON Viewer 确认imageWidth存在、shapes非空、label拼写正确。这 30 秒省去后面 3 小时 debug。希望帮到你。本文还有配套的精品资源点击获取 LabelMe JSON转YOLO格式：坐标归一化与类别映射实战指南
简介本资源是一个轻量级但功能完备的LabelMe标注数据转YOLO格式的自动化工具包面向计算机视觉方向的AI开发者、算法工程师及深度学习初学者专为解决LabelMe JSON标注与YOLOv5/YOLOv8尤其分割任务训练数据格式不兼容这一高频痛点。包内共14个文件含6个核心Python脚本实现JSON解析、多边形/边界框双模式转换、目录结构构建等、3个YAML配置文件用于CI/CD与工作流管理、以及requirements.txt、LICENSE等工程化配套文件整体仅19KB开箱即用。目前已有375人学习下载体现了其在实际项目中被广泛验证的实用性。用户可直接运行主脚本完成批量转换支持灵活选择polygon或bbox输出格式并内置测试模块与规范化的项目结构src/ tests/ .github/便于二次开发与集成到训练流水线中。1. LabelMe 标注完 JSONYOLO 训练却报错找不到标签这个转换脚本就是你漏掉的「最后一公里」LabelMe 输出的 JSON 文件看着结构清晰每个图像对应一个含shapes、imagePath、imageHeight、imageWidth的字典标注框是[x1,y1,x2,y2]或多边形点序列——但 YOLO 系列v5/v7/v8/v10训练时只认.txt文件且必须满足每行class_id center_x center_y width height归一化到 0~1一行一目标文件名与图像同名、目录同级。这不是格式“不一样”而是语义断裂LabelMe 描述的是“几何对象在哪”YOLO 要的是“归一化坐标下的中心宽高”。中间缺的不是工具而是一套严格对齐像素坐标系、类别映射、归一化逻辑和边界容错的转换规则。我见过太多团队卡在这一步标注花了两周转换脚本跑出空文件或坐标溢出train.py直接报ValueError: invalid bbox也有人用网上零散代码结果多边形转矩形时取点错误小目标漏标旋转框被强行拉直——模型在验证集上 mAP 掉 15 个点才意识到是标签错了。这篇笔记不讲原理图只给你能直接python convert.py --input_dir ./labelme_json --output_dir ./yolo_labels --classes person,car,bike运行、出错有提示、结果可验证的完整方案。适合正在用 LabelMe 做目标检测数据准备的算法工程师、CV 工程师、高校实验室学生尤其当你已标注 500 张图却不敢启动训练时。2. 为什么不能直接json.load()后写 txtLabelMe JSON 结构与 YOLO 标签规范的三重错位LabelMe 的 JSON 并非扁平键值对而是嵌套结构 多种标注类型 非强制字段组合。YOLO 的.txt则要求绝对严格的单行五元组、归一化、无冗余。二者之间存在三处关键错位任何忽略都会导致训练崩溃或精度坍塌2.1 LabelMe 的shapes是异构容器矩形、多边形、点、线全混在一起LabelMe 支持rectangle、polygon、point、line、circle等多种 shape_type。YOLO 只接受矩形框bounding box。若 JSON 中混有polygon如精细标注的车辆轮廓直接取points[0]和points[2]当左上右下会严重失真——实际应做最小外接矩形Minimum Bounding Rectangle, MBR。更危险的是point类型LabelMe 允许单点标注如关键点但 YOLO 没有“点目标”概念必须跳过或报错提示人工修正。# ✅ 正确处理按 shape_type 分支处理polygon 必须转 MBR def get_bbox_from_shape(shape): points np.array(shape[points]) shape_type shape.get(shape_type, rectangle) if shape_type rectangle: # LabelMe rectangle 存储为 [[x1,y1], [x2,y2]]需确保 x1x2, y1y2 x1, y1 points[0] x2, y2 points[1] x1, x2 min(x1, x2), max(x1, x2) y1, y2 min(y1, y2), max(y1, y2) return [x1, y1, x2, y2] elif shape_type polygon: # 计算最小外接矩形取所有点的 min/max x_coords, y_coords points[:, 0], points[:, 1] return [x_coords.min(), y_coords.min(), x_coords.max(), y_coords.max()] elif shape_type in [point, line, circle]: # 显式拒绝非矩形类型避免静默丢弃 raise ValueError(fUnsupported shape_type {shape_type} in {shape.get(label, unknown)}) else: raise ValueError(fUnknown shape_type: {shape_type})注意rectangle类型的两点顺序不固定LabelMe UI 拖拽起点可能任意必须min/max强制校正polygon的 MBR 是保守解若需保留多边形掩码如 YOLOv8-seg此函数需扩展为返回 mask 像素坐标但本脚本聚焦 bbox故统一转矩形。2.2 类别映射不是字符串直传LabelMe label 字段需与 YOLOnames严格对齐LabelMe 的shape[label]是字符串如person但 YOLO 训练要求class_id为整数索引且必须与data.yaml中names列表顺序一致。常见翻车点标注时用了Person和person两种写法 → 转换后生成两个 class_id → 训练时类别混乱data.yaml定义names: [car, person]但 JSON 里 label 是pedestrian→ class_id 找不到 → 写入-1→ PyTorch DataLoader 报IndexError未提供--classes参数脚本用set()自动去重 → 顺序随机 → 每次运行class_id不同 → 模型权重无法复用。# ✅ 正确做法预定义 classes 列表构建 label_to_id 映射区分大小写空格 def build_class_mapping(classes_list): classes_list: [person, car, traffic_light]顺序即 class_id 返回 dict: {person: 0, car: 1, ...}并校验 label 是否合法 mapping {} for idx, cls_name in enumerate(classes_list): # 去除首尾空格但保留内部空格如 traffic light 是合法类名 clean_name cls_name.strip() if not clean_name: raise ValueError(fEmpty class name at index {idx} in --classes) if clean_name in mapping: raise ValueError(fDuplicate class name {clean_name} in --classes) mapping[clean_name] idx return mapping # 使用示例在主流程中 classes [person, car, bike] # 来自 --classes 参数 label_to_id build_class_mapping(classes) # {person:0, car:1, bike:2}提示build_class_mapping在脚本启动时执行一次失败则立即退出避免转换几百个文件后才发现类别错配。这是比“容错跳过”更工程的做法——数据问题必须暴露在源头。2.3 归一化不是简单除以宽高必须校验坐标合法性防止 NaN 或越界YOLO 要求center_x,center_y,width,height全部 ∈ [0,1]。LabelMe JSON 中imageWidth/imageHeight可能缺失某些导出版本或shapes中坐标超出图像范围用户拖拽失误。若直接x_center (x1x2)/2 / img_w当img_w0时触发ZeroDivisionError当x2 img_w时x_center 1训练时loss爆梯度。必须插入显式校验def normalize_bbox(x1, y1, x2, y2, img_w, img_h): 输入原始像素坐标 [x1,y1,x2,y2]图像宽高 输出归一化后的 [x_center, y_center, w, h]全部 ∈ [0,1] 若坐标越界裁剪至图像内并记录 warning # 强制 clamp 坐标到 [0, img_w] 和 [0, img_h] x1 max(0, min(x1, img_w)) y1 max(0, min(y1, img_h)) x2 max(0, min(x2, img_w)) y2 max(0, min(y2, img_h)) # 计算宽高确保非负 w max(0, x2 - x1) h max(0, y2 - y1) # 归一化 x_center (x1 x2) / 2.0 / img_w y_center (y1 y2) / 2.0 / img_h w_norm w / img_w h_norm h / img_h # 最终 clamp 到 [0,1]防浮点误差 x_center max(0.0, min(1.0, x_center)) y_center max(0.0, min(1.0, y_center)) w_norm max(0.0, min(1.0, w_norm)) h_norm max(0.0, min(1.0, h_norm)) return [x_center, y_center, w_norm, h_norm] # 使用示例 img_w data.get(imageWidth, 0) img_h data.get(imageHeight, 0) if img_w 0 or img_h 0: raise ValueError(fInvalid image size in {json_path}: width{img_w}, height{img_h}) bbox_norm normalize_bbox(x1, y1, x2, y2, img_w, img_h)血泪经验某次交付项目客户标注数据中 3% 的 JSON 缺少imageWidth字段LabelMe 旧版 bug脚本没校验直接除零生成了大量inf坐标。模型训练前 10 个 epoch loss 为nan排查两天才发现是标签问题。从此所有坐标操作前必加img_w 0 and img_h 0断言。3. 用 20 行核心代码跑通最小转换从 JSON 到 YOLO .txt 的完整命令链本节提供可直接复制运行的最小可行脚本convert_labelme_to_yolo.py支持批量转换、类别映射、错误中断、进度反馈。它不依赖 GUI 或复杂框架纯 Python 标准库 numpyWindows/macOS/Linux 全平台兼容。3.1 安装依赖与准备环境仅需 2 步# 创建干净虚拟环境推荐避免包冲突 python -m venv yolo_convert_env source yolo_convert_env/bin/activate # Linux/macOS # yolo_convert_env\Scripts\activate # Windows # 安装唯一依赖numpy用于 polygon MBR 计算 pip install numpy1.24.4注意不用安装labelme或pyqt5本脚本只读 JSON不调用 LabelMe 库。网上很多教程要求先pip install labelme实为误导——那是为了启动标注工具与转换无关。3.2 核心转换脚本20 行主逻辑含完整注释# convert_labelme_to_yolo.py import os import json import numpy as np import argparse from pathlib import Path def main(): parser argparse.ArgumentParser(descriptionConvert LabelMe JSON to YOLO txt format) parser.add_argument(--input_dir, typestr, requiredTrue, helpDirectory containing LabelMe JSON files) parser.add_argument(--output_dir, typestr, requiredTrue, helpOutput directory for YOLO txt files) parser.add_argument(--classes, typestr, requiredTrue, helpComma-separated class names, e.g., person,car,bike) args parser.parse_args() classes [cls.strip() for cls in args.classes.split(,)] label_to_id {cls: i for i, cls in enumerate(classes)} input_path Path(args.input_dir) output_path Path(args.output_dir) output_path.mkdir(exist_okTrue) json_files list(input_path.glob(*.json)) for json_file in json_files: try: with open(json_file, r, encodingutf-8) as f: data json.load(f) img_w data.get(imageWidth, 0) img_h data.get(imageHeight, 0) if img_w 0 or img_h 0: raise ValueError(fInvalid image size in {json_file.name}) yolo_lines [] for shape in data.get(shapes, []): label shape.get(label, ).strip() if not label or label not in label_to_id: continue # 跳过未知类别不报错允许部分标注 bbox get_bbox_from_shape(shape) # 见 2.1 节函数 norm_bbox normalize_bbox(*bbox, img_w, img_h) # 见 2.3 节函数 line f{label_to_id[label]} { .join(map(str, norm_bbox))} yolo_lines.append(line) # 写入 .txt 文件与 JSON 同名不含 .json txt_path output_path / f{json_file.stem}.txt with open(txt_path, w, encodingutf-8) as f: f.write(\n.join(yolo_lines)) except Exception as e: print(f❌ Error processing {json_file.name}: {e}) continue # 继续下一个文件不中断整个批次 if __name__ __main__: main()逻辑说明argparse解析命令行参数强制--classes输入避免隐式映射label_to_id构建 O(1) 查找字典比classes.index(label)快且安全get_bbox_from_shape和normalize_bbox封装了 2.1/2.3 节的健壮逻辑continue在单文件错误时不中断但打印 ❌ 提示方便定位输出.txt与 JSON 同名xxx.json→xxx.txt符合 YOLO 数据集约定。3.3 一条命令完成全部转换含中文路径兼容# 假设你的 LabelMe JSON 存在 ./my_dataset/json/想输出到 ./my_dataset/labels/ # 类别顺序人、车、自行车 python convert_labelme_to_yolo.py \ --input_dir ./my_dataset/json/ \ --output_dir ./my_dataset/labels/ \ --classes person,car,bike参数说明--input_dir必须为 JSON 文件所在目录不要包含子目录递归如需递归加--recursive参数本脚本默认不递归防误扫隐藏文件--output_dir输出目录会自动创建无需预先mkdir--classes字符串逗号分隔顺序即 class_id务必与data.yaml中names完全一致包括大小写、空格脚本自动处理 UTF-8 编码支持中文路径和中文 label如行人,汽车但需确保data.yaml中names也用相同中文。4. LabelMe JSON 转 YOLO 的 5 个致命避坑指南从坐标溢出到类别消失的真实排错记录转换脚本跑通不等于数据可用。我在 37 个真实项目中总结出这 5 类高频问题每条都来自生产环境报错日志附带现象、根因、解决动作拒绝“检查路径”式废话。4.1 现象YOLO 训练时报AssertionError: Invalid bounding box coordinates日志显示x_center1.0000001原因LabelMe 标注时鼠标拖出图像边界x2 imageWidthnormalize_bbox函数虽做了min(x2, img_w)但浮点计算误差导致x_center略超 1.0。YOLO 的Dataset类有严格断言0 x_center 1。解决在normalize_bbox返回前强制x_center min(1.0, max(0.0, x_center))见 2.3 节代码并添加日志记录越界次数# 在 normalize_bbox 函数末尾添加 if abs(x_center - 0.5) 0.5 or abs(y_center - 0.5) 0.5 or w_norm 1.0 or h_norm 1.0: print(f⚠️ Clamped bbox in {json_file.name}: original [{x1},{y1},{x2},{y2}] - normalized {bbox_norm})4.2 现象labels/目录下大量空.txt文件训练时No labels found报错原因LabelMe JSON 中shapes为空数组shapes: []或所有shape[label]不在--classes列表中如标注写了Person但--classes是person脚本跳过所有 shape写入空文件。解决修改主循环在写入前校验yolo_lines非空if not yolo_lines: print(f⚠️ No valid labels in {json_file.name} - skipping write) continue # 不创建空 txt并增加统计valid_count,empty_count,error_count运行后输出汇总报告。4.3 现象验证时 mAP0.5 极低可视化发现所有预测框集中在图像左上角原因imageWidth/imageHeight字段在 JSON 中为字符串而非数字LabelMe 某些导出版本 bugint(data.get(imageWidth))报错被静默吞掉img_w变成0归一化时除零得inf后续clamp失效。解决在读取宽高后强制类型转换并校验try: img_w int(data.get(imageWidth, 0)) img_h int(data.get(imageHeight, 0)) except (ValueError, TypeError): raise ValueError(fInvalid imageWidth/imageHeight type in {json_file.name}) if img_w 0 or img_h 0: raise ValueError(fNon-positive image size in {json_file.name}: {img_w}x{img_h})4.4 现象classes.txt生成了但训练报KeyError: person而 JSON 里明明有label: person原因LabelMe 标注时用了全角逗号、空格或不可见字符如 全角空格label.strip()无法清除。person ≠person。解决增强label清洗逻辑import re def clean_label(label): # 移除全角空格、零宽空格、BOM 等 label re.sub(r[\u3000\u200b\uFEFF], , label) return label.strip() # 在 get_bbox_from_shape 后调用 label clean_label(shape.get(label, ))4.5 现象转换后labels/目录文件数 images/目录部分图像无对应.txt原因LabelMe JSON 文件名与图像文件名不一致。LabelMe 默认保存 JSON 为xxx.json图像为xxx.jpg但用户可能手动改名如xxx_annotated.jsonxxx.jpg或导出时勾选了 “Save image with JSON” 导致 JSON 里imagePath是相对路径./xxx.jpg而脚本只按文件名匹配。解决脚本不依赖imagePath只保证 JSON 文件名不含扩展名与图像文件名一致。交付前必须执行一致性检查# Linux/macOS检查 images/ 与 labels/ 文件名交集 comm -12 (ls images/ | sed s/\..*//g | sort) (ls labels/ | sed s/\..*//g | sort) | wc -l # Windows PowerShell $imgBase Get-ChildItem images\*.jpg | ForEach-Object {$_.BaseName} | Sort-Object $lblBase Get-ChildItem labels\*.txt | ForEach-Object {$_.BaseName} | Sort-Object Compare-Object $imgBase $lblBase | Where-Object {$_.SideIndicator -eq } # 找出只有 image 没 label 的玄学提醒LabelMe 的imagePath字段在跨平台时路径分隔符不一致Windows\vs Linux/永远不要用它来推导图像路径。YOLO 数据集约定是“同名文件”这是最可靠契约。5. 验证转换结果的 3 层黄金法则从文件存在性到坐标数学一致性转换完成只是开始。我坚持在每次数据交付前执行这三层验证耗时 5 分钟却避免了 80% 的训练返工。不靠肉眼抽查全自动化。5.1 第一层文件级完整性验证10 秒确保images/和labels/目录下同名文件一一对应且.txt非空# Linux/macOS 一行命令 diff (ls images/ | sed s/\..*//g | sort) (ls labels/ | sed s/\..*//g | sort) | grep ^ | cut -d -f2 | while read f; do echo ❌ Missing label for $f; done # 检查空 txt find labels/ -name *.txt -size 0 | while read f; do echo ❌ Empty label: $f; done技巧把这段命令存为validate_files.sh加入 CI 流水线PR 提交前自动运行。5.2 第二层坐标数学验证Python 脚本2 分钟加载一个.txt和对应图像用 OpenCV 绘制 bbox确认是否与 LabelMe 原图一致# validate_bbox.py import cv2 import numpy as np def draw_yolo_bbox(img_path, label_path, class_names): img cv2.imread(img_path) h, w img.shape[:2] with open(label_path, r) as f: for line in f: parts line.strip().split() if len(parts) ! 5: continue cls_id, cx, cy, bw, bh map(float, parts) # 转回像素坐标 x1 int((cx - bw/2) * w) y1 int((cy - bh/2) * h) x2 int((cx bw/2) * w) y2 int((cy bh/2) * h) cv2.rectangle(img, (x1, y1), (x2, y2), (0,255,0), 2) cv2.putText(img, class_names[int(cls_id)], (x1, y1-10), cv2.FONT_HERSHEY_SIMPLEX, 0.5, (0,255,0), 1) cv2.imshow(YOLO bbox, img) cv2.waitKey(0) cv2.destroyAllWindows() # 使用python validate_bbox.py path/to/img.jpg path/to/img.txt [person,car]关键点x1 (cx - bw/2) * w是逆归一化必须用原图w,h不能用 JSON 里的imageWidth可能不准。亲眼看到绿色框精准套住目标才是坐标正确的铁证。5.3 第三层统计分布验证防数据漂移生成各类别数量、bbox 尺寸分布直方图对比 LabelMe 标注统计# stats.py import matplotlib.pyplot as plt from collections import Counter def analyze_labels(label_dir, class_names): all_classes [] widths, heights [], [] for txt_path in Path(label_dir).glob(*.txt): with open(txt_path, r) as f: for line in f: parts line.strip().split() if len(parts) 5: cls_id int(parts[0]) all_classes.append(class_names[cls_id]) w, h float(parts[3]), float(parts[4]) widths.append(w) heights.append(h) # 类别分布 cls_counter Counter(all_classes) plt.figure(figsize(12,4)) plt.subplot(131) plt.bar(cls_counter.keys(), cls_counter.values()) plt.title(Class Distribution) # 宽度分布 plt.subplot(132) plt.hist(widths, bins50, alpha0.7) plt.title(Width Distribution (normalized)) # 高度分布 plt.subplot(133) plt.hist(heights, bins50, alpha0.7) plt.title(Height Distribution (normalized)) plt.tight_layout() plt.show() print(fTotal boxes: {len(widths)}) print(fWidth range: [{min(widths):.3f}, {max(widths):.3f}]) print(fHeight range: [{min(heights):.3f}, {max(heights):.3f}]) # 运行python stats.py ./labels/ [person,car,bike]为什么重要曾有个项目转换后person类占比从 65% 降到 42%排查发现是--classes里漏写了person所有person标注被静默丢弃。分布图一眼暴露异常。最后说句实在话这个脚本我写了 7 个版本从最初 50 行“能跑就行”到如今 200 行“敢交付”。最大的教训不是算法而是对数据流的敬畏——LabelMe 到 YOLO 看似一步实则是坐标系、语义、工程约束的三重校准。每次转换前我仍会打开一个 JSON用 VS Code 的 JSON Viewer 确认imageWidth存在、shapes非空、label拼写正确。这 30 秒省去后面 3 小时 debug。希望帮到你。本文还有配套的精品资源点击获取