Manopth

适用于 PyTorch 的 MANO 层（已在 v0.4 和 v1.x 上测试）

ManoLayer 是一个可微分的 PyTorch 层，它以确定性的方式将姿态和形状参数映射到手部关节和顶点。它可以作为可微分层集成到任何架构中，用于预测手部网格。

ManoLayer 接受批量的手部姿态和形状向量，并输出对应的手部关节和顶点。

该代码主要是将原始 MANO 模型从 chumpy 移植到 PyTorch 的实现。因此，它直接建立在 Javier Romero、Dimitrios Tzionas 和 Michael J. Black 的工作基础上。

该层是为 CVPR19 论文 学习手与被操纵物体的联合重建 开发并使用的。请参阅 项目页面 和 演示及训练代码。

它复用了 MandyMo 的 Zhang Xiong 编写的 PyTorch SMPL 身体模型层中的优秀代码的一部分，用于计算旋转相关工具！

此外，mano/webuser 目录下还包含了原始 MANO 代码的部分文件内容（posemapper.py、serialization.py、lbs.py、verts.py、smpl_handpca_wrapper_HAND_only.py）。

如果您觉得此代码对您的研究有帮助，请考虑引用以下文献：

• 原始 MANO 出版物：

@article{MANO:SIGGRAPHASIA:2017,
  title = {Embodied Hands: Modeling and Capturing Hands and Bodies Together},
  author = {Romero, Javier and Tzionas, Dimitrios and Black, Michael J.},
  journal = {ACM Transactions on Graphics, (Proc. SIGGRAPH Asia)},
  publisher = {ACM},
  month = nov,
  year = {2017},
  url = {http://doi.acm.org/10.1145/3130800.3130883},
  month_numeric = {11}
}

• 本 PyTorch 移植所基于的论文：

@INPROCEEDINGS{hasson19_obman,
  title     = {Learning joint reconstruction of hands and manipulated objects},
  author    = {Hasson, Yana and Varol, G{\"u}l and Tzionas, Dimitris and Kalevatykh, Igor and Black, Michael J. and Laptev, Ivan and Schmid, Cordelia},
  booktitle = {CVPR},
  year      = {2019}
}

与该论文相关的、兼容 manopth 的训练代码可在 这里找到。该发布包含一个在多种手部数据集上训练的模型。

安装

获取代码和依赖项

• git clone https://github.com/hassony2/manopth
• cd manopth
• 安装 environment.yml 中列出的依赖项：
  • 在现有 conda 环境中，运行 conda env update -f environment.yml
  • 在新环境中，运行 conda env create -f environment.yml 将创建名为 manopth 的 conda 环境

下载 MANO pickle 数据结构

• 访问 MANO 官网
• 点击 Sign Up 创建账户并提供信息
• 下载 Models and Code（下载的文件应为 mano_v*_*.zip 格式）。请注意，此次下载的所有代码和数据均受 MANO 许可协议约束。
• 解压并将 models 文件夹复制到 manopth/mano 文件夹中
• 您的文件夹结构应如下所示：

manopth/
  mano/
    models/
      MANO_LEFT.pkl
      MANO_RIGHT.pkl
      ...
  manopth/
    __init__.py
    ...

为检查是否安装成功，可运行 python examples/manopth_mindemo.py，该脚本将使用 MANO 层生成一个随机手部模型！

安装 manopth 包

要能够在其他项目中导入并使用 ManoLayer，请进入您的 manopth 文件夹并运行 pip install .

cd /path/to/other/project

现在您可以在该项目中使用 from manopth import ManoLayer！

使用方法

最小化使用示例

请参阅 examples/manopth_mindemo.py

通过 MANO 层进行简单的前向传播，使用随机的姿态和形状参数

import torch
from manopth.manolayer import ManoLayer
from manopth import demo

batch_size = 10
# 选择姿态空间的主成分数量
ncomps = 6

# 初始化 MANO 层
mano_layer = ManoLayer(mano_root='mano/models', use_pca=True, ncomps=ncomps)

# 生成随机形状参数
random_shape = torch.rand(batch_size, 10)
# 生成随机姿态参数，包括 3 个全局轴角旋转值
random_pose = torch.rand(batch_size, ncomps + 3)

# 通过 MANO 层进行前向传播
hand_verts, hand_joints = mano_layer(random_pose, random_shape)
demo.display_hand({'verts': hand_verts, 'joints': hand_joints}, mano_faces=mano_layer.th_faces)

结果：

演示

更多选项、前向和反向传播以及快速性能分析循环，请查看 examples/manopth_demo.py。

您可以在本地运行：

python examples/manopth_demo.py

Manopth 快速上手指南

Manopth 是 MANO 手部模型的 PyTorch 可微分层实现。它能够将手部的姿态（pose）和形状（shape）参数确定性地映射为手部关节点和顶点网格，适用于手部重建、抓取分析等深度学习任务。

环境准备

• 系统要求：Linux 或 macOS（Windows 需自行配置编译环境）。
• 核心依赖：
  • Python 3.x
  • PyTorch (测试版本 v0.4 及 v1.x+)
  • Conda (推荐用于管理依赖)
• 前置数据：需要手动下载官方的 MANO 模型数据（.pkl 文件）。

安装步骤

1. 获取代码与安装依赖

克隆仓库并使用 Conda 创建环境：

git clone https://github.com/hassony2/manopth
cd manopth

# 方式一：在现有环境中更新依赖
conda env update -f environment.yml

# 方式二：创建名为 'manopth' 的新环境
conda env create -f environment.yml
conda activate manopth

提示：如果 environment.yml 中的源下载缓慢，可手动编辑该文件，将 pip 或 conda 源替换为国内镜像（如清华源或阿里源），或直接使用 pip install -r requirements.txt 配合 -i https://pypi.tuna.tsinghua.edu.cn/simple 安装。

2. 下载 MANO 模型数据

由于版权限制，模型数据需手动下载：

1. 访问 MANO 官网 并注册账号。
2. 下载 Models and Code (文件格式为 mano_v*_*.zip)。
3. 解压文件，将其中的 models 文件夹复制到项目目录下的 manopth/mano/ 路径中。

最终目录结构应如下所示：

manopth/
  mano/
    models/
      MANO_LEFT.pkl
      MANO_RIGHT.pkl
      ...
  manopth/
    __init__.py
    ...

3. 安装 Python 包

为了方便在其他项目中导入，执行以下命令进行本地安装：

pip install .

4. 验证安装

运行官方提供的最小化示例脚本，若能生成随机手部网格则代表安装成功：

python examples/manopth_mindemo.py

基本使用

以下是最简化的使用示例，展示如何初始化层并进行前向传播：

import torch
from manopth.manolayer import ManoLayer
from manopth import demo

batch_size = 10
# 选择姿态空间的主成分数量 (PCA)
ncomps = 6

# 初始化 MANO 层
# mano_root 指向包含 models 文件夹的父目录
mano_layer = ManoLayer(mano_root='mano/models', use_pca=True, ncomps=ncomps)

# 生成随机形状参数 (batch_size, 10)
random_shape = torch.rand(batch_size, 10)

# 生成随机姿态参数 (batch_size, ncomps + 3)
# 包含 3 个全局旋转轴角值 + ncomps 个 PCA 系数
random_pose = torch.rand(batch_size, ncomps + 3)

# 前向传播：输入姿态和形状，输出顶点和关节点
hand_verts, hand_joints = mano_layer(random_pose, random_shape)

# 可视化结果 (可选，需安装 matplotlib 等绘图库)
demo.display_hand({'verts': hand_verts, 'joints': hand_joints}, mano_faces=mano_layer.th_faces)

说明：

• hand_verts: 输出的手部网格顶点坐标。
• hand_joints: 输出的手部关节点坐标。
• 该层完全可微，可直接嵌入神经网络中进行端到端训练。