使用神经混合形状（Neural Blend Shapes）学习骨骼关节运动（Skeletal Articulations）

本仓库提供了一个端到端（end-to-end）的库，用于自动角色绑定（rigging）、蒙皮（skinning）和混合形状（blend shapes）生成，以及一个可视化工具。它基于我们在 SIGGRAPH 2021 上发表的工作 Learning Skeletal Articulations with Neural Blend Shapes。

前提条件

我们的代码已在 Ubuntu 18.04 上测试过。开始之前，请通过以下命令配置您的 Anaconda 环境：

conda env create -f environment.yaml
conda activate neural-blend-shapes

或者您可以手动安装以下包（及其依赖）：

• pytorch 1.8
• tensorboard
• tqdm
• chumpy

注意，提供的环境仅包含 PyTorch CPU 版本，以考虑兼容性。

快速开始

我们提供了一个专为双足角色（biped characters）设计的预训练模型。从 Google Drive 或 百度网盘 (9ras) 下载并解压预训练模型，并将 pre_trained 文件夹放在项目目录下。运行：

python demo.py --pose_file=./eval_constant/sequences/greeting.npy --obj_path=./eval_constant/meshes/maynard.obj

上述精彩的问候动画将作为 obj 文件保存在 demo/obj 中。此外，生成的骨骼（skeleton）将保存为 demo/skeleton.bvh，蒙皮权重矩阵（skinning weight matrix）将保存为 demo/weight.npy。如果您需要动画化的 bvh 文件，可以指定 --animated_bvh=1。

如果您对我们绑定生成的传统线性混合蒙皮（Linear Blend Skinning, LBS）技术结果感兴趣，您可以指定 --envelope_only=1 仅使用包络分支（envelope branch）评估我们的模型。

我们还提供了其他几个网格（meshes）和动画序列。欢迎尝试它们的组合！

FBX 输出（新！）

现在您可以选择将动画输出为单个 fbx 文件，而不是一系列 obj 文件！只需执行以下操作：

python demo.py --animated_bvh=1 --obj_output=0
cd blender_scripts
blender -b -P nbs_fbx_output.py -- --input ../demo --output ../demo/output.fbx

注意，您需要安装 Blender (>=2.80) 来生成 fbx 文件。您可以在源代码中探索生成 fbx 文件的更多选项。

此代码由 @huh8686 贡献。

在自定义网格上测试

您可以通过将 --obj_path 参数指向输入网格（mesh），尝试使用您自己的网格运行我们的模型。请确保您的网格已三角化，并且具有 consistent 的正立和朝前朝向。由于我们的模型要求输入网格在空间上对齐，请指定 --normalize=1。或者，您可以尝试缩放和平移您的网格以对齐提供的 eval_constant/meshes/smpl_std.obj，而不指定 --normalize=1。

评估

要使用预训练模型重建定量结果，您需要从 Google Drive 或 百度网盘 (8b0f) 下载测试数据集，并将两个解压后的文件夹放在 ./dataset 下，然后运行：

python evaluation.py

从头训练

我们提供了重新训练模型的说明。

注意，您可能需要重新安装 PyTorch CUDA 版本，因为提供的环境仅包含 PyTorch CPU 版本。

要从头训练模型，您需要从 Google Drive 或 百度网盘 (uqub) 下载训练集，并将解压后的文件夹放在 ./dataset 下。

训练过程包含两个阶段，每个阶段对应一个分支。要训练第一阶段，请运行：

python train.py --envelope=1 --save_path=[path to save the model] --device=[cpu/cuda:0/cuda:1/...]

对于第二阶段，强烈建议使用预处理来提取混合形状基（blend shapes basis），然后通过以下命令开始训练以获得更高的效率：

python preprocess_bs.py --save_path=[same path as the first stage] --device=[computing device]
python train.py --residual=1 --save_path=[same path as the first stage] --device=[computing device] --lr=1e-4

Blender 可视化

我们提供了一个 Blender Python API (>=2.80) 的简单封装（wrapper），用于渲染 3D 网格动画和可视化蒙皮权重。以下代码已在 Ubuntu 18.04 和 macOS Big Sur 上使用 Blender 2.92 测试过。

注意，由于 Blender 的限制，您无法在无头机器（headless machine）上运行 Eevee 渲染引擎。

我们还提供了几个参数来控制脚本的行为。请参阅代码了解更多详情。要将参数传递给 Blender 中的 Python 脚本，请执行以下操作：

blender [blend file path (optional)] -P [python script path] [-b (running at backstage, optional)] -- --arg1 [ARG1] --arg2 [ARG2]

动画

我们在 eval_constant/simple_scene.blend 中提供了简单的灯光和相机设置。使用前您可能需要调整它。我们使用 ffmpeg 将图像转换为视频。请确保在运行前已安装它。要渲染上述生成的 obj 文件，运行：

cd blender_script
blender ../eval_constant/simple_scene.blend -P render_mesh.py -b

渲染后的每帧图像将保存在 demo/images 中，合成视频将保存为 demo/video.mov。

蒙皮权重

可视化蒙皮权重是一个很好的健全性检查（sanity check），用于查看模型是否按预期工作。我们提供了一个脚本，使用 Blender 内置的 ShaderNodeVertexColor 来可视化蒙皮权重。只需运行：

cd blender_script
blender -P vertex_color.py

如果模型按预期工作，您将看到类似以下内容：

同时，您可以将生成的骨骼（在 demo/skeleton.bvh 中）导入到 Blender。关于骨骼渲染，请参考 deep-motion-editing。

致谢

blender_scripts/nbs_fbx_output.py 中的代码由 @huh8686 贡献。

meshcnn 中的代码改编自 @ranahanocka 的 MeshCNN。

models/skeleton.py 中的代码改编自 @kfiraberman、@PeizhuoLi 和 @HalfSummer11 的 deep-motion-editing。

dataset/smpl.py 中的代码改编自 @CalciferZh 的 SMPL。

部分测试模型取自 SMPL、MultiGarmentNetwork 和 Adobe Mixamo。

引用

如果您将此代码用于研究，请引用我们的论文：

@article{li2021learning,
  author = {Li, Peizhuo and Aberman, Kfir and Hanocka, Rana and Liu, Libin and Sorkine-Hornung, Olga and Chen, Baoquan},
  title = {Learning Skeletal Articulations with Neural Blend Shapes},
  journal = {ACM Transactions on Graphics (TOG)},
  volume = {40},
  number = {4},
  pages = {130},
  year = {2021},
  publisher = {ACM}
}

neural-blend-shapes 快速上手指南

简介

neural-blend-shapes 是一个端到端的库，用于自动角色绑定（Rigging）、蒙皮（Skinning）和混合形状（Blend Shapes）生成。本项目基于 SIGGRAPH 2021 论文 Learning Skeletal Articulations with Neural Blend Shapes。

环境准备

在开始之前，请确保满足以下系统要求和依赖：

• 操作系统: Ubuntu 18.04 (已测试)
• Python: >= 3.8
• PyTorch: >= 1.8.0 (预置环境为 CPU 版本，如需 GPU 训练请自行安装 CUDA 版本)
• Blender: >= 2.8 (可选，用于 FBX 导出和可视化)
• 依赖包: tensorboard, tqdm, chumpy

安装步骤

1. 配置 Anaconda 环境 推荐使用 Conda 创建隔离环境：

   conda env create -f environment.yaml
   conda activate neural-blend-shapes
   

2. 下载预训练模型 下载专为双足角色设计的预训练模型，并解压将 pre_trained 文件夹置于项目根目录下。

   • 百度网盘 (推荐国内用户): 下载链接 (提取码: 9ras)
   • Google Drive: 下载链接

基本使用

1. 运行演示脚本

使用提供的网格和动作序列生成动画。以下命令将生成问候动画：

python demo.py --pose_file=./eval_constant/sequences/greeting.npy --obj_path=./eval_constant/meshes/maynard.obj

输出文件说明：

• demo/obj: 生成的动画网格序列 (obj 格式)
• demo/skeleton.bvh: 生成的骨骼文件
• demo/weight.npy: 蒙皮权重矩阵

若需要生成动态 BVH 文件，可添加参数 --animated_bvh=1。

2. 导出 FBX 动画 (可选)

如需将动画导出为单个 FBX 文件，需安装 Blender (>=2.80) 并执行以下步骤：

python demo.py --animated_bvh=1 --obj_output=0
cd blender_scripts
blender -b -P nbs_fbx_output.py -- --input ../demo --output ../demo/output.fbx

3. 测试自定义网格

您可以使用自己的网格文件进行测试，请确保网格已三角化且方向一致（ upright and front facing）。由于模型要求输入网格空间对齐，建议启用归一化参数：

python demo.py --pose_file=./eval_constant/sequences/greeting.npy --obj_path=[您的网格路径] --normalize=1