Skip to content

pybvh-ml

ML bridge layer for pybvh — turn motion capture data into training-ready inputs for skeleton-based ML models.

pybvh-ml is the layer between pybvh (which parses BVH files and does rotation math) and your model (which consumes tensors). It handles the data plumbing — tensor layout, augmentation, preprocessing, dataset construction — without making assumptions about your model or task. All core functions use NumPy; PyTorch is optional.

  • Quick Start — BVH directory to training batch in five minutes
  • Gallery — layouts, masks, graphs, reproducibility: every pybvh-ml-specific concept, one picture and one call each
  • Find a function — "I want to…" → the exact call → its reference page
  • User Guide — layouts, preprocessing, augmentation, PyTorch, skeleton graphs
  • CHANGELOG — the migration record: breaking changes and upgrade notes for every release
  • Tutorials — three notebooks from first preprocess to a trained classifier
  • Install — pip install pybvh-ml; optional torch and hdf5 extras

What can pybvh-ml do?

  • Tensor packing to (C, T, V), (T, V, C), and flat (T, D) layouts with round-trip unpacking, and a streams= that picks what goes in — pack_to_ctv(arrays, streams=("joint_pos",)) is the (3, T, J) ST-GCN input
  • Rotations and positions together — one clip carries joint_rot, joint_pos and node_pos (end sites included), with the frame convention recorded alongside them, plus derived velocity and acceleration streams differenced at the one point in the pipeline where they come out right
  • Array-level augmentation in quaternion, 6D, axis-angle, rotmat, and Euler — keyword-only, no Bvh round-trip, with composable pipelines and reproducible per-epoch seeding. Every step transforms every stream it is given, or refuses the sample
  • Preprocessing pipelines — BVH directory → on-disk dataset (.npz / .hdf5) with skeleton-aware harmonization for heterogeneous corpora and dataset-wide z-score normalization
  • Skeleton-graph metadata — edge lists, body-part partitions, L/R pairs in both joint and node space, and the forward-kinematics topology, for GCN and Transformer models
  • Optional PyTorch integration — MotionDataset / OnTheFlyDataset / collate_motion_batch with variable-length padding and worker-safe per-epoch augmentation

It replaces the ~150 lines of preprocessing, augmentation, and dataset-class boilerplate that most BVH-based ML pipelines reinvent. Composable enough to use one piece at a time (just the packer, just the augmentor); opinionated enough to give you a working data loader in a dozen lines.

Quick example

import pybvh_ml

# Preprocess a directory of BVH files into a training-ready .npz.
summary = pybvh_ml.preprocess_directory(
    "walks/", "train.npz", representation="6d",
)

# Load back: per-clip arrays, normalization stats, skeleton metadata.
data = pybvh_ml.load_preprocessed("train.npz")
root_pos = data["clips"][0]["root_pos"]      # (F, 3)
joint_rot = data["clips"][0]["joint_rot"]    # (F, J, 6) for 6D
mean, std = data["mean"], data["std"]        # for input normalization

Foundation library

pybvh-ml depends on pybvh for all BVH parsing, rotation math, and spatial transforms — it never reimplements what pybvh provides. Concepts like world-up detection, rotation representations, and forward kinematics are documented there.

Stability and versioning

pybvh-ml is in 0.x — expect breaking changes between minor versions. We treat 0.x as design space: when a past choice turns out to be wrong, we fix it at the root rather than carry scar tissue forward. Each release has a clear migration path in the CHANGELOG, no deprecation cycles. If you depend on pybvh-ml from production code, pin to an exact version (pybvh-ml==0.6.0) and read the upgrade notes before bumping.

pybvh-ml will commit to strict semver at 1.0: no breaking changes within a major version, deprecation warnings (at least one minor release) before any removal. Until then, "make the library better" wins over "preserve the old behavior."