SMPL Family → Python 3

Converts the official SMPL, SMPL-X, SMPL+H, and MANO downloads into plain .pkl / .npz files — no Chumpy, no Python 2, ready to pickle.load or numpy.load directly. Output matches the layout expected by smplx, aitviewer, and similar packages.

1. Download the models

You'll need free accounts on the SMPL, SMPL-X, and MANO sites and must accept each license to download. Grab these files and drop them — unmodified, still zipped — into a zips/ folder in the repo root:

Model	Get this exact download	Save as
SMPL	"Download version 1.1.0 for Python 2.7 (female/male/neutral, 300 shape PCs)"	SMPL_python_v.1.1.0.zip
SMPL-X	"Download SMPL-X with removed head bun (NPZ, 392 MB)"	smplx_lockedhead_20230207.zip
SMPL+H	"Full SMPL+H model version with 300 shape components"	smplh_300.zip
MANO	"Models & Code"	mano_v1_2.zip
SMPL+H (AMASS) — optional, only needed for AMASS	"Extended SMPL+H model (used in AMASS project)"	smplh.tar.xz

SMPL_to_python3/
├── convert_smpl.py
├── chumpy/
├── requirements.txt
├── test.py
└── zips/
├── SMPL_python_v.1.1.0.zip
├── smplx_lockedhead_20230207.zip
├── smplh_300.zip
├── mano_v1_2.zip
└── smplh.tar.xz # optional — needed for AMASS, see below

Missing one? That's fine — the script converts whatever it finds and skips the rest with a warning. smplh.tar.xz is the one exception worth calling out: it's optional for the core SMPL/SMPL-X/SMPL+H/MANO conversion, but required if you want to work with AMASS — see the fine print below.

2. Set up the environment

Tested on Python 3.11. No conda needed — the bundled chumpy/ package (already patched for Python 3 / modern NumPy) is loaded straight from this repo.

git clone https://github.com/keatonkraiger/SMPL_2_Python3.git
cd SMPL_to_python3
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Convert

python convert_smpl.py

Extracts everything in zips/ and writes converted models to body_models/:

body_models/
├── smpl/
│ ├── SMPL_MALE.pkl / .npz
│ ├── SMPL_FEMALE.pkl / .npz
│ └── SMPL_NEUTRAL.pkl / .npz
├── smplx/
│ ├── SMPLX_MALE.pkl / .npz
│ ├── SMPLX_FEMALE.pkl / .npz
│ └── SMPLX_NEUTRAL.pkl / .npz
├── smplh/
│ ├── SMPLH_MALE.pkl / .npz # 300-beta, hands merged — smplx.create()
│ ├── SMPLH_FEMALE.pkl / .npz
│ ├── SMPLH_NEUTRAL.pkl / .npz
│ ├── amass_16betas/ # only if smplh.tar.xz was provided, see below
│ │ ├── SMPLH_MALE.pkl / .npz # 16-beta, hands merged — smplx.create(), AMASS-exact shape
│ │ ├── SMPLH_FEMALE.pkl / .npz
│ │ └── SMPLH_NEUTRAL.pkl / .npz
│ ├── male/model.npz # 16-beta, un-merged — human_body_prior.BodyModel, AMASS-native
│ ├── female/model.npz
│ └── neutral/model.npz
└── mano/
├── MANO_LEFT.pkl / .npz
└── MANO_RIGHT.pkl / .npz

If smplh.tar.xz is in zips/, the two AMASS-compatible 16-beta SMPLH variants (see below) are built automatically too — no extra flag needed.

SMPL-X is always written as both .pkl and .npz regardless of --format, since smplx's own SMPLX class defaults to reading .npz while other tools expect .pkl — matching the official model layout.

Useful flags:

Flag	Default	Effect
--zips_path	zips	Folder containing the downloaded archives
--output_path	body_models	Where converted models are written
--format	both	pkl, npz, or both (SMPL-X always gets both, see above)
--clean	off	Wipe the cached extraction and re-extract everything from scratch

4. Test

python test.py --models_path body_models

Runs two stages:

1. Structural — loads every .pkl/.npz under body_models/ and checks it's a well-formed dict of plain numeric arrays. No extra dependencies.
2. Functional — actually instantiates each model through smplx's own smplx.create() (the way any real downstream code would) and runs a forward pass, for every gender/extension found, including both use_pca=True and use_pca=False for hand-articulated models. This is what catches a genuinely broken file (e.g. missing hand components) — a structurally "valid" dict of arrays can still be unusable. The AMASS-native smplh/<gender>/model.npz files (if present) get their own check, run through the same skinning math human_body_prior.BodyModel uses, since they're not loaded via smplx.create() at all.

Stage 2 needs torch and smplx, which aren't part of the base requirements.txt (this repo only needs numpy/scipy/six to convert models, not use them):

pip install -r requirements-test.txt

If they're not installed, stage 2 is skipped with a warning rather than failing. Pass --skip-functional to run structural checks only on purpose.

---

SMPLH + MANO — the fine print

The MANO/SMPL+H download page lists three different SMPL+H packages, which is easy to mix up:

File	Betas	Genders	Hands included?	Use it for...
smplh_300.zip ✅ recommended	300	M / F / N	Yes	General-purpose use — this is what step 1 above uses, written to smplh/.
smplx.zip ("ready to load by the smplx package")	16	M / F only	Yes	Nothing new — this repo reproduces the same thing itself (see below), plus NEUTRAL.
smplh.tar.xz ("Extended SMPL+H, used in AMASS")	16	M / F / N	No — bare bodies only	Reproducing AMASS mocap exactly, which was fit with this specific 16-beta shape space.

AMASS betas/poses are only meaningful against that last, 16-beta shape space — plugging AMASS data into the 300-beta model gives a plausible-looking but wrong body, since the two aren't the same PCA basis. If you're working with AMASS: download smplh.tar.xz and drop it in zips/. The next run of convert_smpl.py builds two things from it, because different AMASS tooling expects different things:

• body_models/smplh/amass_16betas/SMPLH_<GENDER>.{pkl,npz} — the bare body merged with your downloaded MANO hands (same merge tools/merge_smplh_mano.py describes), in the flat layout smplx's own SMPLH class / smplx.create() expects. Use this if your AMASS code loads models through the smplx package.
• body_models/smplh/<gender>/model.npz — the bare body as-is, no MANO merge. human_body_prior's BodyModel (used in the official AMASS/DMPL tutorials) reads v_template/shapedirs/J_regressor/posedirs/kintree_table/weights directly and treats hand pose as raw per-joint rotation, not MANO's PCA components — it has no use for a hand merge at all, and only accepts .npz. This path also matches the exact filename the AMASS tutorials expect when pointed at support_dir=body_models.

If you're not sure which you need: the second one is the closer match to how the official AMASS example notebooks load models. Use the first only if you're deliberately loading AMASS sequences through smplx.create() instead.

Troubleshooting: modifying Chumpy source yourself

Only do this if the bundled chumpy/ folder doesn't work for you. If you go this route, delete the bundled chumpy/ folder and install the PyPI version instead:

pip install chumpy==0.70

1. Find where it installed:

   importchumpyprint(chumpy.__file__)

2. In chumpy/__init__.py, comment out the line:

   fromnumpyimportbool, int, float, complex, object, unicode, str, nan, inf

3. In chumpy/ch.py, change (around line 1203):

   want_out='out'ininspect.getargspec(func).args

   to:

   want_out='out'ininspect.getfullargspec(func).args

Thanks

It would be nice for SMPL to be updated to Python 3 officially and centralized.