Skip to content

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 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_index includes end sites. It maps to bvh.nodes. node_positions() uses it.
  • The joint_angles index excludes end sites. It maps to bvh.joint_names and to axis 1 of bvh.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. The world_up coordinate 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. The world_up coordinate 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:

Three of the centered modes on a walking clip: world keeps file coordinates, first_ground starts the path at the origin, anchor pins the body anchor, which is the root on this clip, so the root's trail collapses to a point

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