pybvh¶
pybvh is a lightweight Python library to read, write, and manipulate BVH motion capture files.
pybvh is framework-agnostic. It outputs pure NumPy arrays. It understands motion capture data, but it does not assume what you will do with the data. The same library serves ML researchers, biomechanics scientists, and game developers.

- Quick Start — load a file, get NumPy arrays, write it back, in five minutes
- Feature Gallery — every visual capability of the library, one picture and one call each
- Find a function — "I want to…" → the exact call → its reference page
- User Guide — the concepts: index spaces, centering, up axes, representations
- Tutorials — eight notebooks from first file to motion descriptors
- Install —
pip install pybvh; optional extras for visualization backends
What can pybvh do?¶
- Read & write BVH files, and keep the full hierarchy and all the motion data — I/O API
- Rotation conversions between Euler angles, rotation matrices, quaternions, 6D, and axis-angle. All conversions are vectorized with NumPy
- Forward kinematics to compute 3D joint positions from angles
- Skeleton operations: retargeting, scaling, joint extraction, Euler order changes
- Frame operations: slicing, concatenation, resampling to different frame rates
- Spatial transforms: mirroring, vertical rotation, speed perturbation, joint noise, root translation, frame dropout. All of them support seeded randomization
- Motion analysis: joint velocities/accelerations, root trajectory, foot contact detection, and a one-stop
to_feature_array()export - Motion descriptors: trajectory geometry, dynamics (jerk, smoothness, kinetic energy), gait, and SE(3) rigid-transform math. All of it is pure NumPy. Each one is drawn in the gallery
- Signal utilities: finite differences, temporal statistics, smoothing, FFT, polyline simplification
- Batch loading of entire directories with optional parallelism and dataset harmonization
- 3D visualization: publication-grade stills, the sampled-poses sequence figure, ghost trails, turntable orbits, video export and shadowed capsule renders. The four backends are matplotlib, OpenCV, k3d, and vedo
Quick example¶
import pybvh
bvh = pybvh.read_bvh_file("walk.bvh")
bvh.root_pos # (F, 3) root translation
bvh.joint_angles # (F, J, 3) Euler angles in radians
# Convert to 6D rotation representation
rot6d = bvh.to_6d() # (F, J, 6)
# Export features for ML
features = bvh.to_feature_array(representation="6d", include_velocities=True)
Companion library¶
For ML-specific features (tensor packing, PyTorch Datasets, augmentation pipelines), see pybvh-ml (repo).
Stability and versioning¶
pybvh is in 0.x. Expect breaking changes between minor versions.
We treat 0.x as design space. When a past choice proves to be wrong, we fix it at the root, and we do not keep the old choice. Each release has a clear migration path in the CHANGELOG. There are no deprecation cycles.
If you depend on pybvh from production code:
- Pin to an exact version (
pybvh==0.8.0). - Read the upgrade notes before you move to a newer version.
pybvh will commit to strict semver at 1.0:
- No breaking changes within a major version.
- Deprecation warnings before any removal, for at least one minor release.
Until then, "make the library better" wins over "preserve the old behavior."