YOLOv8-Pose训练数据准备避坑指南：从Labelme标注到txt格式的完整流程与可视化校验

YOLOv8-Pose训练数据准备全流程：从Labelme标注到可视化校验的避坑实践

在计算机视觉领域，姿态估计任务对数据格式的要求往往比普通目标检测更加复杂。许多开发者在准备YOLOv8-Pose训练数据时，容易在格式转换环节踩坑——可能是关键点顺序错乱，或是可见性标志缺失，最终导致模型无法正常收敛。本文将分享一套经过实战检验的数据预处理方案，重点解析从Labelme标注到YOLOv8-Pose标准格式的完整转换逻辑，以及每个环节必须注意的验证要点。

1. 理解YOLOv8-Pose的数据格式规范

YOLOv8-Pose的标注文件采用纯文本格式，每行对应一个实例的完整描述。与常规目标检测不同，姿态估计需要额外处理17个关键点的坐标和可见性状态。典型的一行数据如下：

0 0.512 0.634 0.223 0.356 0.529 0.712 2 0.501 0.689 2 ... <后续14个关键点>

各字段含义解析：

• 前5个值：类别索引、边界框中心x、中心y、宽度、高度（均归一化到0-1范围）
• 后续51个值：17个关键点的[x,y,visibility]三元组，其中visibility取值为：
  • 0：未标注
  • 1：标注但不可见（遮挡）
  • 2：标注且可见

关键点顺序必须严格遵循COCO标准：

1. 鼻子
2. 左眼
3. 右眼
4. 左耳
5. 右耳
6. 左肩
7. 右肩
8. 左肘
9. 右肘
10. 左腕
11. 右腕
12. 左髋
13. 右髋
14. 左膝
15. 右膝
16. 左踝
17. 右踝

2. Labelme到COCO格式的转换策略

Labelme的原始JSON标注与目标格式存在三个主要差异：

• 关键点使用自由标签而非固定索引
• 边界框可能缺失或采用不同表示法
• 组标识（group_id）需要特殊处理

关键转换代码解析（labelme2coco.py）

class Lableme2CoCo: def __init__(self, splitDir=''): self.splitDir = splitDir # 路径截断标识符 def to_coco(self, json_path_list): for json_path in json_path_list: obj = self.read_jsonfile(json_path) shapes = obj['shapes'] # 按group_id分组处理多人物实例 groupIds = [shape['group_id'] for shape in shapes] for groupId in set(groupIds): keyPoints = [0] * 51 # 初始化17*3=51维关键点数组 bbox = [] for shape in shapes: if shape['group_id'] != groupId: continue if shape['shape_type'] == "point": labelNum = int(shape['label']) # 关键点编号 # 坐标取整并设置可见性为2 keyPoints[labelNum*3] = int(shape['points'][0][0]+0.5) keyPoints[labelNum*3+1] = int(shape['points'][0][1]+0.5) keyPoints[labelNum*3+2] = 2 elif shape['shape_type'] == 'rectangle': x0, y0, x1, y1 = shape['points'][0][0], shape['points'][0][1], \ shape['points'][1][0], shape['points'][1][1] bbox = [min(x0,x1), min(y0,y1), max(x0,x1)-min(x0,x1), max(y0,y1)-min(y0,y1)] if sum(keyPoints[2::3]) > 0: # 至少有一个有效关键点 annotation = self._annotation(bbox, keyPoints, sum(1 for x in keyPoints[2::3] if x==2)) self.annotations.append(annotation)

关键参数说明：

• splitDir：用于从完整路径中提取相对路径的截断标识。例如设置splitDir='labelMePoint\\'时，路径G:\data\labelMePoint\images\1.jpg将保存为images/1.jpg

常见问题解决方案：

• 关键点编号冲突：确保Labelme中点的标签为0-16的整数
• 路径不一致：检查splitDir是否与实际存储结构匹配
• 多人场景处理：依赖group_id正确分组，标注时需确保同一人物的所有关键点和边界框具有相同group_id

3. COCO到YOLOv8-Pose格式的终极转换

获得COCO格式JSON后，需要使用slefjson2posetxt.py进行最终转换：

def convert_coco_json(cocojsonpath, savepath, use_keypoints=True): for json_file in Path(cocojsonpath).glob('*.json'): with open(json_file) as f: data = json.load(f) images = {f'{x["id"]:d}': x for x in data['images']} imgToAnns = defaultdict(list) for ann in data['annotations']: imgToAnns[ann['image_id']].append(ann) for img_id, anns in imgToAnns.items(): img = images[f'{img_id:d}'] h, w = img['height'], img['width'] for ann in anns: if use_keypoints and ann.get('keypoints'): kpts = np.array(ann['keypoints']).reshape(-1, 3) kpts = kpts / np.array([w, h, 1]) # 归一化 with open(f'{savepath}/{img["file_name"].replace(".jpg",".txt")}', 'a') as f: f.write(('%g '*(4+51)).rstrip() % ( ann['category_id']-1, # class (ann['bbox'][0]+ann['bbox'][2]/2)/w, # cx (ann['bbox'][1]+ann['bbox'][3]/2)/h, # cy ann['bbox'][2]/w, # width ann['bbox'][3]/h, # height *kpts.reshape(-1).tolist() # 17*3 keypoints ) + '\n')

转换过程中的典型陷阱：

1. 坐标未归一化：必须将绝对坐标转换为相对坐标
2. 关键点可见性丢失：确保第三维的visibility标志被保留
3. 文件路径错误：注意Windows与Linux路径分隔符差异

4. 可视化校验：避免前功尽弃的关键步骤

完成格式转换后，必须通过可视化确认标注准确性。PoseVisualization.py脚本的核心逻辑：

def visualize_pose(img_path, txt_path): img = cv2.imread(img_path) h, w = img.shape[:2] with open(txt_path) as f: for line in f.readlines(): data = list(map(float, line.strip().split())) # 绘制边界框 cx, cy, bw, bh = data[1]*w, data[2]*h, data[3]*w, data[4]*h cv2.rectangle(img, (int(cx-bw/2), int(cy-bh/2)), (int(cx+bw/2), int(cy+bh/2)), (0,255,0), 2) # 绘制关键点 kpts = [] for i in range(17): x, y, s = data[5+i*3], data[6+i*3], data[7+i*3] if s > 0: cv2.circle(img, (int(x*w), int(y*h)), 5, COLORS[i], -1) kpts.append([int(x*w), int(y*h), int(s)]) # 绘制骨骼连线 for (start, end) in SKELETON: # COCO定义的17点连接关系 if kpts[start-1][2] > 0 and kpts[end-1][2] > 0: cv2.line(img, tuple(kpts[start-1][:2]), tuple(kpts[end-1][:2]), (255,0,0), 2) cv2.imshow('Preview', cv2.resize(img, (0,0), fx=0.7, fy=0.7)) cv2.waitKey(0)

验证时需特别关注：

• 关键点与人体部位的对应关系是否正确
• 被遮挡关键点的visibility标志是否为1
• 边界框是否合理包裹整个人体
• 多人场景下实例是否区分正确

5. 数据整理与路径处理

最后使用pickImg.py将图片文件整理到对应目录：

def organize_images(img_dir, txt_dir, output_dir): os.makedirs(output_dir, exist_ok=True) txt_files = {os.path.basename(f).replace('.txt', '') for f in glob.glob(f'{txt_dir}/*.txt')} for img_file in glob.glob(f'{img_dir}/*.jpg'): base_name = os.path.basename(img_file).replace('.jpg', '') if base_name in txt_files: shutil.copy(img_file, f'{output_dir}/{base_name}.jpg')

目录结构建议：

dataset/ ├── images/ │ ├── train/ │ └── val/ └── labels/ ├── train/ └── val/

实际项目中遇到的典型问题：

• 图像与标注文件命名不一致
• 验证集缺少对应标注
• 路径中包含中文或特殊字符

这套流程已在多个工业级姿态估计项目中验证，包括生产线工人动作分析和体育训练监测系统。关键是要建立标准化的标注规范，并在每个转换环节后进行可视化抽查。特别是在多人密集场景中，group_id的正确使用和关键点顺序的严格校验尤为重要。