Skip to content

Latest commit

 

History

History
278 lines (212 loc) · 9.24 KB

cn-README.md

File metadata and controls

278 lines (212 loc) · 9.24 KB

./resource/imgs/logo.png

English README ｜ 教程视频（即将发布）

❓ 什么是UniMoCap？

UniMoCap是用于统一文本-动作动捕数据集的社区实现。在这个仓库中，我们统一了基于AMASS的文本-动作数据集（HumanML3D、BABEL和KIT-ML）。我们支持处理AMASS数据的两种格式：

  • 仅身体的H3D格式（263维，24个关节）
  • 全身的的SMPL-X格式（322维 SMPL-X参数）。

我们相信这个仓库对于在更大的文本-动作数据上训练模型将会非常有用。我们会在不久的将来整合更多的文本-动作动捕数据集。

我们尽可能简化了数据处理过程。对于对数据集不熟悉的朋友，在接下来的几周，我们将提供一个视频教程来告诉您如何完成。

🏃🏼 TODO List

  • 支持SMPL-X动作表示计算（包括手和身体的位置、速度、旋转，预计1-2周内）。
  • 支持seg和seq两种BABEL的标注子集。
  • 提供教程视频。
  • 支持更多语言文档。
  • 支持更多文本-动作数据集 (例如 FLAG3D、STDM)。欢迎大家贡献自己的数据集！
  • 提供基于UniMoCap的训练模型。

🛠️ 安装

pip install -r requirements.txt

🚀 如何使用？

1. 数据准备

下载SMPL+H和DMPLs模型。

从SMPL+H（选择AMASS项目中使用的Extended SMPL+H模型）下载SMPL+H模型，从DMPL下载DMPL模型（选择与SMPL兼容的DMPLs），从SMPL-X下载SMPL-X模型。然后将所有模型放在./body_model/下。./body_model/文件夹结构应如下：

./body_models
├── dmpls
│   ├── female
│   │   └── model.npz
│   ├── male
│   │   └── model.npz
│   └── neutral
│       └── model.npz
├── smplh
│   ├── female
│   │   └── model.npz
│   ├── info.txt
│   ├── male
│   │   └── model.npz
│   └── neutral
│       └── model.npz
├── smplx
│   ├── female
│   │   ├── model.npz
│   │   └── model.pkl
│   ├── male
│   │   ├── model.npz
│   │   └── model.pkl
│   └── neutral
│       ├── model.npz
└───────└── model.pkl
下载AMASS动作。
  • 下载AMASS动作。
  • 如果您使用SMPL（在HumanML3D、BABEL和KIT-ML中），请将AMASS数据与SMPL-H G下载到./datasets/amass_data/中。
  • 如果您使用SMPL-X（在Motion-X中），请下载带有SMPL-X G的AMASS数据。如果您使用SMPL-X数据，请将其保存在./datasets/amass_data-x/中。

datasets/amass_data/文件夹结构应如下：

./datasets/amass_data/
├── ACCAD
├── BioMotionLab_NTroje
├── BMLhandball
├── BMLmovi
├── CMU
├── DanceDB
├── DFaust_67
├── EKUT
├── Eyes_Japan_Dataset
├── GRAB
├── HUMAN4D
├── HumanEva
├── KIT
├── MPI_HDM05
├── MPI_Limits
├── MPI_mosh
├── SFU
├── SOMA
├── SSM_synced
├── TCD_handMocap
├── TotalCapture
└── Transitions_mocap
HumanML3D数据集

将HumanML3D仓库克隆到datasets/HumanML3D/中，接着将humanact12.zip解压到datasets/pose_data/中，最后解压texts.zip文件。

mkdir datasets
cd datasets
git clone https://github.com/EricGuo5513/HumanML3D/tree/main
mkdir pose_data
unzip HumanML3D/pose_data/humanact12.zip -d pose_data/
mv pose_data/humanact12/humanact12/*.npy pose_data/humanact12/
rm -rf pose_data/humanact12/humanact12
cd HumanML3D/HumanML3D
unzip texts.zip
cd ../../..
KIT-ML数据集

下载KIT-ML动作，并解压缩到文件夹datasets/kit-mocap/中。

BABEL数据集

从TEACH下载BABEL注释到datasets/babel-teach/中。

2. 生成映射文件和文本文件

在这一步中，我们将得到映射文件（.csv）和文本文件（./{dataset}_new_text）。

HumanML3D数据集

由于HumanML3D数据集使用了MIT许可证，我已经预处理了.json（./outputs-json/humanml3d.json）文件和.csv文件（h3d_h3dformat.csv）。此外，.csv文件可以通过以下命令生成。

python h3d_to_h3d.py
BABEL数据集

我们提供了生成统一BABEL注释的代码。生成了.json（./outputs-json/babel{_mode}.json）文件和.csv文件（babel{mode}_h3dformat.csv）。您可以使用以下命令生成相关文件。.json文件只是一个中间生成的文件，不会在后续处理中使用。

对于BABEL，babel_seg和babel_seq分别表示分割级别和整个序列级别的注释。babel表示两个级别的注释。

python babel.py
KIT-ML数据集

我们提供了生成统一KIT-ML注释的代码。生成了.json（./outputs-json/kitml.json）文件和.csv文件（kitml_h3dformat.csv）。您可以使用以下命令生成相关文件。.json文件只是一个中间生成的文件，不会在后续处理中使用。

python kitml.py

3. 提取和处理数据

在这一步中，我们按照HumanML3D中的方法提取动作特征。

现在，您位于./UniMoCap的根目录位置。要生成仅身体的动作特征，请先创建一个文件夹并复制HumanML3D提供的一些工具：

mkdir body-only-unimocap
cp -r ./datasets/HumanML3D/common ./
cp -r ./datasets/HumanML3D/human_body_prior ./
cp -r ./datasets/HumanML3D/paramUtil.py ./

如果您想获得仅身体部分的动作，请参考仅包括身体的数据预处理。

如果您想获得整体的动作，请参考全身动作的数据预处理。

💖 社区贡献开放

我们真诚地希望社区能够支持更多的文本-动作动作数据集。

🌹 致谢

我们的代码基于了TMR、AMASS-Annotation-Unifier和HumanML3D的仓库 ，感谢所有贡献者！

🤝🏼 引用

如果您在研究中使用了这个仓库，您需要引用：

@article{chen2023unimocap,
  title={UniMocap: Unifier for BABEL, HumanML3D, and KIT},
  author={Chen, Ling-Hao and UniMocap, Contributors},
  journal={https://github.com/LinghaoChan/UniMoCap},
  year={2023}
}

由于UniMoCap的某些组件来自AMASS-Annotation-Unifier和HumanML3D，您需要相应地引用它们。

@inproceedings{petrovich23tmr,
    title     = {{TMR}: Text-to-Motion Retrieval Using Contrastive {3D} Human Motion Synthesis},
    author    = {Petrovich, Mathis and Black, Michael J. and Varol, G{\\"u}l},
    booktitle = {International Conference on Computer Vision ({ICCV})},
    year      = {2023}
}
@InProceedings{Guo_2022_CVPR,
    author    = {Guo, Chuan and Zou, Shihao and Zuo, Xinxin and Wang, Sen and Ji, Wei and Li, Xingyu and Cheng, Li},
    title     = {Generating Diverse and Natural 3D Human Motions From Text},
    booktitle = {Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
    month     = {June},
    year      = {2022},
    pages     = {5152-5161}
}

如果您使用了数据集，你还应该引用KIT-ML和AMASS数据集。

@article{Plappert2016,
    author = {Matthias Plappert and Christian Mandery and Tamim Asfour},
    title = {The {KIT} Motion-Language Dataset},
    journal = {Big Data}
    publisher = {Mary Ann Liebert Inc},
    year = {2016},
    month = {dec},
    volume = {4},
    number = {4},
    pages = {236--252}
}
@conference{AMASS2019,
  title = {AMASS: Archive of Motion Capture as Surface Shapes},
  author = {Mahmood, Naureen and Ghorbani, Nima and Troje, Nikolaus F. and Pons-Moll, Gerard and Black, Michael J.},
  booktitle = {International Conference on Computer Vision},
  pages = {5442--5451},
  month = oct,
  year = {2019},
  month_numeric = {10}
}

如果您使用了Motion-X数据集，请相应地引用它。

@article{lin2023motionx,
  title={Motion-X: A Large-scale 3D Expressive Whole-body Human Motion Dataset},
  author={Lin, Jing and Zeng, Ailing and Lu, Shunlin and Cai, Yuanhao and Zhang, Ruimao and Wang, Haoqian and Zhang, Lei},
  journal={Advances in Neural Information Processing Systems},
  year={2023}
}

如果您有任何问题，请联系陈凌灏（thu [DOT] lhchen [AT] gmail [DOT] com）。