neural-ik-smpl

neural-ik-smpl — SMPL-IK learned inverse kinematics (AMASS)

A learned full-body inverse-kinematics (IK) posing model for the SMPL body model, in the SMPL-IK / ProtoRes family: given a sparse, variable set of effector constraints (3D position targets, 6D rotation targets, and/or look-at targets on any subset of the 24 SMPL body joints, plus SMPL shape betas and gender), the network predicts a full-body pose — per-joint rotations and root position — which is then refined through SMPL forward kinematics.

This checkpoint is an independent reproduction of SMPL-IK: Learned Morphology-Aware Inverse Kinematics for AI Driven Artistic Workflows (Voleti et al., 2022), trained from scratch on AMASS with the official upstream code and configuration from boreshkinai/smpl-ik. It is an intermediate checkpoint (epoch 13 of 120) that already matches the paper's reported validation accuracy; training continues and this card will be updated as later checkpoints land.

• Checkpoint file: smplik_amass_canonical_epoch13.ckpt (PyTorch Lightning checkpoint, ~515 MB)
• Provenance: canonical run epoch=13-step=345071.ckpt
• SHA-256: e95de5c2cff1e36a69302b08931f56eda9c8b55511e6e4a2337384e2737d14e2
• Code (inference overlay): https://github.com/CHDTevior/neural-IK-smpl
• Upstream training code: https://github.com/boreshkinai/smpl-ik (commit ea74d47)

Training details

No hyperparameters were changed relative to the official configuration; this is a faithful reproduction run, not a re-tuning.

Evaluation

Metrics follow the paper's protocol: the random effector scheme — for each validation/test sample a random combination of effectors (type, count, and joint assignment) is drawn, the model predicts the full pose, and error is computed over all 24 joints after SMPL forward kinematics. MPJPE is pelvis-aligned mean per-joint position error; PA-MPJPE applies Procrustes alignment. All values in millimeters (lower is better).

The fixed scheme uses the deterministic validation effector set defined in the upstream config (head, hands, feet, root); the random scheme is the paper's headline benchmark. At epoch 13 the model is already at paper-level validation accuracy on the headline metric.

How to use

The checkpoint is a standard PyTorch Lightning checkpoint whose state_dict loads strictly into the upstream model. The companion repo CHDTevior/neural-IK-smpl overlays the upstream smpl-ik code with a reproducible environment: run its setup.sh to clone/pin upstream at ea74d47, create the environment, and fetch the SMPL model files (you must register at MPI SMPL yourself — they are not redistributed). It also ships a demo server that serves an interactive posing page (drag effector targets, watch the predicted skeleton follow) backed by this checkpoint.

# Inside the repo root after setup.sh (upstream smpl-ik code + SMPL models in place)
import torch, yaml
from pathlib import Path
from hydra.experimental import compose, initialize_config_dir
from hydra.utils import instantiate
from sklearn.model_selection import ParameterGrid
from smplik.utils.model_factory import ModelFactory
import smplik.models  # registers model classes

REPO = Path(".").resolve()
initialize_config_dir(config_dir=str(REPO / "configs"))
exp = yaml.safe_load((REPO / "configs/experiments/smplik_amass.yaml").read_text())
params = {k: v if isinstance(v, list) else [v] for k, v in exp["parameters"].items()}
overrides = [f"{k}={v}" for k, v in list(ParameterGrid(params))[0].items()]
cfg = compose(exp["base_config"] + ".yaml", overrides=overrides).model

dm = instantiate(cfg.dataset); dm.prepare_data()
model = ModelFactory.instantiate(cfg, data_components=dm.get_data_specific_components())
ckpt = torch.load("smplik_amass_canonical_epoch13.ckpt", map_location="cpu")
model.load_state_dict(ckpt["state_dict"], strict=True)
model.eval()

# Build an effector query: betas [B,10], gender [B,1], position targets [B,N,3]
# with position_id [B,N] (SMPL joint indices), weight=1, tolerance=0; empty
# rotation/look-at slots. Then:
#   predicted = model.forward(input_data)   # joint 6D rotations + root position
# and refine through SMPL FK (see run_demo_inference.py in the repo for the
# exact input dict layout and the FK-refinement step used for all metrics above).

For an end-to-end runnable example (checkpoint load, effector construction, FK refinement, and MPJPE computation), see run_demo_inference.py in the companion repo; the demo server README covers the interactive visualization.

Limitations

• Body only: 24-joint SMPL body — no hands (MANO), no face, no SMPL-X.
• Pose distribution: trained on AMASS mocap; poses far outside the AMASS distribution (extreme contortions, interactions with objects) may resolve poorly.
• Intermediate checkpoint: epoch 13 of a 120-epoch schedule. Validation accuracy already matches the paper; the campaign's later epochs (through 21) plateaued at the same level.
• Requires the SMPL body model files at inference time for FK refinement (registration with MPI required; not included here).

License & attribution

These weights are released for NON-COMMERCIAL ACADEMIC RESEARCH ONLY.

They are a derived work of:

• the upstream smpl-ik code by Boris Oreshkin and co-authors, which is licensed for non-commercial use — see the upstream license;
• the AMASS dataset, available under a non-commercial academic license;
• the SMPL body model — the SMPL model files are NOT included in this repository; obtain them by registering at https://smpl.is.tue.mpg.de/ and complying with the SMPL license.

Any use of these weights must comply with all three upstream licenses. Commercial use is not permitted. Full credit for the method and the original implementation goes to the SMPL-IK authors (Voleti, Oreshkin, Bocquelet, Harvey, Ménard, Pal); this repository only contributes an independent training run and packaging.

Citation

If you use these weights, please cite the original SMPL-IK paper and AMASS:

@inproceedings{voleti2022smplik,
  author    = {Voleti, Vikram and Oreshkin, Boris N. and Bocquelet, Florent and
               Harvey, F{\'e}lix G. and M{\'e}nard, Louis-Simon and Pal, Christopher},
  title     = {{SMPL-IK}: Learned Morphology-Aware Inverse Kinematics for AI Driven
               Artistic Workflows},
  booktitle = {SIGGRAPH Asia 2022 Technical Communications (SA '22)},
  year      = {2022},
  note      = {arXiv:2208.08274},
  url       = {https://arxiv.org/abs/2208.08274}
}

@inproceedings{AMASS:ICCV:2019,
  author    = {Mahmood, Naureen and Ghorbani, Nima and Troje, Nikolaus F. and
               Pons-Moll, Gerard and Black, Michael J.},
  title     = {{AMASS}: Archive of Motion Capture as Surface Shapes},
  booktitle = {International Conference on Computer Vision (ICCV)},
  pages     = {5442--5451},
  year      = {2019}
}