MeTRAbs源码剖析:PyTorch与TensorFlow双框架实现原理逐行解读
MeTRAbs源码剖析:PyTorch与TensorFlow双框架实现原理逐行解读
MeTRAbs 是一个从单张 RGB 图像估计绝对尺度 3D 人体姿态的开源项目,曾拿下 3DPW 挑战赛冠军。它的仓库同时维护了两套实现:metrabs_pytorch/(PyTorch 推理)和 metrabs_tf/(TensorFlow 训练与推理)。本文带你逐行读懂 metrabs_pytorch/models/metrabs.py 与 metrabs_tf/models/metrabs.py 这两份核心源码,搞懂"绝对尺度"到底是怎么算出来的。
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 个关键设计:
- 参考点求解:3D 头只知道"谁比谁深多少",不知道绝对深度。reconstruct_ref_fullpersp 把每个关节的 2D 坐标和 3D 偏移拼成线性方程组
A @ ref = b,再用torch.linalg.lstsq(加权最小二乘)解出参考点的真实位置——这就是"Metric-Scale(度量尺度)"的由来。配置里weak_perspective: false时走此路径,true则退化为更稳定的弱透视近似 reconstruct_ref_weakpersp。 - 视场内外分治:is_within_fov 判断 2D 投影是否落在裁剪图内部。在视场内直接用 2D 反投影(信息最充分),视场外(截断人体)才依赖 3D 热力图——这正是论文标题中 "Truncation-Robust(截断鲁棒)" 的实现。
- 混合系数
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 姿态估计的核心,剩下的骨干网、多人流水线都只是工程拼装。
