Quick Start¶
Loading a BVH file¶
import pybvh
bvh = pybvh.read_bvh_file("walk.bvh")
print(bvh) # "24 joints, 75 frames at 30.0 fps (frame_time=0.033333s, from walk.bvh)"
Accessing motion data¶
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)
bvh.joint_count # 24
bvh.euler_orders # ['ZYX', 'ZYX', ...] per joint
3D joint positions¶
The centered parameter picks the coordinate frame. See Core Concepts.
Rotation representations¶
quats = bvh.to_quat() # (F, J, 4)
rot6d = bvh.to_6d() # (F, J, 6)
aa = bvh.to_axisangle() # (F, J, 3)
To pick one, read Choosing a Representation. For the full conversion API, read Rotation Representations & SE(3).
Writing back to file¶
Visualization¶
For a single skeleton, the most natural calls are the methods on the Bvh object:
# Rest pose (T-pose / bind pose)
bvh.plot_rest_pose()
# Static 3D snapshot with camera control
bvh.plot_frame(frame=0, camera="front") # also "side", "top", (azim, elev)
# Export animation to video (OpenCV if installed, else matplotlib)
bvh.render("walk.mp4")
# Camera tracks the character's rotation smoothly
bvh.render("walk_follow.mp4", follow=True)
# Interactive playback (auto-detects best backend)
bvh.play()
# 2D root trajectory
bvh.plot_trajectory()
To compare several skeletons, use the functions of the pybvh.bvhplot module. They accept a list of Bvh objects:
from pybvh import bvhplot
bvhplot.frame([bvh1, bvh2], frame=0, labels=["A", "B"])
bvhplot.render([bvh1, bvh2], "compare.mp4", labels=["A", "B"], sync="pad")
bvhplot.trajectory([bvh1, bvh2], labels=["A", "B"])
The Bvh object gives the character's orientation as a property and a method. The World Up guide tells the full story:
bvh.world_up # e.g. '+y' or '+z' — auto-detected gravity axis
bvh.forward_at(0) # facing direction in world space at frame 0
bvh.world_up = '+y' # manual override if the auto-detect is wrong
For the full visualization options (cameras, backends, side-by-side), read the Visualization API.
Where to next¶
This page covered loading, arrays, and writing. They are a small part of the library. The library also has a full analysis layer: augmentation transforms (mirror, noise, speed), foot contacts and gait parameters, motion descriptors (curvature, smoothness/SPARC, kinetic energy), and SE(3) rigid-transform features.
- Feature Gallery — every visual capability, one picture and one call each. It is the fastest way to see what pybvh can do.
- Find a function — the "I want to… → call" capability map.
- Core Concepts — index spaces and centering modes. Ten minutes here prevent most bugs.
- Motion Descriptors guide — the quantitative analysis layer.
- Tutorials — eight notebooks with detailed walkthroughs.