Deep-motion-editing

本库提供了在深度学习中使用 PyTorch 进行 3D 角色动画处理的基础和高级功能。代码包含端到端模块，从读取和编辑动画文件到使用 Blender 进行可视化和渲染。

此处提供的主要深度编辑操作——动作重定向 (Motion Retargeting) 和 动作风格迁移 (Motion Style Transfer)，基于两篇发表于 SIGGRAPH 2020 的论文：

Skeleton-Aware Networks for Deep Motion Retargeting: 项目 | 论文 | 视频

Unpaired Motion Style Transfer from Video to Animation: 项目 | 论文 | 视频

本库由 Kfir Aberman、Peizhuo Li 和 Yijia Weng 编写和维护。该库仍在开发中。

前置要求

• Linux 或 macOS
• Python 3
• CPU 或 NVIDIA GPU + CUDA CuDNN

快速开始

我们提供了预训练模型以及使用指定为 bvh 格式的动画文件的演示示例。

动作重定向 (Motion Retargeting)

从 Google Drive 或 百度网盘 (ye1q) 下载并解压测试数据集。然后将 Mixamo 目录放置在 retargeting/datasets 内。

要使用预训练模型生成演示示例，请运行

cd retargeting
sh demo.sh

结果将保存在 retargeting/examples 中。

要使用预训练模型重建定量结果，请运行

cd retargeting
python test.py

重定向后的演示结果，包括结构内重定向 (intra-structual retargeting) 和跨结构重定向 (cross-structural retargeting)，将保存在 retargeting/pretrained/results 中。

动作风格迁移 (Motion Style Transfer)

要获取演示示例，只需运行

sh style_transfer/demo.sh

结果将保存在 style_transfer/demo_results 中， 其中每个文件夹包含原始输出 raw.bvh 和经过脚部滑行清理 (footskate clean-up) 后的输出 fixed.bvh。

从头训练

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

动作重定向

数据集

我们使用 Mixamo 数据集来训练模型。您可以从 Google Drive 或 百度网盘(4rgv) 下载我们预处理的数据。然后将 Mixamo 目录放置在 retargeting/datasets 内。

否则，如果您想自行下载 Mixamo 数据集或使用自己的数据集，请遵循以下说明。除非特别说明，所有脚本应在 retargeting 目录下运行。

• 若要自行下载 Mixamo，可参考 此 优秀教程。您需要下载 fbx 文件（不需要皮肤），并在 retargeting/datasets/Mixamo 下为每个角色创建子目录。在我们的原始实现中，我们下载了 60fps 的 fbx 文件并将其降采样为 30fps。由于我们在训练中使用无配对方式，建议将所有动作分为两组大小相等的集合，并为每组中的每个角色分配大小相等的集合。如果您使用自己的数据，需要确保您的数据集由具有相同 T 姿势 (t-pose) 的 bvh 文件组成。您还应将数据集放在 retargeting/datasets/Mixamo 的子目录中。

• 进入 retargeting/datasets 目录并运行 blender -b -P fbx2bvh.py 将 fbx 文件转换为 bvh 文件。如果您已经有 bvh 文件作为数据集，请跳过此步骤。

• 在我们的原始实现中，我们手动分割了 group A 中骨架的三个关节。如果您想遵循我们的流程，请运行 python datasets/split_joint.py。此步骤是可选的。

• 运行 python datasets/preprocess.py 通过移除一些不太重要的关节（例如手指）来简化骨架，并将 bvh 文件转换为 npy 文件。如果您使用自己的数据，需要在 retargeting/datasets/bvh_parser.py 中定义简化的结构。此信息目前硬编码在代码中。有关更多详细信息，请参阅源文件中的注释。让您的数据集工作的步骤有四个。

• 训练和测试的角色在 retargeting/datasets/__init__.py 中是硬编码的。如果您想使用自己的数据集，需要修改它。

训练

准备好数据集后，只需运行

cd retargeting
python train.py --save_dir=./training/

它将使用默认超参数 (hyper-parameters) 训练模型，并将训练好的模型保存在 retargeting/training 目录中。更多选项可在 retargeting/option_parser.py 中找到。您可以通过运行以下命令使用 TensorBoard 监控训练进度

tensorboard --logdir=./retargeting/training/logs/

动作风格迁移

数据集

• 从 Google Drive 或 Baidu Drive (提取码：zzck) 下载数据集。数据集由两部分组成：一部分来自 Xia et al. 提出的动作风格迁移数据集，另一部分是我们的 BFA 数据集，其中两部分都包含针对 CMU mocap 数据集 (动作捕捉数据集) 标准骨架重定向的 .bvh 文件。

• 将 .zip 文件解压到 style_transfer/data

• 为训练预处理数据：

  cd style_transfer/data_proc
  sh gen_dataset.sh
  

  这将在 style_transfer/data 中生成 xia.npz, bfa.npz。

训练

下载数据集后，直接运行

python style_transfer/train.py

来自视频的样式

要在测试阶段使用自己的视频运行我们的模型，您首先需要使用 OpenPose (姿态估计工具) 从视频中提取 2D 关节位置，然后按照示例演示中使用生成的 JSON 文件。

Blender 可视化

我们提供了一个简单的 Blender Python API (2.80) 包装器用于渲染 3D 动画。

前置条件

从 blender.org 分发的 Blender 版本在所有平台上都包含完整的 Python 安装，这意味着您在系统 Python 中安装的任何扩展都不会出现在 Blender 中。

要使用外部 Python 库，您可以直接将新包安装到 Blender 的 Python 发行版中。或者，您可以通过以下方式更改默认的 Blender Python 解释器：

1. 删除内置的 python 目录：[blender_path]/2.80/python。

2. 创建一个符号链接或直接复制一个 python 解释器到 [blender_path]/2.80/python。例如：ln -s ~/anaconda3/envs/env_name [blender_path]/2.80/python

该解释器应为 python 3.7.x 版本，并至少包含：numpy, scipy。

使用方法

参数

由于 Blender 的 argparse 系统，参数列表应与 python 文件用额外的 '--' 分隔，例如：

blender -P render.py -- --arg1 [ARG1] --arg2 [ARG2]

engine: "cycles" 或 "eevee"。更多详细信息请参考 Render 部分。

render: 0 或 1。如果设置为 1，数据将在 Blender GUI 之外渲染。如果您需要手动调整相机，建议使用 render = 0。

完整参数列表可以通过以下命令显示： blender -P render.py -- -h

加载 bvh 文件 (load_bvh.py)

要加载 example.bvh，请运行 blender -P load_bvh.py。请先完成准备工作。

注意，目前它使用具有 5 个顶点的 primitive_cone 作为肢体。

注意，Blender 和 bvh 文件有不同的 xyz 坐标系。在 bvh 文件中，“高度”轴是 y 轴，而在 Blender 中它是 z 轴。load_bvh.py 在 BVH_file 类初始化函数中交换了轴。

目前 bvh 文件中的所有 End Sites 都被丢弃，这是因为 utils/ 中使用的外部代码。

加载 bvh 文件后，其高度被归一化为 10。

材质、纹理、灯光和相机 (scene.py)

此文件允许向场景添加棋盘格地板、相机、“太阳”，并为角色应用基本颜色材质。

地板放置在 y=0 处，如果需要（取决于 bvh 文件中的角色参数），应手动修正。

渲染

我们支持 Blender 2.80 提供的两种渲染引擎：Eevee 和 Cycles，权衡在于速度和画质。

Eevee（左）是一种快速、实时的渲染引擎，提供有限的画质；而 Cycles（右）是一种较慢、无偏置的光线追踪 (ray-tracing) 渲染引擎，提供照片级渲染结果。Cycles 还支持 CUDA 和 OpenGL 加速。

蒙皮

自动蒙皮

我们提供了一个 Blender 脚本，用于对输出骨架应用“蒙皮”(skinning)。您首先需下载对应目标角色的 fbx 文件（例如，"mousey"）。然后，只需运行即可获取蒙皮动画：

blender -P blender_rendering/skinning.py -- --bvh_file [bvh file path] --fbx_file [fbx file path]

注意，该脚本可能无法对所有 fbx 和 bvh 文件正常工作。如果失败，您可以尝试调整脚本或遵循下面的手动蒙皮指南。

手动蒙皮

这里我们提供一个“快速且粗糙”的指南，说明如何在 Blender 中将皮肤应用到生成的 bvh 文件：

• 下载对应重定向角色的 fbx 文件（例如，"mousey")
• 将 fbx 文件导入 Blender（取消勾选“import animation"选项）
• 合并网格 - 选择所有部分并合并它们 (ctrl+J)
• 导入重定向后的 bvh 文件
• 点击“上下文” (菜单栏) -> “休息位置” (在骨架下)
• 手动对齐网格和骨架（旋转 + 平移）
• 选择骨架和网格（骨架对象应高亮显示）
• 点击 对象 -> 父级 -> 带自动权重 (或 Ctrl+P)

现在骨架和皮肤已绑定，动画可以进行渲染。

致谢

utils 目录中的代码主要取自 Holden et al. [2016]。
此外，部分 MoCap 数据集 (动作捕捉数据集) 取自 Adobe Mixamo 以及 Xia et al. 的工作。

引用

如果您在本研究中使用此代码，请引用我们的论文：

@article{aberman2020skeleton,
  author = {Aberman, Kfir and Li, Peizhuo and Sorkine-Hornung Olga and Lischinski, Dani and Cohen-Or, Daniel and Chen, Baoquan},
  title = {Skeleton-Aware Networks for Deep Motion Retargeting},
  journal = {ACM Transactions on Graphics (TOG)},
  volume = {39},
  number = {4},
  pages = {62},
  year = {2020},
  publisher = {ACM}
}

and

@article{aberman2020unpaired,
  author = {Aberman, Kfir and Weng, Yijia and Lischinski, Dani and Cohen-Or, Daniel and Chen, Baoquan},
  title = {Unpaired Motion Style Transfer from Video to Animation},
  journal = {ACM Transactions on Graphics (TOG)},
  volume = {39},
  number = {4},
  pages = {64},
  year = {2020},
  publisher = {ACM}
}

Deep-Motion-Editing 快速上手指南

Deep-Motion-Editing 是一个基于深度学习的 3D 角色动画编辑库，支持动作重定向（Retargeting）和动作风格迁移（Style Transfer）。本指南将帮助您快速配置环境并运行官方预训练模型示例。

1. 环境准备

请确保您的开发环境满足以下要求：

• 操作系统: Linux 或 macOS
• Python: 版本 >= 3.7
• 深度学习框架: PyTorch >= 1.5.0
• 图形渲染: Blender >= 2.8 (用于可视化与渲染)
• 硬件: CPU 或 NVIDIA GPU (需安装 CUDA + CuDNN)

注意: 若需在 Blender 中使用外部 Python 库，请参考官方文档配置 Blender 的 Python 解释器路径。

2. 安装与数据准备

克隆代码库

git clone https://github.com/KfirAberman/deep-motion-editing.git
cd deep-motion-editing

安装依赖

根据系统环境安装 PyTorch 及相关依赖（具体命令参考 PyTorch 官网）：

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# 其他依赖如 numpy, scipy 等通常包含在基础环境中

下载数据集与模型

为了运行演示，您需要下载测试数据集和预训练模型。推荐使用国内加速源：

1. Mixamo 数据集:

   • 百度网盘 (提取码：ye1q)
   • 下载后解压，将 Mixamo 目录放入 retargeting/datasets/ 下。

2. 风格迁移数据集 (可选):

   • 百度网盘 (提取码：zzck)
   • 解压至 style_transfer/data/。

3. 基本使用

工具提供了预训练模型，可直接运行脚本生成结果。

动作重定向 (Motion Retargeting)

将一种骨骼结构的动作应用到另一种骨骼结构上。

cd retargeting
sh demo.sh

• 输出位置: retargeting/examples
• 量化结果: retargeting/pretrained/results

如需自定义输入，可运行：

python test.py -model_path MODEL_PATH -input_A PATH_A -input_B PATH_B -edit_type retargeting

动作风格迁移 (Motion Style Transfer)

将内容动作的风格转换为目标风格（支持 3D MoCap 或 2D 视频关键点）。

sh style_transfer/demo.sh

• 输出位置: style_transfer/demo_results
  • raw.bvh: 原始输出
  • fixed.bvh: 脚部滑动修复后的输出

如需自定义输入：

python test.py -model_path retargeting/models/pretrained_style_transfer.pth -input_A style_transfer/examples/content_input -input_B style_transfer/examples/3D_style_input -edit_type style_transfer

4. 可视化与渲染 (可选)

生成的 .bvh 文件可使用内置的 Blender 脚本进行加载、材质贴图及渲染。

• 加载 BVH:

  blender -P load_bvh.py
  

• 自动蒙皮 (Skinning): 需先下载对应的 FBX 角色模型，然后运行：

  blender -P blender_rendering/skinning.py -- --bvh_file [bvh 文件路径] --fbx_file [fbx 文件路径]
  

• 渲染引擎: 支持 Eevee (快速) 和 Cycles (高质量)。

---

注：该库仍在持续开发中，部分功能可能随版本更新而变化。