MotionBERT：学习人体运动表示的统一视角

这是论文 "MotionBERT: A Unified Perspective on Learning Human Motion Representations"（ICCV 2023）的官方 PyTorch 实现。

安装

conda create -n motionbert python=3.7 anaconda
conda activate motionbert
# 请根据您的 CUDA 版本安装 PyTorch。
conda install pytorch torchvision torchaudio pytorch-cuda=11.6 -c pytorch -c nvidia
pip install -r requirements.txt

快速入门

任务	文档
预训练	docs/pretrain.md
3D人体姿态估计	docs/pose3d.md
基于骨架的动作识别	docs/action.md
网格重建	docs/mesh.md

应用

野外推理（针对自定义视频）

请参考 docs/inference.md。

使用 MotionBERT 进行 以人为中心 的视频表示

'''	    
  x: 2D 骨架 
    type = <class 'torch.Tensor'>
    shape = [batch size * 帧数 * 关节点(17) * 通道数(3)]
    
  MotionBERT：预训练的人体运动编码器
    type = <class 'lib.model.DSTformer.DSTformer'>
    
  E: 编码后的运动表示
    type = <class 'torch.Tensor'>
    shape = [batch size * 帧数 * 关节点(17) * 通道数(512)]
'''
E = MotionBERT.get_representation(x)

提示

1. 该模型可以处理不同长度的输入（不超过243帧）。无需在其他地方显式指定输入长度。
2. 模型使用17个身体关键点（H36M 格式）。如果您使用其他格式，请在输入 MotionBERT 之前进行转换。
3. 请参阅 model_action.py 和 model_mesh.py 中的例子，了解如何轻松地将 MotionBERT 适配到不同的下游任务。
4. 对于 RGB 视频，您需要先提取 2D 姿态（inference.md），再转换关键点格式（dataset_wild.py），最后输入 MotionBERT（infer_wild.py）。

模型库

模型	下载链接	配置	性能
MotionBERT (162MB)	OneDrive	pretrain/MB_pretrain.yaml	-
MotionBERT-Lite (61MB)	OneDrive	pretrain/MB_lite.yaml	-
3D姿态（H36M-SH，从零开始）	OneDrive	pose3d/MB_train_h36m.yaml	39.2mm (MPJPE)
3D姿态（H36M-SH，微调）	OneDrive	pose3d/MB_ft_h36m.yaml	37.2mm (MPJPE)
动作识别（x-sub，微调）	OneDrive	action/MB_ft_NTU60_xsub.yaml	97.2% (Top1 Acc)
动作识别（x-view，微调）	OneDrive	action/MB_ft_NTU60_xview.yaml	93.0% (Top1 Acc)
网格（结合3DPW，微调）	OneDrive	mesh/MB_ft_pw3d.yaml	88.1mm (MPVE)

在大多数应用场景中（尤其是微调时），MotionBERT-Lite 能够以更低的计算开销提供相近的性能。

待办事项

• 预训练脚本和文档

• 自定义视频演示

引用

如果您觉得我们的工作对您的项目有帮助，请考虑引用该论文：

@inproceedings{motionbert2022,
  title     =   {MotionBERT: A Unified Perspective on Learning Human Motion Representations}, 
  author    =   {Zhu, Wentao and Ma, Xiaoxuan and Liu, Zhaoyang and Liu, Libin and Wu, Wayne and Wang, Yizhou},
  booktitle =   {Proceedings of the IEEE/CVF International Conference on Computer Vision},
  year      =   {2023},
}

MotionBERT 快速上手指南

MotionBERT 是一个用于学习人体运动表示的统一预训练模型，支持 3D 人体姿态估计、基于骨架的动作识别和网格恢复等任务。

环境准备

• 操作系统: Linux / macOS / Windows (WSL)
• Python: 3.7
• 深度学习框架: PyTorch (需根据本地 CUDA 版本选择)
• 硬件要求: 推荐具备 NVIDIA GPU 以加速推理和训练

安装步骤

1. 创建并激活 Conda 环境

   conda create -n motionbert python=3.7 anaconda
   conda activate motionbert
   

2. 安装 PyTorch 请根据您的 CUDA 版本选择合适的安装命令（以下为 CUDA 11.6 示例）：

   conda install pytorch torchvision torchaudio pytorch-cuda=11.6 -c pytorch -c nvidia
   

   提示: 国内用户可使用清华或中科大镜像源加速安装，例如： conda install pytorch torchvision torchaudio pytorch-cuda=11.6 -c pytorch -c nvidia --channel https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/

3. 安装项目依赖

   pip install -r requirements.txt
   

   提示: 建议使用国内 pip 镜像源： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

4. 下载预训练模型 从 Model Zoo 部分提供的 OneDrive 链接下载所需的 .pth 模型文件，并放置于项目指定目录（通常为 checkpoint 或 pretrained，具体参考各任务文档）。

基本使用

以下示例展示如何加载预训练的 MotionBERT 模型，并将 2D 骨架序列编码为运动特征表示。

代码示例

import torch
from lib.model.DSTformer import DSTformer

# 1. 初始化模型 (假设已加载预训练权重)
# 实际使用时请根据文档加载具体的 checkpoint
MotionBERT = DSTformer() 
MotionBERT.eval()

# 2. 准备输入数据 (2D 骨架)
# 形状: [Batch Size, Frames, Joints(17), Channels(3)]
# 注意：关键点格式需为 H36M 格式 (17 个关节点)
batch_size = 1
frames = 243
x = torch.randn(batch_size, frames, 17, 3)

# 3. 获取运动特征表示
# 输出形状: [Batch Size, Frames, Joints(17), Channels(512)]
with torch.no_grad():
    E = MotionBERT.get_representation(x)

print(f"输入形状：{x.shape}")
print(f"输出特征形状：{E.shape}")

关键注意事项

• 输入长度: 模型支持动态输入长度，但最大不超过 243 帧，无需额外配置。
• 数据格式: 输入必须是 17 个关键点 的 2D 坐标（H36M 格式）。如果使用其他数据集格式（如 COCO），请先转换为 H36M 格式。
• RGB 视频处理: 如果输入是原始视频，需先提取 2D 姿态（参考 docs/inference.md），转换关键点格式后，再传入模型。

更多任务文档

针对不同下游任务，请参考官方详细文档：

• 预训练: docs/pretrain.md
• 3D 人体姿态估计: docs/pose3d.md
• 动作识别: docs/action.md
• 网格恢复: docs/mesh.md
• 自定义视频推理: docs/inference.md