pybvh
A lightweight Python library for reading, writing, and manipulating BVH motion capture files. Built for researchers and developers working with skeletal animation and motion data.
Documentation · Quick Start · Feature Gallery — every feature, one picture each · Find a function · Tutorials
Features
- Read & write BVH files with full hierarchy and motion data preservation — I/O
- Rotation conversions between Euler angles, rotation matrices, quaternions, 6D (Zhou et al.), and axis-angle — all vectorized with NumPy — guide
- Forward kinematics to compute 3D joint positions from angles — core concepts
- Skeleton operations: retargeting, scaling, joint extraction, Euler order changes — guide
- Frame operations: slicing, concatenation, resampling to different frame rates — guide
- Spatial transforms: mirroring, vertical rotation, speed perturbation, joint noise, root translation, frame dropout — all with seeded randomization — guide
- Motion analysis: joint velocities/accelerations, root trajectory, foot contact detection, gait parameters, and a one-stop
to_feature_array()export — guide - Motion descriptors: trajectory geometry (curvature, torsion, path length, bounding volumes, centre of mass), dynamics (jerk, smoothness/SPARC, kinetic energy, gait), and SE(3) rigid-transform math (twists, screw interpolation, geodesic distance) — all pure NumPy — guide · gallery
- Signal utilities (
pybvh.signal): finite differences, temporal statistics, smoothing, FFT/dominant frequency, polyline simplification — API - Batch loading of entire directories with optional parallel I/O — guide
- Pandas ready —
to_df_dict()output drops straight intopd.DataFrame— guide - 3D visualization: publication-grade stills, the sampled-poses sequence figure, ghost trails, turntable orbits, video export, and shadowed capsule renders — matplotlib, OpenCV, k3d and vedo backends — guide · API
Philosophy
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. For ML-specific features (tensor packing, PyTorch Datasets, augmentation pipelines), see the companion library pybvh-ml (documentation).
Installation
pip install pybvh
Quick Start
import pybvh
# Load a BVH file (pybvh.Bvh.from_file("walk.bvh") is the classmethod spelling)
bvh = pybvh.read_bvh_file("walk.bvh")
print(bvh) # "24 joints, 75 frames at 30.0 fps (frame_time=0.033333s, from walk.bvh)"
# Access motion data as NumPy arrays
bvh.root_pos # (F, 3) root translation per frame
bvh.joint_angles # (F, J, 3) Euler angles in radians
bvh.joint_names # ['Hips', 'Spine', ...] (excludes end sites)
# Get 3D joint positions via forward kinematics
coords = bvh.node_positions() # (F, N, 3)
# Convert to other rotation representations
root_pos, quats = bvh.to_quat() # (F, 3), (F, J, 4)
root_pos, rot6d = bvh.to_6d() # (F, 3), (F, J, 6)
# Write back to file
bvh.write("output.bvh")
Motion Analysis
vel = bvh.joint_velocities() # (F, J, 3) in units/second
contacts = bvh.foot_contacts() # (F, num_feet) binary labels, feet auto-detected
# One-stop export — flat feature array for ML pipelines
features = bvh.to_feature_array(
representation="6d",
include_velocities=True,
include_foot_contacts=True,
) # (F, D)
Beyond the basics sits a full descriptor layer — curvature, smoothness (SPARC), kinetic energy, gait parameters, SE(3) twists — each drawn with its exact call in the Feature Gallery and explained in the Motion Descriptors guide.
Visualization
bvh.plot_rest_pose() # T-pose
bvh.plot_frame(frame=0, camera="front") # also "side", "top", (azim, elev)
bvh.plot_sequence(n_poses=8) # the motion-paper still: time as lightness
bvh.plot_trajectory() # 2D top-down root path
bvh.render("walk.mp4", codec="h264") # video/GIF/HTML export, browser-playable
bvh.render("walk.mp4", ghost=3, trajectory=True) # faded trail + root path on the floor
bvh.render("orbit.mp4", camera="turntable") # a full 360-degree orbit over the clip
bvh.plot_frame(frame=0, backend="vedo") # shadowed 3D capsules, offscreen, headless-safe
bvh.play() # interactive playback (auto-detects backend)
Every function takes style=: "paper" (the default — ground plane, per-chain bone colors, joint markers, axes off), "dark" for slides, "debug" for reading coordinates off the axes, or a Style instance overriding any field.
pip install pybvh[opencv] # Fast video rendering
pip install pybvh[interactive] # k3d for Jupyter notebooks
pip install pybvh[viewer] # vedo for desktop interactive viewer
pip install pybvh[all-viz] # All of the above
Getting figures out of Python and into a paper — vector stills, supplementary video, the capsule look: Publication Figures. Multi-skeleton comparison, camera control, and backend details: Visualization API.
More
| Topic | In one line | Docs |
|---|---|---|
| Batch loading | Load a directory, harmonize heterogeneous skeletons, export one padded array | Feature Export |
| Spatial transforms | mirror, rotate_vertical, add_rotation_noise, perturb_speed, drop_frames — seeded randomization |
Data Augmentation |
| Skeleton & frame ops | retarget, scale, extract_joints, slicing, concatenation, resample |
Skeleton Operations |
| Rotation utilities | Batch-vectorized conversions between all five representations, SLERP, SE(3) | Rotations & SE(3) |
| World up & orientation | Up-axis detection, forward_at/left_at, reorientation |
World Up |
| Pandas integration | to_df_dict() / df_to_bvh() round trip |
Skeleton Operations |
Tutorials
Eight Jupyter notebooks with detailed walkthroughs, from reading your first file to motion descriptors — see the tutorials page.
Each tutorial is committed as a Jupytext-paired .ipynb + .py so the source is reviewable as plain Python.
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. No deprecation cycles, no compatibility shims; each release ships a single clean migration path, documented in the CHANGELOG. If you depend on pybvh from production code, pin to an exact version (pybvh==0.8.2) and read the upgrade notes before bumping.
This will change at 1.0: from then on, pybvh will commit to strict semver — no breaking changes within a major version, deprecation warnings (at least one minor release) before any future removal. Until 1.0, "make the library better" wins over "preserve the old behavior."
Requirements
- Python >= 3.9
- NumPy >= 1.21
- Matplotlib >= 3.7
Pandas is optional (pip install "pybvh[pandas]") - only used in the tutorials, not part of pybvh library.
Citing pybvh
If pybvh is useful in your research, please cite it. On GitHub, the Cite this repository button in the sidebar gives APA and BibTeX generated from CITATION.cff. In BibTeX, with version set to the release you used:
@software{schneider_pybvh,
author = {Schneider, Victor},
title = {pybvh},
url = {https://github.com/VictorS-67/pybvh},
version = {0.9.0},
year = {2026}
}
License
Metadata
Release files for pybvh 0.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pybvh-0.9.0.tar.gz | 240.6 kB | With provenance | Details for pybvh-0.9.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pybvh-0.9.0-py3-none-any.whl | Python 3 | none | any | Details for pybvh-0.9.0-py3-none-any.whl |
Total release size: 491.8 kB
Release files / pybvh-0.9.0.tar.gz
| Download URL | pybvh-0.9.0.tar.gz |
|---|---|
| Size | 240.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4ba1261330e241bd55e89e52acb421bfae8cadfccb0bda019df30b6ef0beb06b
|
|
BLAKE2b-256 checksum How to use checksums |
3e8c8c8ea1797219dadb7197497ecbe1debf0c6a8b0dd1bd86815524017ca835
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logRelease files / pybvh-0.9.0-py3-none-any.whl
| Download URL | pybvh-0.9.0-py3-none-any.whl |
|---|---|
| Size | 251.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b4cf8978a454f9dfd30535a0ef0265b0dd05f43925011b9413793cb41fdde8a7
|
|
BLAKE2b-256 checksum How to use checksums |
cc9df6e0c924dac66d9bedb3ac3d6720c8f8790e971f350ffd86be4ea1a7d339
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logSecurity for pybvh 0.9.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pybvh-0.9.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 28, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.