介绍

https://user-images.githubusercontent.com/81355712/187817864-37c984a5-032d-492b-8314-493a23c27e5e.mp4

XRMoGen 是一个开源的动作生成代码库。 目前，XRMoGen中包含以下两种舞蹈生成的方法：

• Bailando: Siyao et al., Bailando: 3D Dance Generation by Actor-Critic GPT with Choreographic Memory, CVPR 2022
• DanceRevolution: Huang et al., Dance Revolution: Long-Term Dance Generation with Music via Curriculum Learning, ICLR 2021

关于安装部分的介绍，参见installation.md。

• 上手指南
  • 数据集
  • 构建模型
    • 如何构建新的模型
  • 模型训练
    • Epoch 控制
    • 训练
    • 测试
    • 可视化
  • 教程

数据集

我们推荐使用预提取特征的音乐和动作数据，参见dataset_preparation.md。 下载后解压至$PROJECT/data。为了方便在生成舞蹈后合成有音乐的视频，建议将原始音乐（.mov）下载到同一目录的的musics文件夹下：

xrmogen
├── mogen
├── docs
├── configs
├── data
│   ├── aistpp_train_wav
│   ├── aistpp_test_full_wav
│   ├── aistpp_music_feat_7.5fps
│   ├── aist_features_zero_start
│   ├── musics
├── ...

构建模型

模型结构由配置文件（config）来控制。

如何构建新的模型

要实现新的方法，模型需要包含以下的函数/方法以适应当前的训练/测试流程：

• train_step(): 模型训练的正向过程；
• val_step(): 模型测试的正向过程；
• 将模型注册为一个DANCE_MODELS

具体来说，如果我们想实现一个新模型，有几件事要做：

1. 在mogen/models/dance_models/下创建一个新模型my_model.py：

   from ..builder import NETWORKS
   from ...builder import DANCE_MODELS
   
   @DANCE_MODELS.register_module()
   class MyDanceModel(nn.Module):
   
       def __init__(self, model_config):
           super().__init__()
   
       def forward(self, ...):
           ....
   
       def train_step(self, data, optimizer, **kwargs):
           ....
   
       def val_step(self, data, optimizer=None, **kwargs):
           ....

2. 在mogen/models/__init__.py中导入新模型：

   from .my_model import MyDanceModel

3. 将新模型的构建参数写进需要的config文件：

   model = dict(
       type='MyDanceModel',
       ....

模型训练

Epoch 控制

XRMoGen 使用 mmcv.runner.EpochBasedRunner （以epoch为单位）去训练和测试模型.

在训练模式下， config文件中的 max_epochs 参数决定了模型被训练多少epoch。 在测试模式下, max_epochs 被强制设置为1，即将测试数据测试一遍。

训练、测试交替的频率在config文件中的 workflow 设定:

 workflow = [('train', 20), ('val', 1)]

训练

比如，为了训练DanceRevolution模型，运行以下命令

python main.py --config configs/dance_rev.py

参数:

• --config: config 文件路径

测试

测试相应的模型，只需要在config路径后添加 --test_only。 我们提供一些与训练的模型权重进行测试（参见pretrained_model_list.md。将预训练模型下载至文件夹./example中，运行

python main.py --config configs/bailando_test.py --test_only

来生成舞蹈动作。所生成的舞蹈将以.pkl格式存于config文件中所设置的workdir下（在本例中是"./bailando_test"）。

对生成的舞蹈动作计算量化指标：

python tools/eval_quantitative_scores.py --pkl_root ./bailando_test/test/epoch0 --gt_root data/aist_features_zero_start --music_feature_root data/aistpp_test_full_wav

测试结果应和benchmark.md相吻合。

可视化

python tools/visualize_dance_from_pkl.py --pkl_root ./bailando_test/test/epoch0 --audio_path data/musics/

教程

目前我们提供以下教程

• configs
• data pipeline
• model

许可

我们代码库的许可证是Apache-2.0。请注意，此许可仅适用于我们库中的代码，其依赖项是单独许可的。我们向我们所依赖的开源实现致敬。请注意，使用依赖项的内容可能会影响我们代码库的许可。请参阅许可证以查看完整许可证。

引用

@misc{xrmogen,
    title={OpenXRLab Motion Generation Codebase},
    author={XRMoGen Contributors},
    howpublished = {\url{https://github.com/openxrlab/xrmogen}},
    year={2022}
}

参与贡献

我们非常欢迎用户对于 XRMoGen 做出的任何贡献，可以参考 CONTRIBUTION.md 文件了解更多细节。

致谢

XRMoGen 是一款由学校和公司共同贡献的开源项目。我们感谢所有为项目提供算法复现和新功能支持的贡献者，以及提供宝贵反馈的用户。 我们希望该工具箱和基准测试可以为社区提供灵活的代码工具，供用户复现现有算法并开发自己的新模型，从而不断为开源社区提供贡献。

OpenXRLab中的其他项目

• XRPrimer: OpenXRLab foundational library for XR-related algorithms.
• XRSLAM: OpenXRLab Visual-inertial SLAM Toolbox and Benchmark.
• XRSfM: OpenXRLab Structure-from-Motion Toolbox and Benchmark.
• XRLocalization: OpenXRLab Visual Localization Toolbox and Server.
• XRMoCap: OpenXRLab Multi-view Motion Capture Toolbox and Benchmark.
• XRMoGen: OpenXRLab Human Motion Generation Toolbox and Benchmark.
• XRNeRF: OpenXRLab Neural Radiance Field (NeRF) Toolbox and Benchmark.