Core Concepts¶
The BVH format¶
A BVH file has two sections:
- HIERARCHY defines a skeleton as a tree of joints. Each joint has an offset (bone vector from parent) and rotation channels (e.g.,
Zrotation Yrotation Xrotation). Leaf nodes called "End Sites" have only an offset. -
MOTION holds the per-frame data: the number of frames (
Frames:), the seconds per frame (Frame Time:), then one row of floats per frame. Its columns are the channels, in the depth-first order in which the HIERARCHY declares them. Each joint has one block of columns:- The root has six values: three positions and three Euler angles. A static root (
CHANNELS 0) has no columns. It stays at its offset in every frame. - A joint other than the root has three Euler angles.
- A translating joint is a joint other than the root with
CHANNELS 6. It has three positions and three Euler angles. Its positions replace its offset in each frame.
pybvh writes the three positions of a block before its Euler angles. It reads a block that declares its channels in another order, and reorders it.
- The root has six values: three positions and three Euler angles. A static root (
The Bvh object¶
Bvh is the central container. It holds:
| Attribute | Shape | Description |
|---|---|---|
root_pos |
(F, 3) |
Root translation per frame |
joint_angles |
(F, J, 3) |
Euler angles (radians) per joint per frame |
joint_translations |
(F, P, 3) |
Per frame, the position relative to its parent of each translating joint; P = 0 on a skeleton whose joints other than the root only rotate |
nodes |
tuple | All skeleton nodes (joints + end sites) in depth-first order; frozen, see Editing a skeleton |
joint_names |
list of str | Non-end-site joint names |
euler_orders |
list of str | Per-joint Euler orders (e.g. ['ZYX', ...]); '' on a static root, which declares no rotation channel |
edges |
list of tuples | Skeleton edge list as (child_idx, parent_idx) |
frame_time |
float | Seconds per frame |
world_up |
str | Gravity axis (e.g. '+y', '+z'). Auto-detected, settable. |
Index spaces¶
pybvh has two index spaces:
node_indexincludes end sites. It maps tobvh.nodes.node_positions()uses it.- The
joint_anglesindex excludes end sites. It maps tobvh.joint_namesand to axis 1 ofbvh.joint_angles.edges,euler_orders, and augmentation functions use it.
Most functions use the joint_angles index space. The docstring of each function specifies which space it expects.
A parameter that selects a node takes the node's name or the node itself, one of bvh.nodes. It never takes an integer, because an integer does not say which index space it counts in. Node i is bvh.nodes[i]. A name must match exactly one node of the space that the function uses. When several nodes share a name, pass the node that you mean. To find a node's index in an array that you hold, call bvh.index(node, space="node") or bvh.index(node, space="joint"). Functions that take arrays, not a clip, such as transforms.mirror_angles and the functions of geometry, take integer indices into those arrays: there, the array sets the index space.
Centered modes¶
Several functions accept a centered parameter:
"world"— positions as stored in the BVH file"first_ground"— ground-plane centering. pybvh subtracts the first frame's body anchor position in the two horizontal axes only. Theworld_upcoordinate stays as it is. So the motion starts above the origin at its original height."anchor"— the body anchor forced to(0, 0, 0)every frame"anchor_ground"— the travel removed, the height kept. pybvh subtracts each frame's body anchor position in the two horizontal axes only. Theworld_upcoordinate stays as it is. So the body anchor stays above the origin, and a jump shows as the body going up, where under"anchor"it shows as legs that fold up.
The body anchor is the joint that the body's measures start from: the hips on most rigs, and the root on a clip whose root is the hips. Under a reference root that never moves, the three centred modes follow the hips, not the root. See The body anchor.
One look makes the difference obvious. The figure shows the same walking clip and the same frame in three coordinate frames. The blue trail is the root's path over the whole clip:

More one-figure-per-feature visuals: the Gallery.
See also
World Up & Orientation — the up-axis and facing conventions behind centered · Bvh Class API — every attribute and method · Quick Start