SMPLCodec is a minimal pure-Python library that provides a standardized way to read and write SMPL(-H/-X) parameters of bodies and animations as .smpl files, and export meshcapde scenes as .mcs files.
See the SMPL Wiki for a general description of the model, and the SMPL-X project page and GitHub for model data and code for the most commonly used version.
pip install smplcodecA .smpl files is simply an NPZ that follows some conventions. It is flat-structured and only contains numeric (specifically int32 and float32) data for maximum interoperability. The library provides a SMPLCodec dataclass which provides convenience methods for reading, writing, and validating SMPL data.
from smplcodec import SMPLCodec, SMPLVersion, SMPLGender
# Read a 601-frame sequence from a file
a = SMPLCodec.from_file("avatar.smpl")
# The full_pose helper property contains the sequence data
assert a.full_pose.shape == (601, 55, 3)
# You can also load AMASS sequences
a = SMPLCodec.from_amass_npz("motion.npz")
# Create a new neutral avatar and write it to file
b = SMPLCodec(smpl_version=SMPLVersion.SMPLX, gender=SMPLGender.NEUTRAL, shape_parameters=np.zeros(10))
b.write("neutral.smpl")
SMPLCodec also provides functionality to export meshcapade scenes as .mcs files (GLTF format with SMPL extensions). The class-based interface makes it easy to create scenes with custom cameras and SMPL bodies:
from smplcodec.mcs import SceneExporter, CameraIntrinsics, CameraPose
from smplcodec.codec import SMPLCodec
import numpy as np
# Create exporter
exporter = SceneExporter()
# Load SMPL data using SMPLCodec
body = SMPLCodec.from_file("avatar.smpl")
# Custom camera setup
camera_intrinsics = CameraIntrinsics(focal_length=1000.0, principal_point=(640.0, 480.0))
camera_pose = CameraPose(
rotation_matrix=np.eye(3, dtype=np.float32),
translation=np.array([0.0, 0.0, -5.0], dtype=np.float32)
)
# Export scene
exporter.export_single_frame([body], "scene.mcs", camera_intrinsics, camera_pose)For detailed documentation, see MCS_INTERFACE_GUIDE.md.
This library is released under the MIT license.