YOLOv10 / YOLOv8 PosePredictor 源码解析关键点姿态预测的推理链路与后处理实现【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10导读本文围绕当前仓库 docs/en/reference/models/yolo/pose/predict.md 所引用的核心类PosePredictor展开它是 Ultralytics YOLO 系列包括本仓库的 YOLOv8 与 YOLOv10在姿态估计任务Pose Estimation上的推理预测器。通过阅读本文你将掌握PosePredictor的初始化机制、与检测预测器的继承关系、关键点后处理NMS、坐标缩放、关键点恢复的完整实现以及如何通过 Python API 和 CLI 两种方式驱动姿态预测并深入理解底层调用链与Results.keypoints的输出结构。PosePredictor 在 YOLO 推理体系中的定位在 Ultralytics YOLO 的架构中姿态估计Pose与检测Detect、分割Segment、旋转框OBB、分类Classify并列为五大任务之一。PosePredictor是整个姿态推理链路的最终执行者定义于 ultralytics/models/yolo/pose/predict.py。它的类继承关系为BasePredictorultralytics/engine/predictor.py ↑ 继承 DetectionPredictorultralytics/models/yolo/detect/predict.py ↑ 继承 PosePredictorultralytics/models/yolo/pose/predict.py其中 BasePredictor 负责通用的推理框架数据源加载、预处理、模型加载AutoBackend、流式推理调度、结果保存与可视化DetectionPredictor 在其基础上实现了目标检测的 NMS 与检测框缩放而PosePredictor则进一步在检测结果之上叠加关键点keypoints的后处理从而输出带有人体/物体关键点坐标的姿态结果。从任务注册机制看ultralytics/models/yolo/model.py 中的task_map将pose任务映射为pose: { model: PoseModel, trainer: yolo.pose.PoseTrainer, validator: yolo.pose.PoseValidator, predictor: yolo.pose.PosePredictor, }这意味着当用户加载yolov8n-pose.pt等姿态权重并调用model.predict()或model(source...)时框架会自动选择PosePredictor完成推理。ultralytics/models/yolo/pose/init.py 将PoseTrainer、PoseValidator、PosePredictor三个类统一对外导出。初始化与 task 设置mps 设备警告PosePredictor的构造函数通过super().__init__(cfg, overrides, _callbacks)调用父类完成通用配置解析get_cfg合并默认配置与覆盖项随后执行两项姿态特有的初始化def __init__(self, cfgDEFAULT_CFG, overridesNone, _callbacksNone): super().__init__(cfg, overrides, _callbacks) self.args.task pose if isinstance(self.args.device, str) and self.args.device.lower() mps: LOGGER.warning( WARNING ⚠️ Apple MPS known Pose bug. Recommend devicecpu for Pose models. )self.args.task pose将任务标识强制设为pose后续的数据预处理如pre_transform、结果写入等逻辑都会依据该 task 选择姿态路径MPS 设备警告当用户显式传入devicempsApple 芯片 GPU时会输出一条已知 Bug 的警告并建议姿态模型改用devicecpu。这是仓库源码中明确记载的兼容性提示属于姿态任务特有的注意事项值得在部署到 macOS 时格外留意。postprocess姿态后处理的完整链路PosePredictor的核心贡献集中在postprocess方法它接收原始网络输出preds、经过 letterbox 预处理的张量img以及原始图像orig_imgs返回一个Results对象列表。整个过程分为四步第一步非极大值抑制NMSpreds ops.non_max_suppression( preds, self.args.conf, self.args.iou, agnosticself.args.agnostic_nms, max_detself.args.max_det, classesself.args.classes, nclen(self.model.names), )NMS 由 ultralytics/utils/ops.py 中的non_max_suppression函数实现其默认阈值与 BasePredictor 保持一致conf默认为 0.25、iou默认为 0.45、max_det默认为 300。与检测任务的关键区别是传入了nclen(self.model.names)显式指定类别数这是因为姿态输出张量的列布局为[x, y, w, h, class_conf, ...keypoints]NMS 需要精确切分类别置信度与关键点通道。第二步输入张量转 NumPy 批次if not isinstance(orig_imgs, list): # input images are a torch.Tensor, not a list orig_imgs ops.convert_torch2numpy_batch(orig_imgs)当推理源为torch.Tensor例如自定义预处理后直接喂入的张量时需先通过convert_torch2numpy_batch将其转换为 NumPy 批次以保证后续按原始图像尺寸进行坐标还原。第三步检测框与关键点坐标缩放pred[:, :4] ops.scale_boxes(img.shape[2:], pred[:, :4], orig_img.shape).round() pred_kpts pred[:, 6:].view(len(pred), *self.model.kpt_shape) if len(pred) else pred[:, 6:] pred_kpts ops.scale_coords(img.shape[2:], pred_kpts, orig_img.shape)这里体现了姿态后处理与检测后处理最核心的差异pred[:, :4]是检测框xyxy通过scale_boxes从 letterbox 后的尺寸映射回原图尺寸并四舍五入pred[:, 6:]是关键点通道。因为 NMS 输出布局为[x1, y1, x2, y2, score, cls, kpt_x1, kpt_y1, kpt_conf1, ...]所以从第 6 列开始才是关键点数据关键点通过view(len(pred), *self.model.kpt_shape)重塑为(检测数, K, 2或3)的张量kpt_shape来自模型配置见 ultralytics/cfg/models/v8/yolov8-pose.yamlCOCO 姿态为kpt_shape: [17, 3]即 17 个关键点、每点[x, y, visible]三维若某张图没有检测到目标len(pred) 0则直接取pred[:, 6:]空张量避免view因 0 长度报错关键点坐标通过scale_coords做与原图等比例的反向缩放含 padding 去除与越界 clip与检测框共享同一套 letterbox 几何变换参数。第四步封装 Results 对象results.append( Results(orig_img, pathimg_path, namesself.model.names, boxespred[:, :6], keypointspred_kpts) )每个结果被封装为 Results 对象其中boxespred[:, :6]前 6 列检测框 分数 类别交给Boxes模块keypointspred_kpts交给Keypoints模块。Keypoints类ultralytics/engine/results.py提供了xy像素坐标、xyn归一化坐标、conf关键点置信度仅在维度为 3 时可用等属性并会在conf 0.5时将对应点的坐标置零以标记不可见点。这也是Results.keypoints能被results[0].plot()直接绘制出骨骼姿态图的数据基础。与 DetectionPredictor 的对比差异即姿态任务的精髓对比 DetectionPredictor.postprocess 与PosePredictor.postprocess可以清晰看到姿态任务的增量环节DetectionPredictorPosePredictorNMS 类别数不显式传nc传nclen(self.model.names)坐标缩放仅scale_boxes处理pred[:, :4]检测框缩放 scale_coords处理关键点关键点处理无按kpt_shape重塑 坐标反算 越界裁剪Results 封装boxespredboxespred[:, :6]keypointspred_kpts这个对比也解释了为什么姿态推理的底层调用链预处理 → 推理 → 后处理 → 可视化与检测完全一致但结果里多出了keypoints张量维度——关键点分支在模型侧PoseModel见 ultralytics/nn/tasks.py和损失侧v8PoseLoss均有独立实现。使用姿势Python API 与 CLI官方文档给出的最小示例PosePredictor类的 docstring 中给出了最直接的调用方式与文档 docs/en/reference/models/yolo/pose/predict.md 完全一致from ultralytics.utils import ASSETS from ultralytics.models.yolo.pose import PosePredictor args dict(modelyolov8n-pose.pt, sourceASSETS) predictor PosePredictor(overridesargs) predictor.predict_cli()model指定姿态权重yolov8n-pose.pt或任意自定义.ptsource支持图像、视频、目录、URL、摄像头等多类数据源predict_cli()来自 BasePredictor会以生成器方式逐批消费数据流并打印/保存结果。面向日常使用的推荐方式更常见的做法是直接通过统一入口YOLO类加载权重内部自动选择PosePredictorfrom ultralytics import YOLO model YOLO(yolov8n-pose.pt) results model(https://ultralytics.com/images/bus.jpg) # 单张推理 for r in results: boxes r.boxes # Boxes检测框与置信度 kpts r.keypoints # Keypoints姿态关键点 (N, 17, 3) print(kpts.xy.shape) # (N, 17, 2) 像素坐标 print(kpts.conf) # (N, 17) 关键点置信度当 kpt 维度为 3 时CLI 方式等价yolo pose predict modelyolov8n-pose.pt sourcehttps://ultralytics.com/images/bus.jpg更多预测参数conf、iou、imgsz、device、save、show、agnostic_nms、max_det等与完整用法可参考 docs/en/modes/predict.md姿态任务的整体训练、验证、导出流程可参考 docs/en/tasks/pose.md。后处理关键函数的源码级补充为了让读者能精准调参这里对postprocess依赖的两个核心工具函数做源码级说明均位于 ultralytics/utils/ops.pyscale_coords(img1_shape, coords, img0_shape, ...)当未显式传入ratio_pad时按gain min(h1/h0, w1/w0)计算等比缩放系数并推导 letterbox 两侧 padding然后依次执行「减去 padding → 除以 gain →clip_coords越界裁剪」。姿态关键点与检测框共用同一变换因此不会出现骨骼与框错位。non_max_suppression(prediction, conf_thres, iou_thres, ...)默认conf_thres0.25、iou_thres0.45、max_det300、max_wh7680支持classes白名单过滤与agnostic跨类 NMS。姿态推理时conf、iou、max_det、agnostic_nms、classes五个参数均直接透传自预测配置。总结PosePredictor是 Ultralytics YOLO 姿态推理的最终落点它复用了DetectionPredictor的检测后处理管线仅在其上增加了关键点通道的重塑依据模型配置中的kpt_shape、关键点坐标的 letterbox 反向缩放与Results.keypoints的封装。理解 postprocess 实现 中「NMS → 张量转换 → 框/点双路缩放 → Results 封装」四步链路即可在自定义推理脚本中准确获取关键点坐标也能为修改姿态后处理逻辑如自定义关键点过滤策略提供准确的代码切入点。【免费下载链接】yolov10YOLOv10: Real-Time End-to-End Object Detection [NeurIPS 2024]项目地址: https://gitcode.com/GitHub_Trending/yo/yolov10创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考