HumanML3D：3D人体动作-文本数据集

HumanML3D是一个3D人体动作-文本数据集，由HumanAct12和Amass数据集合并而成。它涵盖了广泛的人体动作，包括日常活动（如“走路”、“跳跃”）、体育运动（如“游泳”、“打高尔夫球”）、杂技动作（如“空翻”）以及艺术性动作（如“跳舞”）。

HumanML3D数据集统计信息

:bar_chart: 统计数据

HumanML3D中的每个动作片段都配有3到4条在Amazon Mechanical Turk平台上标注的单句描述。动作数据被下采样至20帧/秒，每个片段时长为2至10秒。

总体而言，HumanML3D数据集包含14,616个动作片段和44,970条描述，这些描述由5,371个不同的词汇组成。动作总时长达到28.59小时。平均每个动作片段时长为7.1秒，而平均每条描述则包含12个词。

:chart_with_upwards_trend: 数据增强

我们通过镜像所有动作并适当替换描述中的某些关键词（例如，“left”替换为“right”，“clockwise”替换为“counterclockwise”），使HumanML3D数据集规模扩大了一倍。

KIT-ML数据集

KIT动作-文本数据集（KIT-ML）也是一个相关数据集，包含3,911个动作片段和6,278条描述。我们按照与HumanML3D数据集相同的流程处理了KIT-ML数据集，并在此仓库中提供访问。然而，如果您希望使用KIT-ML数据集，请务必引用其原始论文。

如果这个数据集对您的项目有所帮助，我们非常感谢您为本代码库点亮星标。😆😆

查看我们在HumanML3D上的研究成果

:ok_woman: T2M - 首个基于HumanML3D的研究，利用时间变分自编码器学习从文本描述生成3D动作。 :running: TM2T - 通过离散的动作标记学习文本与动作之间的双向映射。 :dancer: TM2D - 根据文本指令生成舞蹈动作。 :honeybee: MoMask - 利用残差量化和生成式掩码建模实现更高水平的文本到动作生成。

如何获取数据

对于KIT-ML数据集，您可以直接从[这里]下载。由于AMASS数据集的分发政策限制，我们无法直接分发该数据。因此，我们提供了一系列脚本，可帮助您从AMASS数据集重新构建我们的HumanML3D数据集。

您需要克隆此仓库并安装虚拟环境。

[2022/12/15] 更新：安装matplotlib=3.3.4可以避免生成的数据与参考数据之间出现微小偏差。详情请参阅问题

Python虚拟环境

conda env create -f environment.yaml
conda activate torch_render

若安装失败，您也可以手动安装以下依赖：

- Python==3.7.10
- Numpy          
- Scipy          
- PyTorch        
- Tqdm 
- Pandas
- Matplotlib==3.3.4     // 仅用于动画
- ffmpeg==4.3.1  // 仅用于动画
- Spacy==2.3.4   // 仅用于文本处理

下载SMPL+H和DMPL模型

请从SMPL+H下载SMPL+H模型（选择AMASS项目中使用的扩展版SMPL+H模型），并从DMPL下载DMPL模型（选择与SMPL兼容的版本）。然后将所有模型放置在“./body_model/”目录下。

数据提取与处理

您需要按顺序运行以下脚本以获得HumanML3D数据集：

1. raw_pose_processing.ipynb
2. motion_representation.ipynb
3. cal_mean_variance.ipynb

这一步是可选的，如果您需要生成动画，可以运行第4步：

4. animation.ipynb

请务必仔细检查每一步，以确保您正朝着正确方向构建HumanML3D数据集。最终，您所需要的全部数据都在“./HumanML3D”文件夹中。

数据结构

<DATA-DIR>
./animations.rar        // 所有动作片段的MP4格式动画。
./new_joint_vecs.rar    // 从3D运动位置中提取的旋转不变特征和旋转特征向量。
./new_joints.rar        // 3D运动位置数据。
./texts.rar             // 动作数据的描述文本。
./Mean.npy              // new_joint_vecs中所有数据的均值。
./Std.npy               // new_joint_vecs中所有数据的标准差。
./all.txt               // 所有数据的文件名列表。
./train.txt             // 训练数据的文件名列表。
./test.txt              // 测试数据的文件名列表。
./train_val.txt         // 训练和验证数据的文件名列表。
./val.txt               // 验证数据的文件名列表。
./all.txt               // 所有数据的文件名列表。

HumanML3D数据遵循具有22个关节的SMPL骨骼结构。KIT-ML则包含21个骨骼关节。详细的运动学链请参考paraUtils。

以“MXXXXXX.*”命名的文件（例如‘M000000.npy’）是对应名称为“XXXXXX.*”的文件（例如‘000000.npy’）的镜像版本。文本文件和动作文件采用相同的命名规则，即“./texts/XXXXXX.txt”（例如‘000000.txt’）中的文本准确描述了“./new_joints（或new_joint_vecs）/XXXXXX.npy”（例如‘000000.npy’）中的人体动作。

每个文本文件的格式如下：

一个男人用左腿踢某物或某人。#a/DET man/NOUN kick/VERB something/PRON or/CCONJ someone/PRON with/ADP his/DET left/ADJ leg/NOUN#0.0#0.0
站立的人先用左脚踢一下，然后回到原来的姿势。#the/DET stand/VERB person/NOUN kick/VERB with/ADP their/DET left/ADJ foot/NOUN before/ADP go/VERB back/ADV to/ADP their/DET original/ADJ stance/NOUN#0.0#0.0
一个男人用左腿踢某物或某人。#a/DET man/NOUN kick/VERB with/ADP something/PRON or/CCONJ someone/PRON with/ADP his/DET left/ADJ leg/NOUN#0.0#0.0
他正在用左腿进行飞踢。#he/PRON is/AUX fly/VERB kick/NOUN with/ADP his/DET left/ADJ leg/NOUN#0.0#0.0

每行都是一个独立的文本注释，由四部分组成：原始描述（小写）、处理后的句子、开始时间(s)、结束时间(s)，各部分之间用“#”分隔。

由于某些动作过于复杂而难以完整描述，我们允许标注者在必要时只对动作的某一部分进行描述。在这种情况下，*开始时间(s)和结束时间(s)*将指明被标注的动作片段。不过，我们观察到这种情况在HumanML3D数据集中所占比例很小。默认情况下，*开始时间(s)和结束时间(s)*会被设置为0，这意味着该文本是对整个动作序列的描述。

如果您无法安装ffmpeg，可以将视频转换为’.gif’格式而非’.mp4’格式来生成动画。然而，生成GIF文件通常需要更长的时间和更多的内存资源。

引用

如果您使用KIT-ML数据集，请考虑引用以下论文：

@article{Plappert2016,
    author = {Matthias Plappert和Christian Mandery和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},
    url = {http://dx.doi.org/10.1089/big.2016.0028},
    doi = {10.1089/big.2016.0028},
}

如果您使用HumanML3D数据集，请考虑引用以下论文：

@InProceedings{Guo_2022_CVPR,
    author    = {Guo, Chuan和Zou, Shihao和Zuo, Xinxin和Wang, Sen和Ji, Wei和Li, Xingyu和Cheng, Li},
    title     = {Generating Diverse and Natural 3D Human Motions From Text},
    booktitle = {IEEE/CVF计算机视觉与模式识别会议（CVPR）论文集},
    month     = {June},
    year      = {2022},
    pages     = {5152-5161}
}

其他

如有任何问题或意见，请联系Guo Chuan，邮箱：cguo2@ualberta.ca。

点赞历史

HumanML3D 快速上手指南

HumanML3D 是一个大规模的 3D 人体动作 - 语言数据集，源自 HumanAct12 和 AMASS 数据集的结合。它涵盖了日常活动、体育运动、杂技和艺术表演等多种人类动作，每个动作片段配有 3-4 句自然语言描述，广泛应用于文本生成 3D 动作（Text-to-Motion）等研究任务。

---

环境准备

系统要求

• 操作系统：Linux / macOS / Windows（推荐 Linux）
• Python 版本：3.7.10
• GPU（可选）：用于加速数据处理或后续模型训练

前置依赖

请确保已安装以下基础工具：

• conda（推荐通过 Miniconda 安装）
• git
• ffmpeg（用于生成动画视频，版本建议 4.3.1）
• spacy 英文模型（用于文本处理）

💡 国内用户可使用清华镜像源加速 conda 和 pip 安装：

conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

---

安装步骤

1. 克隆仓库

git clone https://github.com/EricGuo5513/HumanML3D.git
cd HumanML3D

2. 创建并激活虚拟环境

conda env create -f environment.yaml
conda activate torch_render

若上述命令失败，可手动安装核心依赖：

pip install numpy scipy torch tqdm pandas matplotlib==3.3.4 spacy==2.3.4
python -m spacy download en_core_web_sm

⚠️ 注意：务必使用 matplotlib==3.3.4，否则生成的数据可能与参考数据存在微小偏差。

3. 下载人体模型文件

从以下地址下载模型并放入 ./body_model/ 目录：

• SMPL+H 模型：https://mano.is.tue.mpg.de/download.php
  → 选择 "Extended SMPL+H model used in AMASS project"
• DMPL 模型：https://smpl.is.tue.mpg.de/download.php
  → 选择 "DMPLs compatible with SMPL"

解压后将所有 .pkl 或 .npz 文件移至：

mkdir -p body_model
# 将下载的模型文件移动到此目录

4. 获取 KIT-ML 数据（可选）

KIT-ML 可直接下载： 👉 Google Drive 链接

❗ HumanML3D 主数据因 AMASS 分发政策限制，无法直接提供，需自行从 AMASS 重构。

---

基本使用

步骤一：处理原始姿态数据

依次运行以下 Jupyter Notebook 脚本以构建 HumanML3D 数据集：

jupyter notebook raw_pose_processing.ipynb
jupyter notebook motion_representation.ipynb
jupyter notebook cal_mean_variance.ipynb

✅ 每步完成后请检查输出是否符合预期，确保数据流程正确。

步骤二：生成动画（可选）

如需可视化动作片段，运行：

jupyter notebook animation.ipynb

若未安装 ffmpeg，可修改代码生成 .gif 格式动画（耗时较长）。

步骤三：查看最终数据

处理完成后，核心数据位于 ./HumanML3D/ 目录，结构如下：

./HumanML3D/
├── new_joints.rar          # 3D 关节点坐标 (N, 22, 3)
├── new_joint_vecs.rar      # 提取的特征向量
├── texts.rar               # 文本描述文件
├── Mean.npy / Std.npy      # 特征标准化参数
├── train.txt / test.txt    # 数据划分列表
└── animations.rar          # MP4 动画视频（如果生成）

数据读取示例（Python）

import numpy as np
import os

data_dir = "./HumanML3D"
joint_file = os.path.join(data_dir, "new_joints", "000000.npy")
text_file = os.path.join(data_dir, "texts", "000000.txt")

# 加载 3D 动作数据 (T, 22, 3)
motion = np.load(joint_file)

# 加载文本描述
with open(text_file, 'r', encoding='utf-8') as f:
    lines = f.readlines()
    for line in lines:
        parts = line.strip().split('#')
        description = parts[0]  # 原始描述
        print(f"动作描述: {description}")

📌 文件名规则：XXXXXX.npy 对应原始动作，MXXXXXX.npy 为其镜像版本；文本文件命名一致，内容按 描述#分词结果#起始时间#结束时间 格式存储。

---

完成以上步骤后，您即可基于 HumanML3D 开展文本驱动的动作生成、跨模态检索等研究。更多相关项目可参考官方提供的 T2M、TM2T 等工作。