SMPL-X 仓库 transfer_model 详解:在 SMPL、SMPL+H 与 SMPL-X 之间安全转换模型参数

原创2026-10-14 14:20:211,340 阅读
文章标签:计算机视觉图形学

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 不兼容。每个模型都是独立训练过程的产物,即便两个模型的 β\beta 数值相同,编码的体型语义也不同;
  • SMPL-X 的关节位置与 SMPL 不同,因此 pose(θ\theta)参数不可互换——这一点在 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 条目 也说明了这批转换代码是随仓库一并发布的。

SMPL 与 SMPL-X 顶点对应关系可视化,颜色相近的点互为对应点,左侧为 SMPL,右侧为 SMPL-X

转换原理:对应关系、变形转移与三阶段优化

这一节基于 docs/transfer.md 的完整算法描述,并对照源码逐点印证。

1. 建立网格间对应关系

由于 SMPL 与 SMPL-X 的网格拓扑不同(SMPL-X 多了手部与面部的细分网格),首先需要一份“SMPL-X 模板网格注册到 SMPL 模板”的映射。映射方式为:对每个 SMPL-X 顶点,找到 SMPL 网格上的最近点,并存储:

  • 最近点所在三角形的索引 tit_i;
  • 该点相对于 SMPL 三角形的重心坐标 [ai,bi,ci][a_i, b_i, c_i]。

由于 SMPL-X 与 SMPL 在颈部以上共享拓扑,这些重心坐标是 [1.0,0.0,0.0][1.0, 0.0, 0.0] 的置换。工具同时保存一个有效顶点掩码,用于剔除两个网格之间无对应关系的点(如眼球、口腔内部)。上文配图即为按对应关系着色后的两个网格(左 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() 的实现一一对应:

  1. 边长损失初始化姿态(3D edge term)。只使用两个网格中端点均有效的边,损失为:

    L1(θ)=∑(i,j)∈Emimj∥(vi−vj)−(v^i−v^j)∥22L_1(\theta) = \sum_{(i,j) \in \mathcal{E}} m_i m_j \lVert (v_i - v_j) - (\hat{v}_i - \hat{v}_j) \rVert_2^2

    源码对应 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 分支)。

  2. 平移向量 γ\gamma 对齐两个模型:

    L2(γ)=∑imi∥vi−v^i∥L_2(\gamma) = \sum_i m_i \lVert v_i - \hat{v}_i \rVert

    源码中当 var_dict 含 translation 时执行该阶段(translation 优化)。

  3. 全参数顶点拟合,得到最紧的拟合:

    L3((θ,β,ψ,γ))=∑imi∥vi−v^i∥22L_3((\theta, \beta, \psi, \gamma)) = \sum_i m_i \lVert v_i - \hat{v}_i \rVert_2^2

    源码中用 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):

  1. 安装 mesh(MPI-IS/mesh,即 psbody,被 MeshFolder 数据集 导入);
  2. 克隆 SMPL-X 仓库;
  3. 安装依赖:pip install -r requirements.txt(对应 transfer_model/requirements.txt:numpy、torch、dataclasses、pyrender、shapely、trimesh、open3d、smplx、omegaconf、loguru);
  4. 按 Torch Trust Region optimizer 官方说明安装(源码在 optim_factory.py 中 from torchtrustncg import TrustRegion);
  5. 安装 loguru;
  6. 安装 open3d(用于写出 .obj 结果网格);
  7. 安装 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/ 目录。
登录后查看全文
smplx