pybvh-ml

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

Status: pre-1.0. Minor versions can include breaking API changes; see CHANGELOG.md for migration notes.

Documentation · Quick Start · Gallery — every concept, one picture each · Find a function · User Guide · Tutorials

Features

• 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 joint_vel / joint_acc 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.

Philosophy

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.

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.

Installation

pip install pybvh-ml

This pulls in pybvh >= 0.8.2, < 0.9 automatically — pybvh-ml 0.6 tracks pybvh 0.8's API (short representation tokens, radians-first parameters, array-signature forward kinematics).

With optional dependencies:

pip install "pybvh-ml[torch]"    # PyTorch Dataset classes
pip install "pybvh-ml[hdf5]"     # HDF5 output support

Quick Start

import pybvh_ml

# Preprocess a directory of BVH files into a training-ready .npz.
summary = pybvh_ml.preprocess_directory(
    "walks/", "train.npz", representation="6d",
)
print(f"{summary['num_clips']} clips, "
      f"{summary['skeleton_info']['num_joints']} joints")

# 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

# One clip travels as a MotionArrays — what every augmentation and packer takes.
arrays = pybvh_ml.MotionArrays(root_pos=root_pos, joint_rot=joint_rot)
tensor = pybvh_ml.pack_to_ctv(arrays)        # (C, T, V) for a GCN

From there: runtime augmentation in your data loader, PyTorch Datasets with worker-safe per-epoch seeding, and skeleton graph metadata for GCNs — the documentation covers each piece.

Tutorials

Runnable end-to-end notebooks in tutorials/:

1. End-to-end pipeline — BVH directory → preprocess → MotionDataset with augmentation → tiny MLP classifier.
2. Augmentation visualized — every augmentation before/after on a real skeleton, plus set_epoch reproducibility.
3. Heterogeneous preprocessing — mixing skeletons, frame rates, and up-axes robustly.

Notebooks execute in CI via pytest --nbmake tutorials/, so they can't silently rot.

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. No deprecation cycles, no compatibility shims; each release ships a single clean migration path, documented in the CHANGELOG. 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.

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

Requirements

• Python >= 3.9
• pybvh >= 0.8.2, < 0.9
• NumPy >= 1.21

Optional: PyTorch >= 2.0 (pip install "pybvh-ml[torch]"), h5py >= 3.0 (pip install "pybvh-ml[hdf5]").

Development

pip install "pybvh-ml[dev]"
pytest tests/                             # unit tests
pytest --nbmake tutorials/                # tutorial notebook execution
mkdocs serve                              # docs preview (pip install "pybvh-ml[docs]")

License

MIT