I/O

io

BVH file I/O — reading and writing .bvh motion capture files.

Public functions:

• :func:read_bvh_file — parse a .bvh file into a :class:~pybvh.bvh.Bvh
• :func:write_bvh_file — write a :class:~pybvh.bvh.Bvh to a .bvh file

read_bvh_file(filepath: str | Path, world_up: str = 'auto', warn_on_world_up_disagreement: bool = True, lr_mapping: dict[str, str] | None = None) -> Bvh

Parse a BVH motion capture file and return a Bvh object.

Parameters:

Name	Type	Description	Default
filepath	str or Path	Path to the BVH file.	required
world_up	str	World vertical axis. "auto" (default) auto-detects from animation data. Pass a signed axis string like "+y" to skip auto-detection and suppress the disagreement warning.	'auto'
warn_on_world_up_disagreement	bool	If True (default) and world_up="auto", emit a UserWarning when rest-pose and first-frame inferences disagree.	True
lr_mapping	dict or None	Explicit left/right joint pair mapping ({"arm.L": "arm.R", ...}). If provided, skips the name-based auto-detection for this file. Use for skeletons whose naming conventions the heuristic can't parse.	None

Returns:

Name	Type	Description
bvh	Bvh	A Bvh object containing the skeleton hierarchy, root positions, joint angles, and frame time.

Notes

BVH files store joint angles in degrees; pybvh holds them in radians on :attr:Bvh.joint_angles. This function converts on read; :func:write_bvh_file converts back on write. Round-trip is lossless within float precision.

write_bvh_file(bvh: Bvh, filepath: str | Path, verbose: bool = False) -> None

Write a Bvh object to a .bvh file.

Parameters:

Name	Type	Description	Default
bvh	Bvh	The motion data to write.	required
filepath	str or Path	Destination file path. Must have a .bvh extension.	required
verbose	bool	If True, print a one-line confirmation to stdout on success. Default False — preprocessing loops that write many files shouldn't flood the terminal by default.	False

Raises:

Type	Description
Exception	If the file extension is not .bvh or the parent directory does not exist.

Notes

pybvh stores joint angles in radians, but the BVH format requires degrees; this function converts on write.