$ show nghorbani/human_body_prior
This repository implements VPoser, a variational autoencoder-based human pose prior for SMPL/X body models. It provides tools to encode/decode human poses into a low-dimensional latent space, sample novel poses, and perform inverse kinematics fitting to 2D/3D key points using the learned prior. The codebase includes data preparation scripts for the AMASS dataset, a PyTorch Lightning trainer, a flexible IK engine with LBFGS/Adam optimizers, and utilities for rotation mathematics and linear blend skinning. The system is designed as a reusable library for pose prior applications in research and graphics. Architecture-wise, the project is organized into modules: body_model (SMPL/X loading and LBS), models (VPoser VAE and IK engine), tools (rotation conversions, 6D representation, file/path helpers), data (dataset loading and preparation), train (training scripts), and tutorials (Jupyter notebooks and example scripts). Entry points include training scripts (e.g., train/V02_05/V02_05.py), IK demonstrations (tutorials/ik_example_*.py), and usage tutorials (tutorials/vposer.ipynb). External dependencies are primarily PyTorch, Lightning, OmegaConf, and optional visualization packages. Data flows: For training, AMASS .npz files are converted to .pt tensors via prepare_data.py, loaded by VPoserDS, and fed into VPoserTrainer. For inference, pretrained models are loaded via model_loader.py, enabling pose encoding/decoding or IK fitting. The IK engine iteratively optimizes pose, shape, and translation in the VPoser latent space to match target key points.
The LLM identified 4 files worth highlighting for reuse:
Implements the 6D continuous rotation representation and a geodesic loss function for regression of rotations. This component solves the common problem of discontinuities in Euler angles or axis-angle representations when training neural networks to predict rotations, providing a smooth, differentiable representation that can be dropped into any rotation prediction task.
Provides a comprehensive set of conversion utilities between axis-angle, rotation matrices, quaternions, and Euler angles, along with batch rigid transformation functions. These tools are self-contained, well-tested, and can be reused in any project dealing with 3D rotations or pose manipulation without modification.
Implements a flexible inverse kinematics engine that optimizes body pose, shape, and translation in the latent space of a pose prior (e.g., VPoser) to match user-defined key points. It supports batch processing, LBFGS and Adam optimizers with Wolfe line search, optional visualization, and configurable loss weights. The engine is decoupled from the specific prior model via an abstract interface, making it adaptable to other pose priors with minimal changes.
Contains a robust, batched implementation of Linear Blend Skinning with pose blend shapes, shape blending, and joint regression. This function can be used with any body model that provides the necessary parameters (shape, pose, joint regressor, weights) and is a core reusable component for forward skinning in character animation and pose-driven mesh deformation.