Skip to content

Features

features

Feature export for ML pipelines.

Composes the per-frame motion descriptors from :mod:pybvh.analysis (rotations, root position, velocities, foot contacts) into a single flat (F, D) array, plus the column-layout helper that describes it.

feature_array_layout(*, num_joints: int, num_feet: int = 0, num_translating_joints: int | None = None, representation: str = '6d', include_root_pos: bool = True, include_joint_translations: bool = False, include_velocities: bool = False, include_foot_contacts: bool = False) -> dict[str, slice]

Column layout of the array returned by :func:to_feature_array.

Returns a dict mapping block name to column slice so callers can write feat[:, layout['rotations']] without counting columns. Pure function — no :class:~pybvh.bvh.Bvh required; useful for model-shape setup before any data is loaded.

Parameters:

Name Type Description Default
num_joints int

Number of joints (excluding end sites). Used for both the rotation and velocity blocks: velocities are per-joint (not per-node), aligning with the rotation block's joint axis.

required
num_feet int

Number of feet for contact detection. Required (>0) when include_foot_contacts=True.

0
num_translating_joints int

Number of translating joints, P of :attr:Bvh.joint_translations <pybvh.bvh.Bvh.joint_translations>. Required when include_joint_translations=True, unused otherwise; with 0 the block is empty.

None
representation str

Rotation representation: 'euler', 'axisangle' (3 values per joint), 'quat' (4), '6d' (6, default), 'rotmat' (9).

'6d'
include_root_pos bool

Mirror the flags of :func:to_feature_array.

True
include_joint_translations bool

Mirror the flags of :func:to_feature_array.

True
include_velocities bool

Mirror the flags of :func:to_feature_array.

True
include_foot_contacts bool

Mirror the flags of :func:to_feature_array.

True

Returns:

Type Description
dict

{block_name: slice} with keys drawn from {"root_pos", "joint_translations", "rotations", "velocities", "foot_contacts"} depending on the flags, in that column order.

Notes

Within the rotations and velocities blocks joints are in skeleton hierarchy order — the file's declaration order, i.e. Bvh.joint_names, end sites excluded — not alphabetical. For representation='euler' the three columns per joint follow that joint's own channel order from the file (which can differ per joint and between files), not a fixed XYZ; every other representation is order-independent. 'rotmat' flattens each 3×3 row-major (C order).

Raises:

Type Description
ValueError

If representation is unknown, if include_foot_contacts=True but num_feet == 0, or if include_joint_translations=True but num_translating_joints is None.

to_feature_array(bvh: Bvh, representation: str = '6d', include_root_pos: bool = True, include_velocities: bool = False, include_foot_contacts: bool = False, centered: str = 'world', feet: Sequence[NodeSelector] | None = None, stencil: str = 'central', pad: str = 'edge', include_joint_translations: bool = False) -> npt.NDArray[np.float64]

Export motion as a single flat feature array for ML pipelines.

Composes root position, joint translations, joint rotations, velocities, and foot contacts into a single (F, D) array ready for model input.

Parameters:

Name Type Description Default
bvh Bvh

Input motion.

required
representation str

Rotation representation: 'euler', '6d' (default), 'quat', 'axisangle', or 'rotmat' (9 values per joint as a flattened 3×3). 'quat' inherits the per-frame canonical form (w >= 0) of :meth:Bvh.to_quat, which is not temporally continuous — a joint passing through 180° flips sign between frames. Apply :func:pybvh.rotations.quat_unwrap to the array yourself if your model is sensitive to that; '6d' (the default) has no such discontinuity, which is the representation's whole point.

'6d'
include_root_pos bool

If True (default), include root position (3 columns): the root's row of :meth:Bvh.node_positions <pybvh.bvh.Bvh.node_positions> under centered, so centred on :attr:~pybvh.bvh.Bvh.body_anchor. On a clip whose anchor is its root it is zero under "anchor". With the rotations (and include_joint_translations=True on a rig with translating joints), the block gives back node_positions(centered) by forward kinematics (:func:~pybvh.spatial_coord.frames_to_node_positions). On a clip whose root lies above the body, the block is the root's position relative to the anchor: under "anchor" it is not zero, and under "first_ground" and "anchor_ground" it is the root's centred row, not the anchor's. For the body's travel, use include_joint_translations=True or :func:~pybvh.analysis.root_trajectory.

True
include_velocities bool

If True, include joint velocity features, in units per frame — deliberately not :func:joint_velocities' own units-per-second default, because a feature array is consumed per-frame by a model and a per-frame delta keeps the block on the same time base as the rest of the array. Multiply by 1 / bvh.frame_time to recover units/second, and note the two disagree by exactly that factor if you cross-check this block against a direct joint_velocities(bvh) call.

False
include_foot_contacts bool

If True, include foot contact labels. Contacts are always detected in world frame (see :func:pybvh.analysis.foot_contacts), whatever centered says.

False
centered str

Coordinate centering mode (default "world"), as :meth:Bvh.node_positions <pybvh.bvh.Bvh.node_positions> reads it.

'world'
feet sequence of str or BvhNode, or None

The feet for contact detection, each a node name or one of bvh.nodes (see :data:~pybvh.NodeSelector), resolved as :func:pybvh.analysis.foot_contacts resolves its feet; the nodes :func:pybvh.analysis.auto_detect_feet returns if None. Only used when include_foot_contacts=True.

None
stencil optional

Only affect output when include_velocities=True. Same semantics as :func:joint_velocities. The root-position, rotation, and foot-contact blocks are trimmed in time so all blocks align with the velocity shape: pad="none" drops one frame from each end for stencil="central", and the last frame for stencil="forward" (a forward difference labels frame i, so the final frame has no velocity).

'central'
pad optional

Only affect output when include_velocities=True. Same semantics as :func:joint_velocities. The root-position, rotation, and foot-contact blocks are trimmed in time so all blocks align with the velocity shape: pad="none" drops one frame from each end for stencil="central", and the last frame for stencil="forward" (a forward difference labels frame i, so the final frame has no velocity).

'central'
include_joint_translations bool

If True, include :attr:Bvh.joint_translations <pybvh.bvh.Bvh.joint_translations> flattened per frame (3 * P columns, after the root position): per translating joint, in node order, its X Y Z position relative to its parent, the file's values. centered does not apply to them. A clip with no translating joint (P = 0) gets an empty block. Default False: the array is then the same whether or not the clip has translating joints.

False

Returns:

Type Description
ndarray, shape (F, D), (F-1, D), or (F-2, D)

See :func:feature_array_layout for the column layout. Leading dimension depends on include_velocities and the stencil × pad combination.

Raises:

Type Description
ValueError

If representation or centered is unknown, or stencil / pad is invalid; if the clip's motion arrays disagree on frame count (the setters do not check it). With include_foot_contacts=True, also where :func:pybvh.analysis.foot_contacts raises it for feet.

TypeError

With include_foot_contacts=True, where :func:pybvh.analysis.foot_contacts raises it for feet: a bare str or BvhNode in place of a sequence of them, or an entry that is neither.