Skip to content

Batch Processing

batch

Batch file loading and numpy export utilities for BVH datasets.

HarmonizeReport(kept_indices: list[int] = list(), kept_sources: list[str | None] = list(), dropped_indices: list[int] = list(), dropped_sources: list[str | None] = list(), drop_reasons: list[str] = list(), applied_stages: list[dict[str, str]] = list()) dataclass

Per-call summary of what :func:harmonize did to each clip.

All fields use JSON-native types so the report can be serialized directly with json.dumps(dataclasses.asdict(report)) and embedded as audit metadata alongside a preprocessed dataset.

Attributes:

Name Type Description
kept_indices list of int

Indices (into the input clips list) of clips that survived the topology gate.

kept_sources list of str or None

source_path of each kept clip, aligned with kept_indices.

dropped_indices list of int

Indices of clips that were dropped by the topology gate.

dropped_sources list of str or None

source_path of each dropped clip, aligned with dropped_indices.

drop_reasons list of str

One human-readable reason per dropped clip, aligned with dropped_indices.

applied_stages list of dict

One dict per kept clip, aligned with kept_indices. Each dict records which harmonization stages ran for that clip, with before→after where meaningful. Possible keys: "retarget", "resample", "world_up", "rest_up", "rest_forward", "euler_order". Empty dict means the clip passed the gate without needing any transformation. "resample" records an interpolation only: a clip that already has target_fps's rate and only takes its exact frame time has no "resample" key.

read_bvh_directory(dirpath: str | Path, pattern: str = '*.bvh', sort: bool | str = True, parallel: bool = False, max_workers: int | None = None, world_up: str = 'auto', warn_on_world_up_disagreement: bool = True, lr_mapping: dict[str, str] | None = None, skip_errors: bool = False, body_anchor: str | None = None) -> list[Bvh]

Load all BVH files from a directory.

Parameters:

Name Type Description Default
dirpath str or Path

Directory to search for BVH files.

required
pattern str

Glob pattern to filter files (default "*.bvh").

'*.bvh'
sort bool or {'lexicographic', 'natural'}

File ordering. True (default) and "lexicographic" sort by full path string — the same order Python's sorted() over paths produces, so a list built elsewhere with sorted() (labels, split manifests) stays index-aligned; note it puts file10.bvh before file2.bvh. "natural" compares embedded digit runs numerically (file2 before file10, case-insensitive) — opt-in, because silently diverging from the ecosystem's lexicographic default would misalign such parallel lists. False keeps the filesystem's glob order (non-deterministic across platforms).

True
parallel bool

If True, read and parse the files in parallel using threads. Parsing is CPU-bound and GIL-limited, so this mainly helps on slow storage (network filesystems, cold disks); expect little speedup on a warm local disk. Each clip is then built on the calling thread, so its warnings (such as the world-up disagreement) name the line that called this function, as they do without parallel.

False
max_workers int or None

Maximum number of threads when parallel=True. None defers to the ThreadPoolExecutor default.

None
world_up str

World vertical axis applied to every loaded file. "auto" (default) auto-detects per file. Pass e.g. "+y" to override all files uniformly.

'auto'
warn_on_world_up_disagreement bool

Passed to :func:read_bvh_file for every file: False silences the rest-pose / first-frame disagreement warning on each clip, for its lifetime (see there).

True
lr_mapping dict or None

Explicit left/right joint pair mapping applied to every loaded file. Useful when a whole dataset shares an unusual naming convention the auto-detect heuristic can't parse.

None
skip_errors bool

If True, files that fail to load emit a UserWarning and are skipped. If False (default), the first failure propagates as the original exception. Use True when robustness against occasional corrupt files matters more than strict verification.

False
body_anchor str or None

The name of the joint the body's measures start from, set on every loaded file (see :func:read_bvh_file). A file that has no joint of that name, or more than one, fails to load, as skip_errors says.

None

Returns:

Type Description
list of Bvh

One Bvh object per successfully loaded file. Shorter than the set of matched files when skip_errors=True and some failed.

Raises:

Type Description
FileNotFoundError

If dirpath does not exist.

harmonize(clips: list[Bvh], *, reference: Bvh | None = None, target_fps: float | None = None, target_world_up: str | None = None, target_rest_up: str | None = None, target_rest_forward: str | None = None, target_euler_order: str | None = None, on_incompatible: Literal['drop', 'raise'] = 'drop', verbose: bool = True, return_report: bool = False) -> list[Bvh] | tuple[list[Bvh], HarmonizeReport]

Apply dataset-level harmonization to a list of clips.

For each clip, applies in order:

  1. Topology check vs reference (if provided). On mismatch, the clip is dropped or raises per on_incompatible.
  2. Bone-proportion retargeting to reference (if provided).
  3. Frame-rate resampling to target_fps (if provided and the clip does not already have that rate by :meth:Bvh.matches_rate's rule). A clip that has it is not interpolated; it takes the frame time 1 / target_fps exactly.
  4. World-up reorientation to target_world_up (if provided and bvh.world_up != target_world_up). Rotates the entire scene — affects offsets, root_pos, and the world_up flag.
  5. Rest-up reorientation to target_rest_up (if provided and bvh.rest_up != target_rest_up). Rotates only the rest-pose offsets and compensates joint rotations so FK positions are unchanged; the world frame is untouched.
  6. Rest-forward reorientation to target_rest_forward (if provided and bvh.rest_forward != target_rest_forward). Rotates rest-pose offsets around the vertical axis so the skeleton's rest-pose facing matches.
  7. Euler-order re-expression to target_euler_order (if provided and any per-joint Euler order differs). Re-expresses each joint's stored Euler angles in the target order while preserving the underlying rotations.

The ordering matters: world-up is "heaviest" (touches everything), rest-up modifies only rest-pose offsets (leaving world frame intact), and rest-forward is a further rotation of those same offsets about rest up, which is the target one by then. Euler-order re-expression runs last because it only rewrites channel layout, not geometry.

Any of the reference / target_* kwargs may be None to skip that stage. Passing all as None returns a shallow copy of clips (no-op).

Parameters:

Name Type Description Default
clips list of Bvh

Input clips.

required
reference Bvh or None

If provided, every clip must match reference.matches_hierarchy (same joints, same parent structure — rest offsets are allowed to differ since retargeting will overwrite them next). Kept clips are then retargeted to reference's bone offsets.

None
target_fps float or None

Target frame rate in Hz. Clips without this rate by :meth:Bvh.matches_rate's rule are resampled via quaternion SLERP. The others keep their samples. Every kept clip leaves with the frame time 1 / target_fps, the one bvh.fps = target_fps sets, so the results join.

None
target_world_up str or None

Signed-axis string ('+y', '-z', ...). Clips whose world_up differs are rotated via reorient_world_up.

None
target_rest_up str or None

Signed-axis string. Clips whose rest_up differs are corrected via reorient_rest_up. Typically used to fix files whose rest pose and animation disagree on the up axis.

None
target_rest_forward str or None

Signed-axis string. Clips whose rest_forward differs are rotated via reorient_rest_forward so the rest pose faces a consistent direction across the dataset.

None
target_euler_order str or None

Three-character order like 'XYZ' / 'ZYX'. When set, clips with any joint whose Euler order differs are re-expressed in the target order via :meth:Bvh.change_euler_order. A static root (CHANNELS 0) declares no rotation channel: it keeps none, and its order does not count as a difference. This is orientation-preserving: underlying rotations are unchanged; only the channel layout is rewritten. Numerical drift can occur on gimbal-lock-adjacent rotations — for bit-exact round-trips across the conversion, prefer rotation-invariant representations ('6d' / 'quat') downstream.

None
on_incompatible ('drop', 'raise')

Behavior on topology mismatch with reference. "drop" (default) skips the clip; "raise" raises ValueError at the first mismatch.

"drop"
verbose bool

If True (default), emit a single UserWarning at end of call when one or more clips were dropped, summarizing how many were dropped and identifying the first few. Set to False to silence the summary entirely.

True
return_report bool

If True, return (clips, report) where report is a :class:HarmonizeReport describing every stage applied to every kept clip plus per-clip drop reasons. Default False keeps the return type as a plain list[Bvh].

False

Returns:

Type Description
list of Bvh, or (list of Bvh, HarmonizeReport)

Harmonized clips (and optional report). The list may be shorter than clips if any were dropped.

Raises:

Type Description
ValueError

If on_incompatible is not one of the accepted values, if on_incompatible='raise' and a clip mismatches reference, if target_fps is not a positive finite number, or if target_fps is given and a clip's frame_time is 0 (unset).

batch_to_numpy(bvh_list: list[Bvh], representation: str = 'euler', include_root_pos: bool = True, pad: bool = False, pad_value: float = 0.0, include_joint_translations: bool = False) -> npt.NDArray[np.float64] | list[npt.NDArray[np.float64]]

Convert a list of Bvh objects to NumPy arrays.

All Bvh objects must share the same skeleton hierarchy. For representations whose channel layout depends on the source Euler order ('euler', 'axisangle'), all clips must additionally share the same per-joint Euler orders. For rotation-invariant representations ('6d', 'quat', 'rotmat') the Euler-order check is skipped. With include_joint_translations=True all clips must also have the same translating joints, whatever the representation; with it off, which joints translate is not checked, because no column depends on it. The roots' position channels are never compared: a static root (CHANNELS 0) has the columns of a root with position channels.

Parameters:

Name Type Description Default
bvh_list list of Bvh

BVH objects to convert.

required
representation str

Rotation representation: 'euler' (default), '6d', 'quat', 'axisangle', or 'rotmat'.

'euler'
include_root_pos bool

If True (default), prepend root position (3 columns) to the rotation data.

True
pad bool

If True, zero-pad shorter sequences to the maximum length and return a single 3-D array (B, F_max, D). If False (default), return a list of 2-D arrays.

False
pad_value float

Value to use for padding (default 0.0).

0.0
include_joint_translations bool

If True, add the block of joint translations after the root position, as :func:~pybvh.features.to_feature_array does. Default False.

False

Returns:

Type Description
ndarray or list of ndarray

If pad=True: array of shape (B, F_max, D). If pad=False: list of arrays, each (F_i, D).

Raises:

Type Description
ValueError

If skeletons are incompatible or representation is unknown.