pybvh

A lightweight Python library for reading, writing, and manipulating BVH motion capture files.

pybvh is framework-agnostic and outputs pure NumPy arrays. It understands motion capture data but does not assume what you'll do with it — 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 with full hierarchy and motion data preservation — I/O API
• Rotation conversions between Euler angles, rotation matrices, quaternions, 6D, and axis-angle — all 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 with 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 pure NumPy, each one 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 with multiple backends (matplotlib, OpenCV, k3d, vedo) — snapshots, video export, interactive playback

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
root_pos, rot6d = bvh.to_6d()

# 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 turns out to be wrong, we fix it at the root rather than carry scar tissue forward. Each release has a clear migration path in the CHANGELOG, no deprecation cycles. If you depend on pybvh from production code, pin to an exact version (pybvh==0.8.0) and read the upgrade notes before bumping.

pybvh will commit to strict semver at 1.0: no breaking changes within a major version, deprecation warnings (at least one minor release) before any removal. Until then, "make the library better" wins over "preserve the old behavior."