Tutorials¶

Interactive Jupyter notebooks with detailed walkthroughs, progressing from basics to advanced workflows.

Available tutorials¶

Introduction to pybvh — the BVH file format, reading/writing, the Bvh object, basic inspection
Spatial coordinates and skeleton operations — forward kinematics, centering modes, skeleton operations (retarget, scale, extract_joints)
Rotations — Euler angles, rotation matrices, quaternions, 6D representation, axis-angle, Euler order changes, gimbal lock and discontinuity illustrations
Visualization with bvhplot — static snapshots, video export, interactive playback, side-by-side comparison, camera control, follow=True tracking, backend options
Transforms and augmentation — mirror, rotate_vertical, translate_root, add_noise, perturb_speed, drop_frames, composing transforms, reproducibility
Motion features and analysis — joint velocities and accelerations, angular velocities, root-relative positions, root trajectory, foot contacts, to_feature_array()
Batch processing — read_bvh_directory, batch_to_numpy, normalization stats, save/load pattern

A reader who finishes all seven has a solid working understanding of BVH data and the complete pybvh API.

Running locally¶

pip install "pybvh[pandas]" jupyter
cd tutorials/
jupyter notebook

Editing the tutorials (for contributors)¶

Each tutorial is a Jupytext-paired pair: a .ipynb file (the canonical rendered artifact, with outputs and plots) and a .py file in the Percent format (the plain-text source, git-friendly, reviewable as Python).

Both files are committed. Every cell — code, markdown, and cell-level tags like skip-execution or slow-on-pr — is mirrored in both files.

How to edit¶

Install the dev extras (includes jupytext and nbmake):

pip install -e ".[dev,all-viz,pandas]"

Then edit either side:

In Jupyter Lab — edit the .ipynb as usual. On save, Jupytext rewrites the paired .py automatically.
In VS Code — open the .py; the Jupyter extension recognizes Percent-format cells and lets you run them with output inline. Save syncs back to the .ipynb.
In any text editor — edit the .py, then run:
```
jupytext --sync tutorials/*.ipynb
```
Jupytext picks the newer file by mtime and updates the other side. Outputs on unchanged cells are preserved; outputs on modified cells are cleared (re-run the notebook to regenerate).

Cell-level execution control on CI¶

The tutorial CI (.github/workflows/tutorials.yml) executes every tutorial under nbmake with two tag conventions:

skip-execution — cell is always skipped (used for interactive bvh.play() calls that open a window or widget).
slow-on-pr — cell is skipped on pull-request builds, executed on pushes to main / dev and on manual dispatch. Used for bvh.render(...) calls that produce videos.

Add a tag in the .py by writing it into the cell header:

# %% tags=["slow-on-pr"]
bvh.render("demo.mp4")

Then jupytext --sync propagates the tag into the .ipynb metadata.

Keeping the pair in sync¶

If you ever suspect the two files have drifted, run:

jupytext --sync tutorials/*.ipynb

This is also safe to run as a pre-commit step. A future commit may add a pre-commit hook to enforce sync automatically.