(CVPR 2023) T2M-GPT

论文“T2M-GPT：基于离散表示从文本描述生成人体运动”的 PyTorch 实现

[项目页面] [论文] [Notebook 演示] [HuggingFace] [Space 演示] [T2M-GPT+]

如果我们的项目对您的研究有所帮助，请考虑引用：

@inproceedings{zhang2023generating,
  title={T2M-GPT: Generating Human Motion from Textual Descriptions with Discrete Representations},
  author={Zhang, Jianrong and Zhang, Yangsong and Cun, Xiaodong and Huang, Shaoli and Zhang, Yong and Zhao, Hongwei and Lu, Hongtao and Shen, Xi},
  booktitle={Proceedings of the IEEE/CVF Conference on Computer Vision and Pattern Recognition (CVPR)},
  year={2023},
}

目录

• 1. 可视化结果
• 2. 安装
• 3. 快速入门
• 4. 训练
• 5. 评估
• 6. SMPL 网格渲染
• 7. 致谢
• 8. 更改记录

1. 可视化结果（更多结果可在我们的项目页面中找到）

文本：一名男子向前迈步并做倒立。
真实标签	T2M	MDM	MotionDiffuse	我们的方法
文本：一名男子从地上起身，绕圈行走，然后重新坐回地上。
真实标签	T2M	MDM	MotionDiffuse	我们的方法

2. 安装

2.1. 环境

我们的模型可以在单块 V100-32G 显卡上进行训练。

conda env create -f environment.yml
conda activate T2M-GPT

代码已在 Python 3.8 和 PyTorch 1.8.1 上测试通过。

2.2. 依赖项

bash dataset/prepare/download_glove.sh

2.3. 数据集

我们使用两个三维人体动作-语言数据集：HumanML3D 和 KIT-ML。对于这两个数据集，您都可以在[这里]找到详细信息及下载链接。

以 HumanML3D 为例，文件目录应如下所示：

./dataset/HumanML3D/
├── new_joint_vecs/
├── texts/
├── Mean.npy # 与 [HumanML3D](https://github.com/EricGuo5513/HumanML3D) 中的相同
├── Std.npy # 与 [HumanML3D](https://github.com/EricGuo5513/HumanML3D) 中的相同
├── train.txt
├── val.txt
├── test.txt
├── train_val.txt
└── all.txt

2.4. 动作和文本特征提取器：

我们使用 t2m 提供的相同提取器来评估我们生成的动作。请下载这些提取器。

bash dataset/prepare/download_extractor.sh

2.5. 预训练模型

预训练模型文件将存储在 'pretrained' 文件夹中：

bash dataset/prepare/download_model.sh

2.6. 渲染 SMPL 网格（可选）

如果您想渲染生成的动作，需要安装：

sudo sh dataset/prepare/download_smpl.sh
conda install -c menpo osmesa
conda install h5py
conda install -c conda-forge shapely pyrender trimesh mapbox_earcut

3. 快速入门

关于如何使用我们代码的快速入门指南可在 demo.ipynb 中找到。

4. 训练

请注意，对于 kit 数据集，只需设置 '--dataname kit'。

4.1. VQ-VAE

结果保存在 output 文件夹中。

python3 train_vq.py \
--batch-size 256 \
--lr 2e-4 \
--total-iter 300000 \
--lr-scheduler 200000 \
--nb-code 512 \
--down-t 2 \
--depth 3 \
--dilation-growth-rate 3 \
--out-dir output \
--dataname t2m \
--vq-act relu \
--quantizer ema_reset \
--loss-vel 0.5 \
--recons-loss l1_smooth \
--exp-name VQVAE

4.2. GPT

结果保存在 output 文件夹中。

python3 train_t2m_trans.py  \
--exp-name GPT \
--batch-size 128 \
--num-layers 9 \
--embed-dim-gpt 1024 \
--nb-code 512 \
--n-head-gpt 16 \
--block-size 51 \
--ff-rate 4 \
--drop-out-rate 0.1 \
--resume-pth output/VQVAE/net_last.pth \
--vq-name VQVAE \
--out-dir output \
--total-iter 300000 \
--lr-scheduler 150000 \
--lr 0.0001 \
--dataname t2m \
--down-t 2 \
--depth 3 \
--quantizer ema_reset \
--eval-iter 10000 \
--pkeep 0.5 \
--dilation-growth-rate 3 \
--vq-act relu

5. 评估

5.1. VQ-VAE

python3 VQ_eval.py \
--batch-size 256 \
--lr 2e-4 \
--total-iter 300000 \
--lr-scheduler 200000 \
--nb-code 512 \
--down-t 2 \
--depth 3 \
--dilation-growth-rate 3 \
--out-dir output \
--dataname t2m \
--vq-act relu \
--quantizer ema_reset \
--loss-vel 0.5 \
--recons-loss l1_smooth \
--exp-name TEST_VQVAE \
--resume-pth output/VQVAE/net_last.pth

5.2. GPT

python3 GPT_eval_multi.py  \
--exp-name TEST_GPT \
--batch-size 128 \
--num-layers 9 \
--embed-dim-gpt 1024 \
--nb-code 512 \
--n-head-gpt 16 \
--block-size 51 \
--ff-rate 4 \
--drop-out-rate 0.1 \
--resume-pth output/VQVAE/net_last.pth \
--vq-name VQVAE \
--out-dir output \
--total-iter 300000 \
--lr-scheduler 150000 \
--lr 0.0001 \
--dataname t2m \
--down-t 2 \
--depth 3 \
--quantizer ema_reset \
--eval-iter 10000 \
--pkeep 0.5 \
--dilation-growth-rate 3 \
--vq-act relu \
--resume-trans output/GPT/net_best_fid.pth

6. SMPL 网格渲染

python3 render_final.py --filedir output/TEST_GPT/ --motion-list 000019 005485

7. 致谢

我们感谢以下人员的帮助：

• 公开代码，如 text-to-motion、TM2T、MDM、MotionDiffuse 等。
• Mathis Petrovich、Yuming Du、Yingyi Chen、Dexiong Chen 和 Xuelin Chen 提供的启发性讨论和宝贵反馈。
• Minh Chien Vu 提供的 Hugging Face Space 演示。

8. 变更日志

• 2023年2月19日：添加了 Hugging Face Space 演示，用于骨骼和 SMPL 网格的可视化展示。

T2M-GPT 快速上手指南

T2M-GPT 是一个基于离散表示，通过文本描述生成人体运动的 AI 模型（CVPR 2023）。本指南将帮助您快速在本地部署并运行该工具。

1. 环境准备

系统要求

• 操作系统: Linux (推荐)
• GPU: 单张 V100-32G 或同等显存容量的 GPU
• Python: 3.8
• PyTorch: 1.8.1

前置依赖

确保已安装 conda 包管理器。本项目依赖 GloVe 词向量、预训练模型及特征提取器。

提示：若下载脚本速度较慢，可手动访问 HumanML3D 数据集页面 或 HuggingFace 下载相关文件后放入对应目录。

2. 安装步骤

2.1 创建虚拟环境

克隆项目代码后，使用提供的配置文件创建 conda 环境：

conda env create -f environment.yml
conda activate T2M-GPT

2.2 下载依赖资源

依次运行以下脚本下载 GloVe 数据、特征提取器和预训练模型：

# 下载 GloVe
bash dataset/prepare/download_glove.sh

# 下载特征提取器 (用于评估)
bash dataset/prepare/download_extractor.sh

# 下载预训练模型
bash dataset/prepare/download_model.sh

2.3 准备数据集

本项目支持 HumanML3D 和 KIT-ML 数据集。以 HumanML3D 为例，请下载数据集并确保目录结构如下：

./dataset/HumanML3D/
├── new_joint_vecs/
├── texts/
├── Mean.npy
├── Std.npy
├── train.txt
├── val.txt
├── test.txt
├── train_val.txt
└── all.txt

(可选) 若需渲染 SMPL 网格动画，请额外安装渲染依赖：

sudo sh dataset/prepare/download_smpl.sh
conda install -c menpo osmesa
conda install h5py
conda install -c conda-forge shapely pyrender trimesh mapbox_earcut

3. 基本使用

最快速的上手方式是使用官方提供的 Colab Notebook 进行体验，无需本地配置环境：

• Notebook Demo: Google Colab 链接
• HuggingFace Space: 在线演示空间

本地推理示例

若已完成安装并下载了预训练模型，可通过修改评估脚本来生成运动数据。以下命令展示了如何加载预训练的 GPT 模型进行生成（结果保存在 output 目录）：

python3 GPT_eval_multi.py  \
--exp-name TEST_GPT \
--batch-size 128 \
--num-layers 9 \
--embed-dim-gpt 1024 \
--nb-code 512 \
--n-head-gpt 16 \
--block-size 51 \
--ff-rate 4 \
--drop-out-rate 0.1 \
--resume-pth output/VQVAE/net_last.pth \
--vq-name VQVAE \
--out-dir output \
--total-iter 300000 \
--lr-scheduler 150000 \
--lr 0.0001 \
--dataname t2m \
--down-t 2 \
--depth 3 \
--quantizer ema_reset \
--eval-iter 10000 \
--pkeep 0.5 \
--dilation-growth-rate 3 \
--vq-act relu \
--resume-trans output/GPT/net_best_fid.pth

渲染结果 (可选)

生成 .npy 格式的运动数据后，可使用以下命令将其渲染为可视化的 SMPL 网格动画：

python3 render_final.py --filedir output/TEST_GPT/ --motion-list 000019 005485