SMPL-X 仓库 transfer_model 详解:在 SMPL、SMPL+H 与 SMPL-X 之间安全转换模型参数
SMPL-X 仓库 transfer_model 详解:在 SMPL、SMPL+H 与 SMPL-X 之间安全转换模型参数
transfer_model 是 SMPL-X 仓库中用于在 SMPL、SMPL+H、SMPL-X 三个 body model 之间转换模型参数的官方工具集。它通过“顶点/三角形对应关系 + 变形转移矩阵(deformation transfer)+ 三阶段迭代优化”的流程,把一个模型的姿态、体型等参数拟合转换为另一个模型的参数,而不是直接复制参数。读完本文,你可以完整复现从 AMASS 样本动作到 SMPL-X 参数的转换流程,理解六条转换方向各自的命令与 YAML 配置项,并从源码层面弄清优化目标、优化器与输出文件是如何生成的。
为什么不能直接复制参数
transfer_model/README.md 的核心警告是:绝不可以在模型之间直接拷贝参数("Never copy parameters between the models")。原因在于:
- SMPL、SMPL+H 与 SMPL-X 的 shape space 不兼容。每个模型都是独立训练过程的产物,即便两个模型的 数值相同,编码的体型语义也不同;
- SMPL-X 的关节位置与 SMPL 不同,因此 pose()参数不可互换——这一点在 docs/transfer.md 中解释得最清楚:“the joint locations in SMPL-X differ from those in SMPL, meaning that the pose (theta) parameters are not interchangeable”。
所以正确的做法是用目标模型去“拟合”源模型生成的网格,从而在目标模型的参数空间中重新求解出最接近的姿态与体型。这正是 transfer_model 工具做的事情,README 的 News 条目 也说明了这批转换代码是随仓库一并发布的。
转换原理:对应关系、变形转移与三阶段优化
这一节基于 docs/transfer.md 的完整算法描述,并对照源码逐点印证。
1. 建立网格间对应关系
由于 SMPL 与 SMPL-X 的网格拓扑不同(SMPL-X 多了手部与面部的细分网格),首先需要一份“SMPL-X 模板网格注册到 SMPL 模板”的映射。映射方式为:对每个 SMPL-X 顶点,找到 SMPL 网格上的最近点,并存储:
- 最近点所在三角形的索引 ;
- 该点相对于 SMPL 三角形的重心坐标 。
由于 SMPL-X 与 SMPL 在颈部以上共享拓扑,这些重心坐标是 的置换。工具同时保存一个有效顶点掩码,用于剔除两个网格之间无对应关系的点(如眼球、口腔内部)。上文配图即为按对应关系着色后的两个网格(左 SMPL、右 SMPL-X)。
这些预计算的映射以 *_def_transfer.pkl / *_deftrafo_setup.pkl 文件随“Model correspondences”数据包分发。源码中由 read_deformation_transfer() 读取:pkl 中既支持 'mtx' 键(稀疏矩阵,会 todense() 后取顶点部分,即列数一半的列)也支持 'matrix' 键;应用时 apply_deformation_transfer() 用一行 torch.einsum('mn,bni->bmi', ...) 把源网格顶点变换成目标拓扑下的“目标网格”。
2. 三阶段优化求解参数
拿到对应关系后,transfer.md 描述的优化分三步,与 run_fitting() 的实现一一对应:
-
边长损失初始化姿态(3D edge term)。只使用两个网格中端点均有效的边,损失为:
源码对应 VertexEdgeLoss:它通过
gt_connections/est_connections两个 buffer 索引出两端顶点做差,支持l1/l2范数与sum/mean归约;在 run_fitting() 中以type='vertex-edge'构建。当配置edge_fitting.per_part=True时,还会逐关节(per-part)优化:对每个 pose 参数组、每个关节索引单独建立一个小优化器并最小化,收敛后写回var_dict(见 per_part 分支)。 -
平移向量 对齐两个模型:
源码中当
var_dict含translation时执行该阶段(translation 优化)。 -
全参数顶点拟合,得到最紧的拟合:
源码中用
type='l2'的 WeightedMSELoss 对所有var_dict参数联合优化,并对mask_ids中的无效顶点做掩码(vertex 优化)。
被优化的参数集合由 get_variables() 按目标模型类型生成:
| 目标模型 | 优化的参数 |
|---|---|
| SMPL | transl、global_orient、body_pose、betas |
| SMPL+H | 上列 + left_hand_pose、right_hand_pose |
| SMPL-X | 上列 + jaw_pose、leye_pose、reye_pose、expression |
其中所有 pose 参数以轴角(axis-angle)形式存储,前向时经 batch_rodrigues 解码为旋转矩阵后送入 body model。对于 SMPL/SMPL+H 之间这类共享拓扑的转换,可以跳过第一步的对应关系建立,直接拟合;而 SMPL+H → SMPL-X 可复用 SMPL → SMPL-X 的对应关系(smplh2smplx_deftrafo_setup.pkl)。
环境准备与依赖
transfer_model/README.md 的 Requirements 列出以下安装步骤(该工具为非商业科研用途的许可软件,使用前需阅读 LICENSE):
- 安装 mesh(MPI-IS/mesh,即
psbody,被 MeshFolder 数据集 导入); - 克隆 SMPL-X 仓库;
- 安装依赖:
pip install -r requirements.txt(对应 transfer_model/requirements.txt:numpy、torch、dataclasses、pyrender、shapely、trimesh、open3d、smplx、omegaconf、loguru); - 按 Torch Trust Region optimizer 官方说明安装(源码在 optim_factory.py 中
from torchtrustncg import TrustRegion); - 安装
loguru; - 安装
open3d(用于写出.obj结果网格); - 安装
omegaconf(配置解析)。
另外,若要加载 SMPL / SMPL+H 的 pkl 模型文件,还应先按 tools/README.md 清理 Chumpy 对象并合并 MANO 参数(仓库 README 明确要求),这可以用 tools/clean_ch.py 与 tools/merge_smplh_mano.py 完成。
数据准备:transfer_data 目录结构
需要在 SMPL-X 官网注册并下载 Model correspondences 数据包,解压到名为 transfer_data 的文件夹。README 给出的目标结构为:
transfer_data
├── meshes
│ ├── smpl
│ ├── smplx
├── smpl2smplh_def_transfer.pkl
├── smpl2smplx_deftrafo_setup.pkl
├── smplh2smpl_def_transfer.pkl
├── smplh2smplx_deftrafo_setup.pkl
├── smplx2smpl_deftrafo_setup.pkl
├── smplx2smplh_deftrafo_setup.pkl
├── smplx_mask_ids.npy
其中:
meshes/存放按帧切分的.obj/.ply输入网格(MeshFolder 默认扫描.obj和.ply两种扩展名,用trimesh.load(..., process=False)读取);*_def_transfer.pkl/*_deftrafo_setup.pkl是各方向的变形转移矩阵;smplx_mask_ids.npy是有效顶点掩码,供mask_ids_fname配置项加载(在 main.py 中读取)。
仓库自带了一份 AMASS 样本动作 transfer_data/support_data/github_data/amass_sample.npz,可用于跑通示例流程。
完整实战流程:AMASS 样本 → SMPL-X 参数
README 的 Steps 一节给出了三步式流程,可以完整复现:
第 1 步:把动作拆成逐帧 .obj 网格。 SMPL-* 参数在 npz 中是按序列存储的,而 transfer_model 只接受逐帧网格,因此先用 write_obj.py 展开。该脚本用 smplx.create(...) 加载模型,逐帧前向得到 vertices,再导出为 0000.obj、0001.obj 等(逐帧导出逻辑)。README 中的示例命令:
python write_obj.py --model-folder ../models/ --motion-file ../transfer_data/support_data/github_data/amass_sample.npz --output-folder ../transfer_data/meshes/amass_sample/
注意命令中的 ../ 前缀表明它假定在 transfer_model/ 目录下执行;若在仓库根目录执行,应改为 python transfer_model/write_obj.py --model-folder models/ --motion-file transfer_data/support_data/github_data/amass_sample.npz --output-folder transfer_data/meshes/amass_sample/。脚本还支持 --model-type {smpl,smplh,smplx,mano,flame}(默认 smplh)、--gender 等参数;若输入 npz 含 smpl_poses(AMASS 格式),会经 Body.from_smpl().as_smplh() 把 SMPL 姿态重排为 SMPL+H 布局(write_obj.py L74-L86)。
第 2 步:运行 transfer_model 主程序。 用仓库根目录 config_files/ 中的模板 YAML,指向第 1 步的输出网格目录。转换 AMASS 样本到 SMPL-X:
python -m transfer_model --exp-cfg config_files/smplh2smplx_as.yaml
smplh2smplx_as.yaml 与 smplh2smplx.yaml 内容一致,仅输入目录与模型目录不同(前者读 transfer_data/meshes/amass_sample、模型在 models/;后者读 transfer_data/meshes/smplh、模型在 transfer_data/body_models)。执行入口是 transfer_model/main.py:parse_args() 合并默认配置与 YAML 后,逐 batch 调用 run_fitting(),对每帧输出两个文件(main.py L88-L100):
<帧名>.pkl:包含拟合得到的全部参数张量(transl、global_orient、body_pose、betas、手部/下颌/眼球姿态、expression)以及前向结果vertices、joints、faces等;<帧名>.obj:用 open3d 写出的拟合网格,便于人工检查转换质量。
第 3 步:合并为单一动作序列。 逐帧 pkl 需要合并回一个动作文件。merge_output.py 会按文件名中的数字排序读取所有 pkl(merge 函数),对各键做聚合:
python merge_output.py --gender neutral ../output
聚合规则值得注意(merge_output.py L8-L43):
betas对全序列取均值(同时打印每维均值与标准差,可用于观察体型稳定性);global_orient、body_pose、left_hand_pose、right_hand_pose、jaw_pose、full_pose等旋转参数先经R.from_matrix(...).as_rotvec()从旋转矩阵还原为旋转向量再拼接;- 其余键(
transl、expression等)直接torch.cat; - 结果写入
merged.pkl并附gender字段。
README 还提示:流程中常见问题的调试笔记可参见上游仓库的 DEBUG_NOTES 分支及相关 issue(当前镜像中不包含这些外部文档)。
六个转换方向的命令与注意事项
以下命令均从仓库顶层目录运行(README 原文),对应配置文件位于 config_files/:
| 方向 | 命令 | 配置文件 | 注意事项 |
|---|---|---|---|
| SMPL → SMPL-X | python -m transfer_model --exp-cfg config_files/smpl2smplx.yaml |
smpl2smplx.yaml | 输入网格放 transfer_data/meshes/smpl(ply 或 obj) |
| SMPL-X → SMPL | python main.py --exp-cfg config_files/smplx2smpl.yaml(README 原文;-m transfer_model 亦可) |
smplx2smpl.yaml | 生成 SMPL-X 网格时不要使用手部与面部参数,否则 SMPL 无法表达这些信息 |
| SMPL+H → SMPL | python -m transfer_model --exp-cfg config_files/smplh2smpl.yaml |
smplh2smpl.yaml | 此方向会丢失全部手部信息 |
| SMPL → SMPL+H | python -m transfer_model --exp-cfg config_files/smpl2smplh.yaml |
smpl2smplh.yaml | 输出为 SMPL+H 参数(README 中该段误写为 SMPL 参数) |
| SMPL+H → SMPL-X | python -m transfer_model --exp-cfg config_files/smplh2smplx.yaml |
smplh2smplx.yaml | 输入 transfer_data/meshes/smplh |
| SMPL-X → SMPL+H | python -m transfer_model --exp-cfg config_files/smplx2smplh.yaml |
smplx2smplh.yaml | 生成网格时不要使用 jaw 姿态与表情参数 |
通用做法:把自己数据的网格(ply 或 obj)放入配置指定的 data_folder,修改该路径后运行即可,结果以 pkl 形式输出。
两点来自源码与配置的补充说明:
- SMPL+H 没有 neutral 模型。在 smpl2smplh.yaml 与 smplx2smplh.yaml 中,
gender被显式设为"female"并注释 "SMPL+H has no neutral model, so we have to manually select the gender",可按实际数据在male/female间切换; - 优化器因方向而异:SMPL-X 方向的模板默认用
trust-ncg(100 次迭代),而 SMPL-X → SMPL / SMPL+H 方向的模板改用lbfgs(200 次迭代);smplh2smplx_onepose.yaml 还提供了一个adam(lr: 0.1、maxiters: 10000)的变体,可作为调参参考。
YAML 配置项详解
transfer_model 的配置是默认值 + YAML 覆盖 + 命令行覆盖三层合并:cmd_parser.py 先把 defaults.py 的 Config(基于 omegaconf 的 dataclass)作为底,再 merge_with 加载 --exp-cfg 指定的 YAML,最后用 --exp-opts 提供的命令行键值覆盖。以下按 smpl2smplx.yaml 的实际键逐项说明:
datasets:输入网格目录
datasets:
mesh_folder:
data_folder: 'transfer_data/meshes/smpl'
默认类为 DatasetConfig:name 固定为 mesh-folder,num_workers 默认 0,mesh_folder.data_folder 默认 data/meshes。该目录中的 .obj/.ply 文件即逐帧输入。
deformation_transfer_path:变形转移矩阵
deformation_transfer_path: 'transfer_data/smpl2smplx_deftrafo_setup.pkl'
指向与转换方向对应的 pkl 文件,由 read_deformation_transfer() 加载为 float32 张量;文件不存在会直接断言报错(路径检查)。
mask_ids_fname:有效顶点掩码
mask_ids_fname: 'smplx_mask_ids.npy'
仅当目标模型顶点多于源模型有效区域(如 SMPL/SMPL+H → SMPL-X)时需要;目标为 SMPL/SMPL+H 时配置留空字符串即可(参见 smplx2smpl.yaml 中 mask_ids_fname: '')。文件缺失时程序会警告并继续(main.py L66-L74)。
edge_fitting / optim:损失与优化器
edge_fitting:
per_part: False
optim:
type: 'trust-ncg'
maxiters: 100
gtol: 1e-06
edge_fitting.per_part(默认 False,见 defaults.py):是否按关节逐个优化姿态;为 True 时对每个 pose 组、每个关节索引单独跑一轮最小化(run_fitting per_part 分支),代价更高但局部收敛更稳;optim.type支持的值由 build_optimizer() 决定:adam、lbfgs/lbfgsls、trust_ncg/trust-ncg、rmsprop、sgd;其中trust-ncg来自 torch-trust-ncg 库且需要二阶导(create_graph=True);maxiters(默认 100)、gtol(默认 1e-8)、ftol(默认 -1.0)以及各优化器的子节(lbfgs.line_search_fn='strong_wolfe'、sgd.momentum=0.9等,见 OptimConfig)均可按方向调整。
body_model:目标模型定义
body_model:
model_type: "smplx"
gender: "neutral"
folder: "transfer_data/body_models"
use_compressed: False
use_face_contour: True
smplx:
betas:
num: 10
expression:
num: 10
对应 BodyModelConfig:
model_type(smplx/smplh/smpl等)决定 get_variables() 中初始化的参数集合,也是 main.py 中 build_layer 的模型类型;folder指向模型文件目录(pkl 或 npz,ext字段切换,SMPL/SMPL+H 模板用ext: 'pkl');use_compressed控制是否加载压缩版 SMPL 模型;use_face_contour控制是否使用 SMPL-X 面部轮廓;smplx.betas.num: 10、smplx.expression.num: 10指定 β 与表情系数维数(默认均为 10,见 Shape/Expression 定义),需与smplx.create生成的模型一致。
其他全局键
summary_steps(默认 5,模板设为 100):每 N 步记录一次Vertex-to-Vertex误差(毫米,见 summary_closure);use_cuda(默认 True):无 GPU 时会交互式询问是否改用 CPU(main.py L39-L46);output_folder(默认output):pkl/obj 输出目录;interactive(默认 True)、batch_size(默认 1)等亦可在 YAML 中覆盖。
源码架构与执行链路速览
从源码结构看,整条链路为:
python -m transfer_model
└─ __main__.main() # 解析配置、设备、模型、掩码
├─ config.parse_args() # 默认配置 + YAML + CLI 三层合并
├─ smplx.build_layer(...) # 加载目标 body model
├─ read_deformation_transfer() # 加载变形转移矩阵
├─ build_dataloader() # MeshFolder 读取逐帧 obj/ply
└─ run_fitting() 逐 batch
├─ get_variables() # 按模型类型初始化待优化参数
├─ apply_deformation_transfer() # 源网格 → 目标拓扑网格
├─ edge 优化(可选 per-part)
├─ translation 优化
└─ vertex 全参数优化
输出:每帧 <name>.pkl(参数) + <name>.obj(拟合网格)
关键文件与职责:
| 文件 | 职责 |
|---|---|
| transfer_model/main.py | 入口:配置、设备、模型加载、逐帧拟合与结果落盘 |
| transfer_model/transfer_model.py | run_fitting() 三阶段优化、get_variables() 参数初始化、per-part 关节级优化 |
| transfer_model/losses/losses.py | build_loss() 工厂与 VertexEdgeLoss、WeightedMSELoss |
| transfer_model/optimizers/optim_factory.py | build_optimizer():sgd/adam/lbfgs/rmsprop/trust-ncg 五种优化器 |
| transfer_model/utils/def_transfer.py | 变形转移矩阵的读取与应用 |
| transfer_model/data/datasets/mesh.py | MeshFolder:目录扫描 + trimesh 逐帧加载 |
| transfer_model/write_obj.py / merge_output.py | 流程首尾:动作展开为逐帧网格、逐帧结果合并为 merged.pkl |
| transfer_model/view_pkl.py | 用 pyrender 逐帧可视化 pkl 中的参数/网格,用于人工检查 |
其中 view_pkl.py 值得一提:它兼容 AMASS 风格的 npz(会把 root_orient→global_orient、pose_body→body_pose、pose_hand 切分为左右手),可以加载 merged.pkl 类数据逐帧预览转换结果,是验证输出质量的实用工具。
可视化顶点对应关系
README 提供了对应关系可视化命令:
python vis_correspondences.py --exp-cfg configs/smpl2smplx.yaml --exp-opts colors_path PATH_TO_SMPL_COLORS
渲染结果中颜色相近的点互为对应点(即上文配图的效果)。需要说明的是:当前仓库镜像的 transfer_model/ 目录下并没有 vis_correspondences.py 脚本(目录中仅有 __main__.py、write_obj.py、merge_output.py、view_pkl.py 等),该命令沿用的是上游文档写法;在当前仓库中可直接参考 docs/images 下的对应关系图 来理解映射效果。
许可、引用与致谢
- 本工具为非商业科研用途的许可软件,使用即视为接受 LICENSE 条款;
- 转换得到的参数归属哪个模型,就引用相应工作(README 给出了三条 BibTeX,摘录 SMPL-X 一条):
@inproceedings{SMPL-X:2019,
title = {Expressive Body Capture: 3D Hands, Face, and Body from a Single Image},
author = {Pavlakos, Georgios and Choutas, Vasileios and Ghorbani, Nima and Bolkart, Timo and Osman, Ahmed A. A. and Tzionas, Dimitrios and Black, Michael J.},
booktitle = {Proceedings IEEE Conf. on Computer Vision and Pattern Recognition (CVPR)},
year = {2019}
}
另两条(SMPL 2015、SMPL+H/MANO 2017)完整条目见 transfer_model/README.md 的 Citation 一节。代码由 Vassilis Choutas 实现,基于 Timo Bolkart 的 Chumpy 版本实现;问题可联系 smplx@tue.mpg.de。
小结与常见问题
- 不要把参数从一个模型直接拷到另一个模型——shape space 与关节布局均不同,必须通过本工具的拟合流程转换;
- 转换到 SMPL/SMPL+H 时,源网格生成时不要启用目标模型无法表达的参数(SMPL-X 的面部/表情、手部),否则拟合只会引入误差;
- 遇到不收敛或结果异常时,可先调
summary_steps观察Vertex-to-Vertex误差曲线,再调整optim.type(如trust-ncg↔lbfgs↔adam)与maxiters;per_part: True可获得更稳的姿态初始化; - 所有路径均为相对仓库根目录的引用,配置模板集中在 config_files/,算法细节在 transfer_model/docs/transfer.md,核心实现位于 transfer_model/ 目录。
