ViTPose 仓库 HRNet 全身人体姿态估计实战指南:基于 COCO-WholeBody 数据集的 Top-Down Heatmap 方案
ViTPose 仓库 HRNet 全身人体姿态估计实战指南:基于 COCO-WholeBody 数据集的 Top-Down Heatmap 方案
本文以 ViTPose 仓库中 HRNet + COCO-WholeBody 基准文档 为核心,系统讲解如何用 HRNet 骨干网络完成 133 关键点的全身(Whole-Body)人体姿态估计。你将掌握 COCO-WholeBody 数据集的标注结构与 133 关键点划分、Top-Down Heatmap 任务的整体训练管线、4 套官方配置(w32/w48 × 256x192/384x288)的参数差异与官方精度基准,以及从数据准备到训练、测试、推理的完整实操链路。
1. 任务背景:什么是全身人体姿态估计
全身人体姿态估计(Whole-Body Human Pose Estimation)的目标是从单张 RGB 图像中同时恢复人体的**身体(Body)、脚(Foot)、面部(Face)和双手(Hand)**共 133 个关键点。它与传统仅预测 17 个身体关键点的任务相比,覆盖了更完整的语义信息,可支撑数字人驱动、虚拟试穿、动作捕捉、康复评估等需要精细肢体与手势理解的场景。
在 ViTPose 仓库中,这一类任务归属于 configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/ 目录,采用自顶向下(Top-Down)两阶段范式:
- 人体检测:先用检测器从图像中框出每个人体(Human Bounding Box);
- 单人姿态估计:将每个人体裁剪区域送入姿态估计模型,预测该人体的全身关键点热图。
Top-Down 方法不直接回归关键点坐标,而是输出一张张热图(Heatmap),每个通道对应一个关键点,热图的峰值位置即该关键点的估计位置。仓库 README.md 对这一范式给出了明确描述:"Instead of estimating keypoint coordinates directly, the pose estimator will produce heatmaps which represent the likelihood of being a keypoint"。
注意:仓库根目录同时是 ViTPose(ViT 骨干)的官方实现仓库,但本文聚焦的 HRNet 文档属于仓库内提供的经典 CNN 骨干对比基线,二者共享同一套 Top-Down 训练与评估框架,因此下文涉及的所有配置、数据管线与评测流程,对仓库内 ViTPose 系列配置同样适用。
2. 数据基础:COCO-WholeBody 数据集的 133 关键点结构
2.1 数据集的来源与划分
本文涉及的配置全部基于 COCO-WholeBody v1.0(ECCV'2020,论文 Whole-Body Human Pose Estimation in the Wild)。训练与验证使用的标注文件为:
- 训练集:
data/coco/annotations/coco_wholebody_train_v1.0.json,图像目录data/coco/train2017/ - 验证集:
data/coco/annotations/coco_wholebody_val_v1.0.json,图像目录data/coco/val2017/
以上路径来自 hrnet_w32_coco_wholebody_256x192.py 中的 data 配置块。需要注意的是,官方提供的验证集指标是在 COCO val2017 上人体 AP 为 56.4 的检测器(检测框文件 COCO_val2017_detections_AP_H_56_person.json)前提下评测得到的,并非使用 GT 框,这一点在文档的基准表中已有明确说明。
2.2 133 个关键点的组织方式
COCO-WholeBody 的关键点由五部分组成,索引划分在数据集实现类 topdown_coco_wholebody_dataset.py 的 docstring 中有精确注释:
| 区域 | 索引范围 | 数量 |
|---|---|---|
| Body 身体关键点 | 0–16 | 17 |
| Foot 脚部关键点 | 17–22 | 6 |
| Face 面部关键点 | 23–90 | 68 |
| Hand 手部关键点(左右各 21) | 91–132 | 42 |
| 总计 | 0–132 | 133 |
对应地,数据集类内部也以 self.body_num = 17、self.foot_num = 6、self.face_num = 68、self.left_hand_num = 21、self.right_hand_num = 21 保存这五段的数量,用于标注解析与结果切分。在标注 JSON 中,每一段以独立字段存在(keypoints、foot_kpts、face_kpts、lefthand_kpts、righthand_kpts),数据集在加载时通过 _load_coco_keypoint_annotation_kernel 将它们拼接成 (133, 3) 的关键点数组。
每个关键点的名称、颜色、左右镜像配对关系(swap)由 configs/base/datasets/coco_wholebody.py 中的 dataset_info 字典完整定义,例如 left_eye ↔ right_eye、left_hand_root ↔ right_hand_root。这些 swap 配对信息在训练时的随机翻转数据增强和推理时的翻转测试(flip test)中都会被用来正确交换左右侧热图。
2.3 通道配置:channel_cfg
由于 133 个关键点一次性输出,所有 HRNet 配置都使用统一的通道配置:
channel_cfg = dict(
num_output_channels=133, # 热图输出通道数 = 关键点数
dataset_joints=133, # 数据集关键点总数
dataset_channel=[
list(range(133)), # 训练时使用全部 133 个关键点
],
inference_channel=list(range(133))) # 推理时输出全部 133 个关键点
该配置在 hrnet_w32_coco_wholebody_256x192.py 与其余三个配置中完全一致,说明 HRNet 系列在该任务上不做关键点子集划分,训练与推理均覆盖全部 133 个点。
3. 模型配置解析:HRNet 骨干 + Top-Down 热图头
3.1 整体模型结构
所有 HRNet 全身配置遵循统一的 TopDown 模型范式,以 w32 / 256x192 配置为例:
model = dict(
type='TopDown', # 自顶向下检测器类型
pretrained='https://download.openmmlab.com/mmpose/'
'pretrain_models/hrnet_w32-36af842e.pth', # ImageNet 预训练权重
backbone=dict(type='HRNet', in_channels=3, extra=dict(...)), # 骨干
keypoint_head=dict(
type='TopdownHeatmapSimpleHead', # 简单热图头
in_channels=32, # 取 HRNet 第一个分支(最高分辨率)输出
out_channels=channel_cfg['num_output_channels'], # 133
num_deconv_layers=0, # 无反卷积上采样层
extra=dict(final_conv_kernel=1), # 1x1 卷积输出 133 通道热图
loss_keypoint=dict(type='JointsMSELoss', use_target_weight=True)),
train_cfg=dict(),
test_cfg=dict(
flip_test=True, # 开启翻转测试
post_process='default',
shift_heatmap=True, # 使用四舍五入偏移补偿
modulate_kernel=11)) # DARK 风格调制核大小
这里 HRNet 与常规 SimpleBaseline 的关键区别在于:HRNet 全程保持高分辨率表示,网络主体由 4 个 stage 的多分辨率并行分支组成(w32 时四个分支通道数为 32/64/128/256,w48 时为 48/96/192/384),因此热图头不需要反卷积上采样,而是直接取最高分辨率分支的特征(in_channels=32 或 48),经过 1x1 卷积得到 133 通道热图。
从 hrnet.py 的 HRNet 类实现可以看到,stage 结构通过 extra 字典控制:stage1 为单分支 BOTTLENECK 块(w32 时 num_channels=(64,)),stage2–stage4 分别为 2/3/4 个并行分支的 BASIC 块,各 stage 的 num_blocks、num_channels 决定了网络的宽度与深度。热图头 topdown_heatmap_simple_head.py 的实现则说明 num_deconv_layers=0 时直接由 final_layer(1x1 卷积)输出热图。
3.2 四种官方配置一览
仓库为 HRNet 全身估计提供了 w32 / w48 两种骨干规格 × 256x192 / 384x288 两种输入分辨率,共 4 个配置:
| 配置文件 | 骨干 | 输入尺寸 | 热图尺寸 | 高斯 sigma |
|---|---|---|---|---|
| hrnet_w32_coco_wholebody_256x192.py | HRNet-W32 | 256x192 | 64x48 | 2 |
| hrnet_w32_coco_wholebody_384x288.py | HRNet-W32 | 384x288 | 96x72 | 3 |
| hrnet_w48_coco_wholebody_256x192.py | HRNet-W48 | 256x192 | 64x48 | 2 |
| hrnet_w48_coco_wholebody_384x288.py | HRNet-W48 | 384x288 | 96x72 | 3 |
其中 data_cfg 里的 image_size 与 heatmap_size 一一对应:
data_cfg = dict(
image_size=[192, 256], # 输入图像 [宽, 高]
heatmap_size=[48, 64], # 热图 [宽, 高],为输入的 1/4
...
)
高分辨率输入(384x288)配 sigma=3 的更大高斯核、低分辨率(256x192)配 sigma=2,保证热图高斯峰在不同分辨率下覆盖的像素范围大致一致。
3.3 训练超参数
四个配置共享同一套训练超参数(定义于 default_runtime.py 与各配置文件):
- 优化器:Adam,初始学习率
lr=5e-4,无梯度裁剪(grad_clip=None) - 学习率策略:step 衰减,
step=[170, 200],w32 配置使用 500 步线性 warmup(warmup='linear', warmup_iters=500, warmup_ratio=0.001),w48 配置中 warmup 相关行被注释(等效于无 warmup) - 总轮数:
total_epochs = 210 - 评测:
evaluation = dict(interval=10, metric='mAP', save_best='AP'),即每 10 个 epoch 在验证集上评估一次 mAP,并以整体 AP 作为最优模型筛选依据 - 批量大小:w32 配置
samples_per_gpu=64(val/test 为 32),w48 配置训练samples_per_gpu=32(val/test 为 32),workers_per_gpu=2
3.4 数据增强管线
训练管线(train_pipeline)自 hrnet_w32_coco_wholebody_256x192.py 可见,包含:
train_pipeline = [
dict(type='LoadImageFromFile'),
dict(type='TopDownRandomFlip', flip_prob=0.5), # 50% 概率水平翻转
dict(type='TopDownHalfBodyTransform', # 半身裁剪:提升身体局部精度
num_joints_half_body=8, prob_half_body=0.3),
dict(type='TopDownGetRandomScaleRotation', # 随机缩放/旋转
rot_factor=40, scale_factor=0.5),
dict(type='TopDownAffine'), # 仿射变换裁剪到目标尺寸
dict(type='ToTensor'),
dict(type='NormalizeTensor',
mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]), # ImageNet 归一化
dict(type='TopDownGenerateTarget', sigma=2), # 生成高斯热图标签
dict(type='Collect',
keys=['img', 'target', 'target_weight'],
meta_keys=['image_file', 'joints_3d', 'joints_3d_visible',
'center', 'scale', 'rotation', 'bbox_score', 'flip_pairs']),
]
其中 TopDownGenerateTarget 负责根据关键点坐标生成高斯热图标签;flip_pairs 会被 Collect 收集,供翻转测试时进行左右关键点交换。验证与测试管线(val_pipeline / test_pipeline)仅保留仿射变换、张量化、归一化与收集,不包含任何随机增强。
4. 官方精度基准
以下结果来自 hrnet_coco-wholebody.md 的基准表,评测条件为 COCO-WholeBody v1.0 val,检测器在 COCO val2017 上人体 AP 为 56.4。指标分为 Body / Foot / Face / Hand / Whole 五个子集的 AP(平均精度)与 AR(平均召回率):
| 配置 | 输入尺寸 | Body AP/AR | Foot AP/AR | Face AP/AR | Hand AP/AR | Whole AP/AR |
|---|---|---|---|---|---|---|
| hrnet_w32 | 256x192 | 0.700 / 0.746 | 0.567 / 0.645 | 0.637 / 0.688 | 0.473 / 0.546 | 0.553 / 0.626 |
| hrnet_w32 | 384x288 | 0.701 / 0.773 | 0.586 / 0.692 | 0.727 / 0.783 | 0.516 / 0.604 | 0.586 / 0.674 |
| hrnet_w48 | 256x192 | 0.700 / 0.776 | 0.672 / 0.785 | 0.656 / 0.743 | 0.534 / 0.639 | 0.579 / 0.681 |
| hrnet_w48 | 384x288 | 0.722 / 0.790 | 0.694 / 0.799 | 0.777 / 0.834 | 0.587 / 0.679 | 0.631 / 0.716 |
从表中可以清晰看到两个规律:
- 分辨率收益集中于小目标区域:从 256x192 提升到 384x288,Face 与 Hand AP 的提升最为显著(例如 w48 的 Face AP 从 0.656 提升至 0.777,Hand AP 从 0.534 提升至 0.587),因为面部和手部关键点像素尺寸小,高分辨率输入提供更精细的空间定位;
- 宽骨干收益明显:w48 相比 w32 在 Foot、Hand、Whole 指标上均有明显优势,尤其是 Foot AP(w48@384x288 达 0.694,w32@256x192 仅 0.567)。
各模型的官方权重文件与训练日志可通过基准表中的 ckpt、log 列获取(对应权重哈希如 hrnet_w48_coco_wholebody_384x288-6e061c6a_20200922.pth),完整索引同时记录于 hrnet_coco-wholebody.yml。
5. 指标评估机制:五段独立评测
COCO-WholeBody 的 mAP 评估与普通 COCO 关键点评测不同,需要按 Body、Foot、Face、Left Hand、Right Hand、WholeBody 六个任务分别调用 COCOeval。这一机制在数据集实现 topdown_coco_wholebody_dataset.py 的 _do_python_keypoint_eval 中完整体现:
- 通过
cuts = np.cumsum([0, 17, 6, 68, 21, 21])将 133 个关键点切分为五段; - 依次用
'keypoints_body'、'keypoints_foot'、'keypoints_face'、'keypoints_lefthand'、'keypoints_righthand'、'keypoints_wholebody'六个 task 分别执行COCOeval; - 每段使用对应的 OKS sigma 权重(来自
dataset_info.sigmas,通过 kpt_2d_sview_rgb_img_top_down_dataset.py 注入到self.sigmas)。
这正是为什么基准表中同时给出 Body / Foot / Face / Hand / Whole 五组 AP、AR 指标——它们是六个独立 COCOeval 子任务的汇总结果。测试用例 test_top_down_dataset.py 使用 tests/data/coco/test_coco_wholebody.json 对数据集加载、GT 框模式和 mAP 评估进行了单元验证。
6. 从零实操:数据准备、训练、测试与推理
6.1 数据准备
将 COCO-WholeBody 数据集按以下目录结构放置(data_root = 'data/coco'):
data/coco/
├── annotations/
│ ├── coco_wholebody_train_v1.0.json
│ └── coco_wholebody_val_v1.0.json
├── train2017/ # COCO 训练图像
├── val2017/ # COCO 验证图像
└── person_detection_results/
└── COCO_val2017_detections_AP_H_56_person.json # 验证用检测框
其中检测框文件是复现官方 val 指标所必需的外部检测结果(检测器人体 AP 为 56.4);若仅做训练,data_cfg 中的 bbox_file 只影响验证阶段。
6.2 训练
使用仓库提供的 tools/train.py 启动训练(单卡):
python tools/train.py \
configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/coco-wholebody/hrnet_w48_coco_wholebody_384x288.py
多卡训练可使用 tools/dist_train.sh:
bash tools/dist_train.sh \
configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/coco-wholebody/hrnet_w48_coco_wholebody_384x288.py \
8
训练过程由 default_runtime.py 提供基础运行配置:checkpoint_config = dict(interval=10) 每 10 个 epoch 保存一次权重,log_config 每 50 个 iteration 输出一次日志,mp_start_method = 'fork' 加速数据加载。
6.3 测试
使用 tools/test.py 在验证集上评估并复现基准表指标:
python tools/test.py \
configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/coco-wholebody/hrnet_w48_coco_wholebody_384x288.py \
/path/to/hrnet_w48_coco_wholebody_384x288.pth
评估输出将包含 Body / Foot / Face / Left Hand / Right Hand / WholeBody 六个部分的 AP、AR 等统计量(统计项定义于数据集实现中的 stats_names,包括 AP、AP .5、AP .75、AP (M)、AP (L)、AR 系列)。
6.4 推理
使用仓库 demo/top_down_img_demo.py 对单张图片进行全身姿态可视化:
python demo/top_down_img_demo.py \
configs/wholebody/2d_kpt_sview_rgb_img/topdown_heatmap/coco-wholebody/hrnet_w48_coco_wholebody_384x288.py \
/path/to/hrnet_w48_coco_wholebody_384x288.pth \
--img-root 测试图片目录 \
--json-file 检测结果.json \
--out-img-root 输出目录
如需端到端的人体检测 + 全身估计,可参考 demo/top_down_img_demo_with_mmdet.py 及其配套检测器配置 demo/mmdetection_cfg/。
7. 如何在仓库内继续深入
如果你希望进一步探索 HRNet 全身姿态估计的更多细节,仓库提供了以下延伸入口:
- DARK 变体:同目录下的
hrnet_w32_coco_wholebody_256x192_dark.py等配置采用 DARK(Distribution-Aware coordinate Representation)后处理,通过 hrnet_dark_coco-wholebody.md 查看其精度对比; - 其他骨干:同目录提供 ResNet(resnet_coco-wholebody.md)、ViPNAS(vipnas_coco-wholebody.md)以及 ViTPose 系列的全身配置(
ViTPose_base_wholebody_256x192.py等),可用于横向对比; - 热图后处理原理:翻转测试(
flip_back)、坐标映射回原图(transform_preds)等实现在 mmpose/core/post_processing/post_transforms.py; - 热图头与损失:
TopdownHeatmapSimpleHead与JointsMSELoss分别位于 mmpose/models/heads/topdown_heatmap_simple_head.py 和 mmpose/models/losses/mse_loss.py。
8. 小结
本文完整梳理了 ViTPose 仓库中 HRNet 全身人体姿态估计从数据、模型、训练到评测的完整链路。核心要点可归纳为:
- COCO-WholeBody 提供 133 关键点(17 身体 + 6 脚 + 68 脸 + 42 手),是全身估计的标准基准;
- HRNet 通过多分辨率并行分支保持高分辨率特征,配合
TopdownHeatmapSimpleHead直接输出 133 通道热图; - 4 套官方配置(w32/w48 × 256x192/384x288)共享训练框架,高分辨率与宽骨干分别显著提升小区域关键点(Face/Hand)与 Foot/Whole 指标;
- 评测采用六段独立 COCOeval 机制,因此基准表中出现 Body / Foot / Face / Hand / Whole 五组 AP/AR 指标。
掌握这套 HRNet 基准后,你可以基于同一套 Top-Down 配置骨架 平滑迁移到仓库内的 ViTPose 系列骨干,进行全身姿态估计的更进阶实验。