## SMPL-X: A new joint 3D model of the human body, face and hands together
[[Paper Page](https://smpl-x.is.tue.mpg.de)] [[Paper](https://ps.is.tuebingen.mpg.de/uploads_file/attachment/attachment/497/SMPL-X.pdf)]
[[Supp. Mat.](https://ps.is.tuebingen.mpg.de/uploads_file/attachment/attachment/498/SMPL-X-supp.pdf)]
## Table of Contents
* [License](#license)
* [Description](#description)
* [News](#news)
* [Installation](#installation)
* [Downloading the model](#downloading-the-model)
* [Loading SMPL-X, SMPL+H and SMPL](#loading-smpl-x-smplh-and-smpl)
* [SMPL and SMPL+H setup](#smpl-and-smplh-setup)
* [Model loading](https://github.com/vchoutas/smplx#model-loading)
* [MANO and FLAME correspondences](#mano-and-flame-correspondences)
* [Example](#example)
* [Modifying the global pose of the model](#modifying-the-global-pose-of-the-model)
* [Citation](#citation)
* [Acknowledgments](#acknowledgments)
* [Contact](#contact)
## License
Software Copyright License for **non-commercial scientific research purposes**.
Please read carefully the [terms and conditions](https://github.com/vchoutas/smplx/blob/master/LICENSE) and any accompanying documentation before you download and/or use the SMPL-X/SMPLify-X model, data and software, (the "Model & Software"), including 3D meshes, blend weights, blend shapes, textures, software, scripts, and animations. By downloading and/or using the Model & Software (including downloading, cloning, installing, and any other use of this github repository), you acknowledge that you have read these terms and conditions, understand them, and agree to be bound by them. If you do not agree with these terms and conditions, you must not download and/or use the Model & Software. Any infringement of the terms of this agreement will automatically terminate your rights under this [License](./LICENSE).
## Disclaimer
The original images used for the figures 1 and 2 of the paper can be found in this link.
The images in the paper are used under license from gettyimages.com.
We have acquired the right to use them in the publication, but redistribution is not allowed.
Please follow the instructions on the given link to acquire right of usage.
Our results are obtained on the 483 × 724 pixels resolution of the original images.
## Description
*SMPL-X* (SMPL eXpressive) is a unified body model with shape parameters trained jointly for the
face, hands and body. *SMPL-X* uses standard vertex based linear blend skinning with learned corrective blend
shapes, has N = 10, 475 vertices and K = 54 joints,
which include joints for the neck, jaw, eyeballs and fingers.
SMPL-X is defined by a function M(θ, β, ψ), where θ is the pose parameters, β the shape parameters and
ψ the facial expression parameters.
## News
- 3 November 2020: We release the code to transfer between the models in the
SMPL family. For more details on the code, go to this [readme
file](./transfer_model/README.md). A detailed explanation on how the mappings
were extracted can be found [here](./transfer_model/docs/transfer.md).
- 23 September 2020: A UV map is now available for SMPL-X, please check the
Downloads section of the website.
- 20 August 2020: The full shape and expression space of SMPL-X are now available.
## Installation
To install the model please follow the next steps in the specified order:
1. To install from PyPi simply run:
```Shell
pip install smplx[all]
```
2. Clone this repository and install it using the *setup.py* script:
```Shell
git clone https://github.com/vchoutas/smplx
python setup.py install
```
## Downloading the model
To download the *SMPL-X* model go to [this project website](https://smpl-x.is.tue.mpg.de) and register to get access to the downloads section.
To download the *SMPL+H* model go to [this project website](http://mano.is.tue.mpg.de) and register to get access to the downloads section.
To download the *SMPL* model go to [this](http://smpl.is.tue.mpg.de) (male and female models) and [this](http://smplify.is.tue.mpg.de) (gender neutral model) project website and register to get access to the downloads section.
## Loading SMPL-X, SMPL+H and SMPL
### SMPL and SMPL+H setup
The loader gives the option to use any of the SMPL-X, SMPL+H, SMPL, and MANO models. Depending on the model you want to use, please follow the respective download instructions. To switch between MANO, SMPL, SMPL+H and SMPL-X just change the *model_path* or *model_type* parameters. For more details please check the docs of the model classes.
Before using SMPL and SMPL+H you should follow the instructions in [tools/README.md](./tools/README.md) to remove the
Chumpy objects from both model pkls, as well as merge the MANO parameters with SMPL+H.
### Model loading
You can either use the [create](https://github.com/vchoutas/smplx/blob/c63c02b478c5c6f696491ed9167e3af6b08d89b1/smplx/body_models.py#L54)
function from [body_models](./smplx/body_models.py) or directly call the constructor for the
[SMPL](https://github.com/vchoutas/smplx/blob/c63c02b478c5c6f696491ed9167e3af6b08d89b1/smplx/body_models.py#L106),
[SMPL+H](https://github.com/vchoutas/smplx/blob/c63c02b478c5c6f696491ed9167e3af6b08d89b1/smplx/body_models.py#L395) and
[SMPL-X](https://github.com/vchoutas/smplx/blob/c63c02b478c5c6f696491ed9167e3af6b08d89b1/smplx/body_models.py#L628) model. The path to the model can either be the path to the file with the parameters or a directory with the following structure:
```bash
models
├── smpl
│ ├── SMPL_FEMALE.pkl
│ └── SMPL_MALE.pkl
│ └── SMPL_NEUTRAL.pkl
├── smplh
│ ├── SMPLH_FEMALE.pkl
│ └── SMPLH_MALE.pkl
├── mano
| ├── MANO_RIGHT.pkl
| └── MANO_LEFT.pkl
└── smplx
├── SMPLX_FEMALE.npz
├── SMPLX_FEMALE.pkl
├── SMPLX_MALE.npz
├── SMPLX_MALE.pkl
├── SMPLX_NEUTRAL.npz
└── SMPLX_NEUTRAL.pkl
```
## MANO and FLAME correspondences
The vertex correspondences between SMPL-X and MANO, FLAME can be downloaded
from [the project website](https://smpl-x.is.tue.mpg.de). If you have extracted
the correspondence data in the folder *correspondences*, then use the following
scripts to visualize them:
1. To view MANO correspondences run the following command:
```
python examples/vis_mano_vertices.py --model-folder $SMPLX_FOLDER --corr-fname correspondences/MANO_SMPLX_vertex_ids.pkl
```
2. To view FLAME correspondences run the following command:
```
python examples/vis_flame_vertices.py --model-folder $SMPLX_FOLDER --corr-fname correspondences/SMPL-X__FLAME_vertex_ids.npy
```
## Example
After installing the *smplx* package and downloading the model parameters you should be able to run the *demo.py*
script to visualize the results. For this step you have to install the [pyrender](https://pyrender.readthedocs.io/en/latest/index.html) and [trimesh](https://trimsh.org/) packages.
`python examples/demo.py --model-folder $SMPLX_FOLDER --plot-joints=True --gender="neutral"`
## Modifying the global pose of the model
If you want to modify the global pose of the model, i.e. the root rotation and
translation, to a new coordinate system for example, you need to take into
account that the model rotation uses the pelvis as the center of rotation. A
more detailed description can be found in the following
[link](https://www.dropbox.com/scl/fi/zkatuv5shs8d4tlwr8ecc/Change-parameters-to-new-coordinate-system.paper?dl=0&rlkey=lotq1sh6wzkmyttisc05h0in0).
If something is not clear, please let me know so that I can update the
description.
## Citation
Depending on which model is loaded for your project, i.e. SMPL-X or SMPL+H or SMPL, please cite the most relevant work below, listed in the same order:
```
@inproceedings{SMPL-X:2019,
title = {Expressive Body Capture: 3D Hands, Face, and Body from a Single Image},
author = {Pavlakos, Georgios and Choutas, Vasileios and Ghorbani, Nima and Bolkart, Timo and Osman, Ahmed A. A. and Tzionas, Dimitrios and Black, Michael J.},
booktitle = {Proceedings IEEE Conf. on Computer Vision and Pattern Recognition (CVPR)},
year = {2019}
}
```
```
@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)},
volume = {36},
number = {6},
series = {245:1--245:17},
month = nov,
year = {2017},
month_numeric = {11}
}
```
```
@article{SMPL:2015,
author = {Loper, Matthew and Mahmood, Naureen and Romero, Javier and Pons-Moll, Gerard and Black, Michael J.},
title = {{SMPL}: A Skinned Multi-Person Linear Model},
journal = {ACM Transactions on Graphics, (Proc. SIGGRAPH Asia)},
month = oct,
number = {6},
pages = {248:1--248:16},
publisher = {ACM},
volume = {34},
year = {2015}
}
```
This repository was originally developed for SMPL-X / SMPLify-X (CVPR 2019), you might be interested in having a look: [https://smpl-x.is.tue.mpg.de](https://smpl-x.is.tue.mpg.de).
## Acknowledgments
### Facial Contour
Special thanks to [Soubhik Sanyal](https://github.com/soubhiksanyal) for sharing the Tensorflow code used for the facial
landmarks.
## Contact
The code of this repository was implemented by [Vassilis Choutas](vassilis.choutas@tuebingen.mpg.de).
For questions, please contact [smplx@tue.mpg.de](smplx@tue.mpg.de).
For commercial licensing (and all related questions for business applications), please contact [ps-licensing@tue.mpg.de](ps-licensing@tue.mpg.de).
Raw data
{
"_id": null,
"home_page": "http://smpl-x.is.tuebingen.mpg.de",
"name": "smplx",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6.0",
"maintainer_email": "",
"keywords": "",
"author": "Vassilis Choutas",
"author_email": "vassilis.choutas@tuebingen.mpg.de",
"download_url": "https://files.pythonhosted.org/packages/69/eb/51da17b291fb1221317a1ff65a301fb2cf9c6c0dd87a0caec4cbcd06c1da/smplx-0.1.28.tar.gz",
"platform": "",
"description": "\n## SMPL-X: A new joint 3D model of the human body, face and hands together\n\n[[Paper Page](https://smpl-x.is.tue.mpg.de)] [[Paper](https://ps.is.tuebingen.mpg.de/uploads_file/attachment/attachment/497/SMPL-X.pdf)]\n[[Supp. Mat.](https://ps.is.tuebingen.mpg.de/uploads_file/attachment/attachment/498/SMPL-X-supp.pdf)]\n\n\n\n## Table of Contents\n * [License](#license)\n * [Description](#description)\n * [News](#news)\n * [Installation](#installation)\n * [Downloading the model](#downloading-the-model)\n * [Loading SMPL-X, SMPL+H and SMPL](#loading-smpl-x-smplh-and-smpl) \n * [SMPL and SMPL+H setup](#smpl-and-smplh-setup)\n * [Model loading](https://github.com/vchoutas/smplx#model-loading)\n * [MANO and FLAME correspondences](#mano-and-flame-correspondences) \n * [Example](#example)\n * [Modifying the global pose of the model](#modifying-the-global-pose-of-the-model)\n * [Citation](#citation)\n * [Acknowledgments](#acknowledgments)\n * [Contact](#contact)\n\n## License\n\nSoftware Copyright License for **non-commercial scientific research purposes**.\nPlease read carefully the [terms and conditions](https://github.com/vchoutas/smplx/blob/master/LICENSE) and any accompanying documentation before you download and/or use the SMPL-X/SMPLify-X model, data and software, (the \"Model & Software\"), including 3D meshes, blend weights, blend shapes, textures, software, scripts, and animations. By downloading and/or using the Model & Software (including downloading, cloning, installing, and any other use of this github repository), you acknowledge that you have read these terms and conditions, understand them, and agree to be bound by them. If you do not agree with these terms and conditions, you must not download and/or use the Model & Software. Any infringement of the terms of this agreement will automatically terminate your rights under this [License](./LICENSE).\n\n## Disclaimer\n\nThe original images used for the figures 1 and 2 of the paper can be found in this link. \nThe images in the paper are used under license from gettyimages.com.\nWe have acquired the right to use them in the publication, but redistribution is not allowed.\nPlease follow the instructions on the given link to acquire right of usage.\nOur results are obtained on the 483 \u00d7 724 pixels resolution of the original images.\n\n## Description\n\n*SMPL-X* (SMPL eXpressive) is a unified body model with shape parameters trained jointly for the\nface, hands and body. *SMPL-X* uses standard vertex based linear blend skinning with learned corrective blend\nshapes, has N = 10, 475 vertices and K = 54 joints,\nwhich include joints for the neck, jaw, eyeballs and fingers. \nSMPL-X is defined by a function M(\u03b8, \u03b2, \u03c8), where \u03b8 is the pose parameters, \u03b2 the shape parameters and\n\u03c8 the facial expression parameters.\n\n## News\n\n- 3 November 2020: We release the code to transfer between the models in the\n SMPL family. For more details on the code, go to this [readme\n file](./transfer_model/README.md). A detailed explanation on how the mappings\n were extracted can be found [here](./transfer_model/docs/transfer.md).\n- 23 September 2020: A UV map is now available for SMPL-X, please check the\n Downloads section of the website.\n- 20 August 2020: The full shape and expression space of SMPL-X are now available.\n\n## Installation\n\nTo install the model please follow the next steps in the specified order:\n1. To install from PyPi simply run: \n ```Shell\n pip install smplx[all]\n ```\n2. Clone this repository and install it using the *setup.py* script: \n```Shell\ngit clone https://github.com/vchoutas/smplx\npython setup.py install\n```\n\n## Downloading the model\n\nTo download the *SMPL-X* model go to [this project website](https://smpl-x.is.tue.mpg.de) and register to get access to the downloads section. \n\nTo download the *SMPL+H* model go to [this project website](http://mano.is.tue.mpg.de) and register to get access to the downloads section. \n\nTo download the *SMPL* model go to [this](http://smpl.is.tue.mpg.de) (male and female models) and [this](http://smplify.is.tue.mpg.de) (gender neutral model) project website and register to get access to the downloads section. \n\n## Loading SMPL-X, SMPL+H and SMPL\n\n### SMPL and SMPL+H setup\n\nThe loader gives the option to use any of the SMPL-X, SMPL+H, SMPL, and MANO models. Depending on the model you want to use, please follow the respective download instructions. To switch between MANO, SMPL, SMPL+H and SMPL-X just change the *model_path* or *model_type* parameters. For more details please check the docs of the model classes.\nBefore using SMPL and SMPL+H you should follow the instructions in [tools/README.md](./tools/README.md) to remove the\nChumpy objects from both model pkls, as well as merge the MANO parameters with SMPL+H.\n\n### Model loading \n\nYou can either use the [create](https://github.com/vchoutas/smplx/blob/c63c02b478c5c6f696491ed9167e3af6b08d89b1/smplx/body_models.py#L54)\nfunction from [body_models](./smplx/body_models.py) or directly call the constructor for the \n[SMPL](https://github.com/vchoutas/smplx/blob/c63c02b478c5c6f696491ed9167e3af6b08d89b1/smplx/body_models.py#L106), \n[SMPL+H](https://github.com/vchoutas/smplx/blob/c63c02b478c5c6f696491ed9167e3af6b08d89b1/smplx/body_models.py#L395) and \n[SMPL-X](https://github.com/vchoutas/smplx/blob/c63c02b478c5c6f696491ed9167e3af6b08d89b1/smplx/body_models.py#L628) model. The path to the model can either be the path to the file with the parameters or a directory with the following structure:\n```bash\nmodels\n\u251c\u2500\u2500 smpl\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 SMPL_FEMALE.pkl\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 SMPL_MALE.pkl\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 SMPL_NEUTRAL.pkl\n\u251c\u2500\u2500 smplh\n\u2502\u00a0\u00a0 \u251c\u2500\u2500 SMPLH_FEMALE.pkl\n\u2502\u00a0\u00a0 \u2514\u2500\u2500 SMPLH_MALE.pkl\n\u251c\u2500\u2500 mano\n| \u251c\u2500\u2500 MANO_RIGHT.pkl\n| \u2514\u2500\u2500 MANO_LEFT.pkl\n\u2514\u2500\u2500 smplx\n \u251c\u2500\u2500 SMPLX_FEMALE.npz\n \u251c\u2500\u2500 SMPLX_FEMALE.pkl\n \u251c\u2500\u2500 SMPLX_MALE.npz\n \u251c\u2500\u2500 SMPLX_MALE.pkl\n \u251c\u2500\u2500 SMPLX_NEUTRAL.npz\n \u2514\u2500\u2500 SMPLX_NEUTRAL.pkl\n```\n\n\n## MANO and FLAME correspondences\n\nThe vertex correspondences between SMPL-X and MANO, FLAME can be downloaded\nfrom [the project website](https://smpl-x.is.tue.mpg.de). If you have extracted\nthe correspondence data in the folder *correspondences*, then use the following\nscripts to visualize them:\n\n1. To view MANO correspondences run the following command:\n\n```\npython examples/vis_mano_vertices.py --model-folder $SMPLX_FOLDER --corr-fname correspondences/MANO_SMPLX_vertex_ids.pkl\n```\n\n2. To view FLAME correspondences run the following command:\n\n```\npython examples/vis_flame_vertices.py --model-folder $SMPLX_FOLDER --corr-fname correspondences/SMPL-X__FLAME_vertex_ids.npy\n```\n\n## Example\n\nAfter installing the *smplx* package and downloading the model parameters you should be able to run the *demo.py*\nscript to visualize the results. For this step you have to install the [pyrender](https://pyrender.readthedocs.io/en/latest/index.html) and [trimesh](https://trimsh.org/) packages.\n\n`python examples/demo.py --model-folder $SMPLX_FOLDER --plot-joints=True --gender=\"neutral\"`\n\n\n\n## Modifying the global pose of the model\n\nIf you want to modify the global pose of the model, i.e. the root rotation and\ntranslation, to a new coordinate system for example, you need to take into\naccount that the model rotation uses the pelvis as the center of rotation. A\nmore detailed description can be found in the following\n[link](https://www.dropbox.com/scl/fi/zkatuv5shs8d4tlwr8ecc/Change-parameters-to-new-coordinate-system.paper?dl=0&rlkey=lotq1sh6wzkmyttisc05h0in0).\nIf something is not clear, please let me know so that I can update the\ndescription.\n\n## Citation\n\nDepending on which model is loaded for your project, i.e. SMPL-X or SMPL+H or SMPL, please cite the most relevant work below, listed in the same order:\n\n```\n@inproceedings{SMPL-X:2019,\n title = {Expressive Body Capture: 3D Hands, Face, and Body from a Single Image},\n author = {Pavlakos, Georgios and Choutas, Vasileios and Ghorbani, Nima and Bolkart, Timo and Osman, Ahmed A. A. and Tzionas, Dimitrios and Black, Michael J.},\n booktitle = {Proceedings IEEE Conf. on Computer Vision and Pattern Recognition (CVPR)},\n year = {2019}\n}\n```\n\n```\n@article{MANO:SIGGRAPHASIA:2017,\n title = {Embodied Hands: Modeling and Capturing Hands and Bodies Together},\n author = {Romero, Javier and Tzionas, Dimitrios and Black, Michael J.},\n journal = {ACM Transactions on Graphics, (Proc. SIGGRAPH Asia)},\n volume = {36},\n number = {6},\n series = {245:1--245:17},\n month = nov,\n year = {2017},\n month_numeric = {11}\n }\n```\n\n```\n@article{SMPL:2015,\n author = {Loper, Matthew and Mahmood, Naureen and Romero, Javier and Pons-Moll, Gerard and Black, Michael J.},\n title = {{SMPL}: A Skinned Multi-Person Linear Model},\n journal = {ACM Transactions on Graphics, (Proc. SIGGRAPH Asia)},\n month = oct,\n number = {6},\n pages = {248:1--248:16},\n publisher = {ACM},\n volume = {34},\n year = {2015}\n}\n```\n\nThis repository was originally developed for SMPL-X / SMPLify-X (CVPR 2019), you might be interested in having a look: [https://smpl-x.is.tue.mpg.de](https://smpl-x.is.tue.mpg.de).\n\n## Acknowledgments\n\n### Facial Contour\n\nSpecial thanks to [Soubhik Sanyal](https://github.com/soubhiksanyal) for sharing the Tensorflow code used for the facial\nlandmarks.\n\n## Contact\nThe code of this repository was implemented by [Vassilis Choutas](vassilis.choutas@tuebingen.mpg.de).\n\nFor questions, please contact [smplx@tue.mpg.de](smplx@tue.mpg.de).\n\nFor commercial licensing (and all related questions for business applications), please contact [ps-licensing@tue.mpg.de](ps-licensing@tue.mpg.de).\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "PyTorch module for loading the SMPLX body model",
"version": "0.1.28",
"project_urls": {
"Homepage": "http://smpl-x.is.tuebingen.mpg.de"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c933bd37416aec828e7465652d9e2525fe52de0a29a581f1519cc51a74485091",
"md5": "fd3436bf65fae327188e0294d73df388",
"sha256": "e8ff3d278a015c097dc86d44a38475da4ac170042943c84c08eee433629406a7"
},
"downloads": -1,
"filename": "smplx-0.1.28-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fd3436bf65fae327188e0294d73df388",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6.0",
"size": 29903,
"upload_time": "2021-05-26T12:14:08",
"upload_time_iso_8601": "2021-05-26T12:14:08.641096Z",
"url": "https://files.pythonhosted.org/packages/c9/33/bd37416aec828e7465652d9e2525fe52de0a29a581f1519cc51a74485091/smplx-0.1.28-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "69eb51da17b291fb1221317a1ff65a301fb2cf9c6c0dd87a0caec4cbcd06c1da",
"md5": "f0e4d01444391b8121a1edd32e2a6295",
"sha256": "c3a1e2c3069cdf7a4b34fd250c2484c8bb1a4fd9c14490da9359af5fbc64fbe6"
},
"downloads": -1,
"filename": "smplx-0.1.28.tar.gz",
"has_sig": false,
"md5_digest": "f0e4d01444391b8121a1edd32e2a6295",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6.0",
"size": 28500,
"upload_time": "2021-05-26T12:14:10",
"upload_time_iso_8601": "2021-05-26T12:14:10.194186Z",
"url": "https://files.pythonhosted.org/packages/69/eb/51da17b291fb1221317a1ff65a301fb2cf9c6c0dd87a0caec4cbcd06c1da/smplx-0.1.28.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-05-26 12:14:10",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "smplx"
}
JSON