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 four 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_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, see below

Missing one? That's fine — the script converts whatever it finds and skips the rest with a warning.

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
│   ├── SMPLH_FEMALE.pkl / .npz
│   ├── SMPLH_NEUTRAL.pkl / .npz
│   └── amass_16betas/          # only if smplh.tar.xz was provided, see below
└── mano/
    ├── MANO_LEFT.pkl / .npz
    └── MANO_RIGHT.pkl / .npz

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

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
--convert_csc_matrix	off	Densify any leftover scipy sparse matrices into plain float32 arrays
--clean	off	Wipe the cached extraction and re-extract everything from scratch

4. Test

python test.py --models_path body_models

Loads every .pkl/.npz under body_models/ and checks it's a well-formed dict of plain numeric arrays.

---

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	Everything — this is what step 1 above uses.
smplx.zip ("ready to load by the smplx package")	16	M / F only	Yes	Nothing new — smplh_300.zip is a strict upgrade, unless you specifically need the legacy 16-beta pkl format.
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.

If you need the AMASS-exact 16-beta variant: download smplh.tar.xz and drop it in zips/. The next time you run convert_smpl.py, it's automatically merged with the MANO hands you already downloaded and written to body_models/smplh/amass_16betas/, kept separate since the shape space isn't compatible with the 300-beta files.

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:

   import chumpy
   print(chumpy.__file__)

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

   from numpy import bool, int, float, complex, object, unicode, str, nan, inf

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

   want_out = 'out' in inspect.getargspec(func).args

   to:

   want_out = 'out' in inspect.getfullargspec(func).args

Thanks

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