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 astreams=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_posandnode_pos(end sites included), with the frame convention recorded alongside them, plus derivedjoint_vel/joint_accstreams 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
Bvhround-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_batchwith 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/:
- End-to-end pipeline — BVH directory → preprocess →
MotionDatasetwith augmentation → tiny MLP classifier. - Augmentation visualized — every augmentation before/after on a real skeleton, plus
set_epochreproducibility. - 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.