Skip to content

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.

A skeleton animates while its hand traces a blue trajectory. pybvh renders motion, and it extracts trajectories from it. You can analyze those trajectories

  • 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?

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."