MeTRAbs源码剖析:PyTorch与TensorFlow双框架实现原理逐行解读

原创2026-11-16 16:52:171,068 阅读

MeTRAbs源码剖析:PyTorch与TensorFlow双框架实现原理逐行解读

MeTRAbs 是一个从单张 RGB 图像估计绝对尺度 3D 人体姿态的开源项目,曾拿下 3DPW 挑战赛冠军。它的仓库同时维护了两套实现:metrabs_pytorch/(PyTorch 推理)和 metrabs_tf/(TensorFlow 训练与推理)。本文带你逐行读懂 metrabs_pytorch/models/metrabs.py 与 metrabs_tf/models/metrabs.py 这两份核心源码,搞懂"绝对尺度"到底是怎么算出来的。

MeTRAbs绝对3D人体姿态估计演示:多个人体的2D关键点与3D世界坐标姿态结果

1. 项目结构:先分清两个框架各管什么

目录 角色 说明
metrabs_pytorch/ PyTorch 推理 结构精简,面向实验性推理场景
metrabs_tf/ TensorFlow 训练 + 推理 含完整训练循环、数据增强、评估
demos/ 示例脚本 一键跑通推理演示
docs/ 官方文档 API.md、INFERENCE.md、TRAINING.md

💡 一句话总结:想训练看 metrabs_tf,想快速复现推理看 metrabs_pytorch。两版的模型类骨架几乎一一对应,读通一份,另一份秒懂。

2. 核心网络:Metrabs 类逐行解读(PyTorch 版)

模型入口是 Metrabs 类,forward 主干只有 4 步:

def forward(self, inp):
    image, intrinsics = inp                    # 输入:图像 + 相机内参
    features = self.backbone(image)            # ① 骨干网提取特征(EfficientNetV2 等)
    coords2d, coords3d = self.heatmap_heads(features)  # ② 双头解码出 2D/3D 相对坐标
    coords3d_abs = ptu3d.reconstruct_absolute(   # ③ 几何重建,恢复绝对尺度
        coords2d, coords3d, intrinsics,
        mix_3d_inside_fov=FLAGS.mix_3d_inside_fov)
    return coords3d_abs                        # ④ 输出毫米级 3D 关节点

第②步由 MetrabsHeads 完成,它是一个 1x1 卷积同时输出两组通道:

self.n_outs = [self.n_points, FLAGS.depth * self.n_points]
self.conv_final = torch.nn.LazyConv2d(out_channels=sum(self.n_outs), kernel_size=1)
  • 2D 头:每个关节一张 2D 高斯热力图,soft_argmax 解码出像素坐标;
  • 3D 头:每个关节一张 depth x H x W 的 3D 体积热力图,预测的是关节相对于某个"参考点"的偏移量(而非绝对深度);
  • 解码用的是 ptu.soft_argmax,即对 softmax 后的概率分布做期望坐标,保证可导、亚像素精度。

热力图坐标最后经 heatmap_to_metric 按 box_size_mm(默认 2200mm,见 config.yaml)缩放到真实毫米尺度。

3. 算法核心:绝对尺度是怎么"重建"出来的

这是整个项目最精彩的部分,全部在 ptu3d.py:

def reconstruct_absolute(coords2d, coords3d_rel, intrinsics, ...):
    ...
    ref = reconstruct_ref_fn(coords2d_normalized, coords3d_rel, ...)
    coords_abs_3d_based = coords3d_rel + ref[:, np.newaxis]   # 3D 头:参考点 + 偏移
    coords_abs_2d_based = back_project(coords2d_normalized, ...)  # 2D 头:纯反投影
    return torch.where(is_predicted_to_be_in_fov[..., None],
                       coords_abs_2d_based, coords_abs_3d_based)

拆开来看 3 个关键设计:

  1. 参考点求解:3D 头只知道"谁比谁深多少",不知道绝对深度。reconstruct_ref_fullpersp 把每个关节的 2D 坐标和 3D 偏移拼成线性方程组 A @ ref = b,再用 torch.linalg.lstsq(加权最小二乘)解出参考点的真实位置——这就是"Metric-Scale(度量尺度)"的由来。配置里 weak_perspective: false 时走此路径,true 则退化为更稳定的弱透视近似 reconstruct_ref_weakpersp。
  2. 视场内外分治:is_within_fov 判断 2D 投影是否落在裁剪图内部。在视场内直接用 2D 反投影(信息最充分),视场外(截断人体)才依赖 3D 热力图——这正是论文标题中 "Truncation-Robust(截断鲁棒)" 的实现。
  3. 混合系数 mix_3d_inside_fov: 0.5:训练时对视野内样本随机混用两种重建结果,让网络学会两种路径都能工作(见 config.yaml)。

4. 双框架对照表:10 分钟读懂 TensorFlow 版

两个框架的 Metrabs 结构几乎镜像,对照着看:

功能 PyTorch 版 TensorFlow 版
模型基类 torch.nn.Module tf.keras.Model
前向方法 forward call
几何重建 ptu3d.reconstruct_absolute tfu3d.reconstruct_absolute
软解码 ptu.soft_argmax tfu.soft_argmax
导出推理 — predict_multi:用 @tf.function 固化输入签名,导出 SavedModel 单行调用

TensorFlow 版比 PyTorch 版多了两样"重装备":

  • MetrabsTrainer:完整的训练循环。compute_loss_with_3d_gt(L259-L305)把损失拆成根相对损失 + 投影损失 + 绝对损失三段;forward_test_flipped(L416-L427)实现水平翻转测试时增强;
  • 多任务损失:compute_losses_latents_and_all(L320-L391)对应 WACV'23 论文中的"潜变量 + 全关节"混合头,配合骨架格式自动编码器使用。

另外 metrabs_tf/models/ 下还有两个实验变体:metro.py(纯 3D 头,无需相机内参)和 twofive.py(2.5D:2D 坐标 + 深度,用理想骨骼长度重建)。

5. 多人推理流水线与快速上手

真正的"开箱即用"入口是 Pose3dEstimator(TensorFlow 版同名模块在 metrabs_tf/multiperson/),完整链路为:

原图 → 人体检测 → 智能裁剪(去畸变+抗锯齿) → 裁剪图批量过 Metrabs
     → 翻转TTA平均 → 可信度过滤(NMS) → 相机/世界坐标系 3D 姿态
  • 相机参数处理:没给内参时会按 default_fov_degrees=55 自动合成(见 intrinsic_matrix_from_field_of_view);
  • 测试时增强:每次推理对每个人体做 num_aug=5 组旋转/翻转/亮度扰动并取平均(L107-L109),显著提升精度;
  • 输出坐标系:提供外参后姿态以毫米为单位落在世界坐标系中,这就是开头演示图里右侧 3D 场景的由来。

🚀 最快上手路径:阅读 demos/demo.py 的单行预测 + docs/API.md 参数详解;训练侧参考 docs/TRAINING.md 与 docs/EVALUATION.md,模型配置从 metrabs_pytorch/config/ 的 YAML 起步(如 config_s_256.yaml)。

常见疑问 FAQ

Q:为什么 PyTorch 版没有训练代码? A:README 明确标注 PyTorch 版为实验性推理支持(2023-08 重构时加入),训练、评估与模型导出仍以 TensorFlow/Keras 为第一公民。

Q:3D 热力图不是直接输出深度吗? A:不。它输出的是"关节 − 参考点"的偏移,参考点由 2D/3D 两头的联合几何约束解出(第 3 节),这既解决了尺度歧义,又让截断人体可用。

Q:能商用吗? A:受训练数据集许可证限制,官方模型仅限非商业用途。

✅ 总结:MeTRAbs 的精髓在于"2D 头管视场内、3D 头管视场外,几何重建管尺度"的分工设计。读懂 forward 的 4 行主干和 reconstruct_absolute 的 25 行重建函数,你就掌握了这套绝对 3D 姿态估计的核心,剩下的骨干网、多人流水线都只是工程拼装。

登录后查看全文
metrabs