Skip to main content

pybvh-ml

PyPI version Python Tests Docs License: MIT

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

Metadata

Release files for pybvh-ml 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pybvh-ml 0.6.0
File Size Uploaded Provenance Actions
pybvh_ml-0.6.0.tar.gz 110.9 kB With provenance Details for pybvh_ml-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pybvh-ml 0.6.0
File Interpreter ABI Platform Actions
pybvh_ml-0.6.0-py3-none-any.whl Python 3 none any Details for pybvh_ml-0.6.0-py3-none-any.whl

Total release size: 227.6 kB

Release files / pybvh_ml-0.6.0.tar.gz

Download URL pybvh_ml-0.6.0.tar.gz
Size 110.9 kB
Tags Source
SHA-256 checksum
How to use checksums
c3d3b724dad11cf2c5b8afd101170ae06167434323223ce36e7dada8058115b3
BLAKE2b-256 checksum
How to use checksums
db02951b51042c78b62ec30956d04ec20d374c324cbf89a20beaf6921e2ab369
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.

Transparency log

Release files / pybvh_ml-0.6.0-py3-none-any.whl

Download URL pybvh_ml-0.6.0-py3-none-any.whl
Size 116.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
aa884013364ba33438da261335c097774832ee5f4f84a4eb2202a26963e0db81
BLAKE2b-256 checksum
How to use checksums
205bfd316aaa1073a0980162061ea014f376a75b0fc53bbf36078da07e270d83
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.

Transparency log

Security for pybvh-ml 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pybvh_ml-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page