Skip to content

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

coords = bvh.node_positions()  # (F, N, 3) via forward kinematics

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

bvh.write("output.bvh")

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.