Skip to content

Motion Descriptors

pybvh computes a layer of theory-neutral motion descriptors. They are geometric and dynamic properties, measured directly from the motion. They are properties of the data, not of any particular consumer. A biomechanics researcher, a game developer, and an ML engineer all read the same curvature, smoothness, and gait numbers. Everything is pure NumPy in and out, so it composes with any framework.

Every descriptor on this page is drawn in the Feature Gallery, with one figure and one call each. If you want the visual overview before the prose, skim the gallery first.

The descriptors are in four modules. The modules mirror the two halves of the BVH data model (rotations and positions), plus their dynamics and the shared signal layer:

Module Owns Examples
pybvh.geometry positions in R³ curvature, bounding_box, center_of_mass, inter_joint_distance
pybvh.analysis motion dynamics node_jerk, smoothness, kinetic_energy, cadence
pybvh.rotations orientation & rigid transforms se3_exp/se3_log, screw_interpolate, rotation_geodesic_distance
pybvh.signal array-pure signal utilities finite_difference, box_filter_smooth, fft_magnitude, temporal_stats

Geometry — what the body traces out

pybvh.geometry measures points and trajectories:

  • How far a joint travels (path_length), and how directly (directness).
  • How sharply its path turns (curvature), and how sharply it twists out of plane (torsion).
  • The size and shape of the whole pose (bounding_box, bounding_sphere, bounding_ellipsoid, verticality).
  • The pose's centre of mass (center_of_mass, com_displacement).
  • Relations between joints (inter_joint_distance, joint_angle, triangle_area).

Derivative-based kernels share pybvh's one finite-difference convention with the velocity ladder (signal.finite_difference). So geometry and kinematics derivatives stay consistent when you combine them.

Analysis — how the body moves

pybvh.analysis adds dynamics on top of the kinematics it already owned:

  • node_jerk/joint_jerk: the third rung of the velocity → acceleration ladder.
  • node_speed_derivative/joint_speed_derivative: the ladder's tangential rung. It is the per-frame d‖v‖/dt. It is positive while a joint speeds up. It is negative while the joint brakes. It is distinct from node_accelerations, whose norm also counts direction changes.
  • Smoothness of a speed profile, via SPARC, dimensionless jerk, log dimensionless jerk, number of peaks, and a smoothness(metric=…) dispatcher. Every speed-profile kernel also reduces a (T, K) stack of profiles per column.
  • kinetic_energy.
  • Gait: cadence, stride_length, walking_pace.
  • Peak-to-peak range_of_motion.
  • Covariance descriptors: cov3dj, lagged_covariance.

SE(3) — rigid-transform features

pybvh.rotations handles rigid transforms alongside its rotation conversions:

  • The exp/log maps between 4×4 transforms and se(3) twists [ω, v] (se3_exp/se3_log).
  • Screw-motion interpolation, the SE(3) analogue of SLERP.
  • The segment-to-segment relative_transform bridge.
  • rotation_geodesic_distance.

These are the building blocks for Lie-group skeletal features.

Array-pure kernels vs Bvh methods

There are two layers, by design:

  • Array-pure kernels take plain NumPy arrays and return arrays. They are all of pybvh.geometry, the smoothness functions, the covariance descriptors, and the SE(3) math. A downstream library can call them with no Bvh at all.
  • Bvh methods wrap the primitives that are either skeleton-bound or common single-joint queries. A skeleton-bound primitive needs world_up, frame_time, or foot detection. Examples: bvh.curvature("RightHand"), bvh.bounding_box(), bvh.smoothness(node), bvh.cadence().

    Relational and trajectory methods select in node space, so end sites (fingertips, toe tips, head top) are first-class. range_of_motion selects in joint space, because rotations exist only on joints, so it refuses an end site.

    A node is selected by its name or by the BvhNode itself, one of bvh.nodes. A name must match exactly one node of the space: a name that two nodes share raises ValueError, and the node itself selects either of them. Integer indices raise TypeError, because they do not say which index space they count in: node i is bvh.nodes[i]. For index-based access, resolve with bvh.index(node, space=...), and use the array-pure kernels.

    Every descriptor method reads the node positions that the clip computes by forward kinematics and keeps. It takes no positions from the caller. For positions that you hold yourself, for example smoothed, predicted or edited ones, find the node's row with bvh.index(node, space="node"), then call the array-pure kernel on your array.

Name-based primitives assume one consistent skeleton

Descriptors addressed by node name (inter_joint_distance(pairs), foot and centre-of-mass detection) assume every clip shares the same skeleton. Reconciling differing skeletons across a dataset is a harmonization concern (pybvh.batch.harmonize; pybvh.analysis.relative_scale_factor for size), not a descriptor concern.

See also