Skip to content

[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons

Python
58.2 KB
Raw Blame
"""Blender utilities for exporting rigged assets to NPZ motion data.

Format-agnostic helpers shared by the Truebones (FBX), Mixamo (FBX),
Objaverse (GLB/GLTF) and single-asset exporters: scene loading, action
discovery, skeleton/skin extraction, skeleton pruning, Z-up → Y-up
conversion and NPZ/summary writing.

The counterpart for the *animate* direction (NPZ → rigged character) lives
in :mod:`data_process.utils.blender_rig`.
"""

import csv
import os
import re
import json
import numpy as np
import bpy
from math import floor, ceil
from pathlib import Path
from loguru import logger
from Animation import Animation, Quaternions, positions_global
from data_process.utils.plotting import save_skeleton_motion, save_skeleton_tpose
from data_process.utils.export_markers import (  # noqa: F401  (re-exported)
    collect_joint_names_from_markers,
    is_asset_complete,
    mark_asset_complete,
    merge_joint_names,
)


# ─────────────────────────────────────────────────────────────────────────────
# GLTF I/O
# ─────────────────────────────────────────────────────────────────────────────

def import_gltf(path: str):
    bpy.ops.import_scene.gltf(filepath=path)


def import_fbx(path: str):
    bpy.ops.import_scene.fbx(filepath=path, use_anim=True)


# Float noise on an action's frame range (60.0000038 for 60) must not add a
# frame: an end within this of an integer rounds to it.
FRAME_RANGE_EPS = 1e-3


def action_frame_range(action):
    """Return (start, end) integer frame range for an action."""
    fr = action.frame_range
    start = int(floor(fr[0] + FRAME_RANGE_EPS))
    end = int(ceil(fr[1] - FRAME_RANGE_EPS))
    return start, max(start, end)


def find_main_fbx(fbx_dir):
    """Find the single FBX file that contains all actions for the object type.

    Priority:
      1. FBX files without '-': if exactly one, use it; if multiple, pick the one
         with 'all' (case-insensitive) in its name.
      2. If no files without '-', pick the one with '-all' in its name (e.g., Foo-all.fbx).
    """
    fbx_files = [f for f in os.listdir(fbx_dir) if f.lower().endswith('.fbx')]

    # Try files without '-' first
    no_dash = [f for f in fbx_files if '-' not in os.path.splitext(f)[0]]
    if len(no_dash) == 1:
        return os.path.join(fbx_dir, no_dash[0])
    if len(no_dash) > 1:
        with_all = [f for f in no_dash if 'all' in os.path.splitext(f)[0].lower()]
        if len(with_all) >= 1:
            return os.path.join(fbx_dir, with_all[0])

    # Fallback: file with '-all' in name (e.g., Foo-all.fbx)
    dash_all = [f for f in fbx_files if '-all' in os.path.splitext(f)[0].lower()]
    if len(dash_all) >= 1:
        return os.path.join(fbx_dir, dash_all[0])

    return None


EXCLUDED_CSV = "excluded.csv"


def load_excluded_stems(input_dir: Path) -> set:
    """Asset stems listed in ``excluded.csv`` beside (or inside) *input_dir*.

    Assets no importer can read — corrupt rigs, singular transforms, NaN
    axis limits — are recorded there once so every later stage skips them
    instead of failing on them again on each rerun. The CSV carries a
    header with at least ``file`` or ``object_id``; ``stage`` and ``reason``
    are informational.
    """
    stems = set()
    for candidate in (input_dir / EXCLUDED_CSV, input_dir.parent / EXCLUDED_CSV):
        if not candidate.is_file():
            continue
        with open(candidate, newline="") as f:
            for row in csv.DictReader(f):
                stem = (row.get("object_id") or "").strip()
                if not stem:
                    stem = Path((row.get("file") or "").strip()).stem
                if stem:
                    stems.add(stem)
    return stems


def _list_files(input_dir: Path, exts):
    input_dir = Path(input_dir)
    paths = sorted(p for p in input_dir.glob("*") if p.is_file() and p.suffix.lower() in exts)
    excluded = load_excluded_stems(input_dir)
    if not excluded:
        return paths
    kept = [p for p in paths if p.stem not in excluded]
    if len(kept) != len(paths):
        logger.info(f"Skipping {len(paths) - len(kept)} asset(s) listed in {EXCLUDED_CSV}")
    return kept


def list_gltf_files(input_dir: Path):
    """``.glb``/``.gltf`` files directly under *input_dir* (objaverse layout),
    minus the stems listed in ``excluded.csv``."""
    return _list_files(input_dir, {".glb", ".gltf"})


# Formats of the ``general`` dataset (and of any export_general.py input):
# the importer is picked per file by extension.
GENERAL_ASSET_EXTS = frozenset({".glb", ".gltf", ".fbx"})


def list_asset_files(input_dir: Path):
    """``.glb``/``.gltf``/``.fbx`` files directly under *input_dir*, minus the
    stems listed in ``excluded.csv``. The asset list of the ``general``
    dataset: its exporter and renderer must see the same files."""
    return _list_files(input_dir, GENERAL_ASSET_EXTS)


def strip_gltf_action_suffix(armature):
    """Rename the armature's actions back to their glTF animation names.

    Blender's glTF importer names the action of animation ``walk`` on node
    ``Armature`` ``walk_Armature``. A multi-animation GLB (one asset, its
    clips as named animations) would otherwise export ``{asset}-walk_Armature``.
    An action keeps its name when the stripped name is empty or already taken.
    """
    if armature is None:
        return
    suffix = f"_{armature.name}"
    owned = set()
    anim_data = armature.animation_data
    if anim_data is not None:
        if anim_data.action is not None:
            owned.add(anim_data.action)
        owned.update(s.action for t in anim_data.nla_tracks for s in t.strips
                     if s.action is not None)
    for action in sorted(owned, key=lambda a: a.name):
        base = action.name[:-len(suffix)] if action.name.endswith(suffix) else ''
        if base and base not in bpy.data.actions:
            action.name = base


def discover_clip_actions(armature):
    """Pose actions of the loaded scene (:func:`discover_pose_actions`), or,
    when the pose filter finds none, the armature's bound action (single-action
    files such as Mixamo animation-only FBX). The armature's actions are first
    renamed to their glTF animation names (:func:`strip_gltf_action_suffix`).

    The ``general`` exporter and renderer both call this, so they derive the
    same clip names; the objaverse pair has neither the renaming nor the
    fallback.

    Returns:
        ``(action_names, frame_ranges)`` like :func:`discover_pose_actions`.
    """
    strip_gltf_action_suffix(armature)
    action_names, frame_ranges = discover_pose_actions()
    if action_names or armature is None:
        return action_names, frame_ranges
    anim_data = armature.animation_data
    if anim_data is None or anim_data.action is None:
        return action_names, frame_ranges
    action = anim_data.action
    logger.info(f"No pose actions discovered; falling back to bound action '{action.name}'.")
    return [action.name], {action.name: action_frame_range(action)}


def action_is_relevant_pose(action) -> bool:
    """Return True if the action has fcurves that animate pose bones."""
    if action is None or len(action.fcurves) == 0:
        return False
    return any(fc.data_path.startswith("pose.bones[") for fc in action.fcurves)


def discover_pose_actions(min_frames: int = 0, max_frames: int = float('inf')):
    """Find all pose-type actions in the current Blender scene.

    By default no frame-count filter is applied; callers may pass
    *min_frames* / *max_frames* to reject clips outside a desired range.

    Returns:
        (action_names, frame_ranges) where frame_ranges maps action name to
        (start_frame, end_frame) tuples.
    """
    action_names = []
    frame_ranges = {}

    for action_name, action in bpy.data.actions.items():
        if not action_is_relevant_pose(action):
            logger.info(f"Skipping irrelevant action: {action_name}")
            continue

        start, end = action_frame_range(action)
        n_frames = end - start + 1

        if n_frames < min_frames or n_frames > max_frames:
            logger.info(f"Skipping action '{action_name}': {n_frames} frames "
                        f"(valid range: [{min_frames}, {max_frames}])")
            continue

        logger.info(f"Found action: {action_name}, frames=[{start},{end}]")

        if action_name not in frame_ranges:
            action_names.append(action_name)
            frame_ranges[action_name] = (start, end)
        else:
            prev_start, prev_end = frame_ranges[action_name]
            frame_ranges[action_name] = (min(start, prev_start), max(end, prev_end))

    return action_names, frame_ranges


# ─────────────────────────────────────────────────────────────────────────────
# Naming helpers
# ─────────────────────────────────────────────────────────────────────────────

def sanitize_object_type(obj_type):
    """Normalize a Truebones object-type directory name.

    Replaces '-' and whitespace with '_' so compound type names (e.g.
    'Dog-2') don't collide with the object-action separator dash used in
    clip names (e.g. 'Dog_2-Walk').
    """
    return obj_type.replace('-', '_').replace(' ', '_')


def asset_name(path):
    """Object-type name of one asset file: its stem with ``-`` and every
    whitespace character replaced by ``_``.

    Clips are named ``{asset}-{action}`` and every later stage takes the
    object type as the text before the first ``-``, so a stem like
    ``my-robot`` must become ``my_robot``. Objaverse stems (hex ids) and the
    Mixamo character names are unchanged by it.
    """
    return re.sub(r'[-\s]', '_', Path(path).stem)


def asset_names(paths):
    """``{path: asset_name(path)}`` for a list of asset files.

    Raises:
        ValueError: when two files map to the same name (``a-b.glb`` and
            ``a_b.glb``, or ``x.glb`` and ``x.fbx``); they would export and
            render into one object type, the second silently skipped as
            already done.
    """
    names = {}
    by_name = {}
    for p in paths:
        name = asset_name(p)
        by_name.setdefault(name, []).append(Path(p).name)
        names[p] = name
    clashes = {n: files for n, files in by_name.items() if len(files) > 1}
    if clashes:
        detail = '; '.join(f"{n}: {', '.join(files)}" for n, files in sorted(clashes.items()))
        raise ValueError(f"{len(clashes)} asset name(s) are shared by several files "
                         f"(rename them): {detail}")
    return names


def sanitize_action_name(raw_name):
    """Extract a clean action name from Blender action names.

    Strips Blender prefixes (``Armature|``), colon suffixes (``:Base``),
    known domain prefixes (``mixamo.com_``), then replaces all
    non-alphanumeric characters with ``_``.

    Examples:
        'Armature|Walk'                        -> 'Walk'
        'Armature|Run|Run:Base'                -> 'Run'
        'Idle'                                 -> 'Idle'
        'Armature|Big-Mouth Attack'            -> 'Big_Mouth_Attack'
        'mixamo.com_Walk'                      -> 'Walk'
        'Armature|mixamo.com_Run:Base'         -> 'Run'
    """
    parts = raw_name.split('|')
    name = parts[1] if len(parts) > 1 else parts[0]
    name = name.split(':')[0]
    # Remove known domain prefixes
    name = re.sub(r'^mixamo\.com_', '', name)
    # Remove GLTF importer suffixes (e.g. '_GLTF_created_0')
    name = re.sub(r'_GLTF_created_\d+$', '', name)
    # Replace whitespace with '_'
    name = re.sub(r'\s+', '_', name)
    # Replace all non-alphanumeric characters with '_'
    name = re.sub(r'[^a-zA-Z0-9]+', '_', name)
    # Strip leading/trailing underscores
    name = name.strip('_')
    return name


def truebones_clip_name(fbx_stem):
    """Clip name for one curated Truebones per-clip FBX stem.

    The curated layout is ``{Species}-{Action}.fbx`` with the first dash
    separating the two. Export and rendering must derive the same name from
    it or stage 4's exact-match caption lookup silently yields an empty
    caption, so both go through this one helper.

    Raises:
        ValueError: when the stem has no ``-`` to split on.
    """
    species, sep, action = fbx_stem.partition('-')
    if not sep:
        raise ValueError(
            f"Truebones clip filename '{fbx_stem}' has no '-' separating "
            f"species from action; expected '{{Species}}-{{Action}}.fbx'")
    return f"{sanitize_object_type(species)}-{sanitize_action_name(action)}"


def unique_clip_names(action_names):
    """Map each action name to a collision-free sanitized clip suffix.

    ``sanitize_action_name`` keeps only the second ``|``-separated segment,
    so distinct actions routinely collapse onto one name — e.g.
    ``Armature|Take 001|BaseLayer_Obj`` and
    ``Armature|Take 001|BaseLayer.002_Obj`` both yield ``Take_001``. Export
    then overwrites ``motions/{clip}.npz`` (last wins) while the renderer's
    completeness check skips the later actions (first wins), so the NPZ and
    the render under one clip name end up being different animations and the
    caption describes the wrong motion.

    Colliding names get a ``_00``/``_01``… suffix in list order, skipping any
    that another action's name already takes. Callers on
    both sides must pass the SAME ordered action list (the full set of pose
    actions, before any frame-count filtering) or the suffixes diverge.

    Args:
        action_names: Ordered action names, as returned by
            :func:`discover_pose_actions`.

    Returns:
        ``{action_name: clip_suffix}``.
    """
    bases = [sanitize_action_name(n) or "action" for n in action_names]
    total = {}
    for base in bases:
        total[base] = total.get(base, 0) + 1

    # A suffixed name must not land on a name another action already has
    # (``Take_001_00`` from ``Take 001|A`` next to an action named
    # ``Take_001_00``): skip to the next free index.
    used = {base for base in bases if total[base] == 1}
    seen = {}
    mapping = {}
    for action_name, base in zip(action_names, bases):
        if total[base] == 1:
            mapping[action_name] = base
        else:
            idx = seen.get(base, 0)
            while f"{base}_{idx:02d}" in used:
                idx += 1
            seen[base] = idx + 1
            mapping[action_name] = f"{base}_{idx:02d}"
            used.add(mapping[action_name])
    return mapping


# ─────────────────────────────────────────────────────────────────────────────
# Constants (skinning threshold and Blender rigging naming conventions)
# ─────────────────────────────────────────────────────────────────────────────

_SKINNING_WEIGHT_EPS = 1e-5


def _max_weight(skin_matrix, j):
    """Largest weight of bone *j* over the vertices; 0 without a mesh
    (a ``(0, nbones)`` skin matrix)."""
    return float(skin_matrix[:, j].max()) if len(skin_matrix) else 0.0


_CONTROL_PREFIXES = ('MCH-', 'ORG-', 'VIS-')
_CONTROL_SUFFIXES_LOWER = (
    '_ik', '.ik', '_pole', '.pole',
    '_target', '_tip',
    '_ctrl', '.ctrl',
    '_tweak', '_helper',
)


# ─────────────────────────────────────────────────────────────────────────────
# Blender scene utilities
# ─────────────────────────────────────────────────────────────────────────────

def reset_scene():
    bpy.ops.wm.read_factory_settings(use_empty=True)


def set_scene_fps(fps: int):
    bpy.context.scene.render.fps = int(fps)


def find_armatures():
    return [o for o in bpy.data.objects if o.type == "ARMATURE"]


def find_meshes():
    return [o for o in bpy.data.objects if o.type == "MESH"]


def choose_main_armature(armatures):
    """Heuristic: armature with most bones."""
    if not armatures:
        return None
    return sorted(armatures, key=lambda a: len(a.data.bones), reverse=True)[0]


def choose_main_mesh(meshes):
    """Heuristic: mesh with most vertices."""
    if not meshes:
        return None
    return sorted(meshes, key=lambda m: len(m.data.vertices), reverse=True)[0]


def find_skinned_meshes(armature):
    """Meshes deformed by *armature* (an Armature modifier targeting it), in
    scene order. A rig built from one mesh per part (robots) skins each part
    to its own bone, so the main mesh alone leaves most bones unskinned."""
    return [m for m in find_meshes()
            if any(md.type == 'ARMATURE' and md.object == armature for md in m.modifiers)]


# ─────────────────────────────────────────────────────────────────────────────
# Animation state management
# ─────────────────────────────────────────────────────────────────────────────

def clear_animation_state(arm_obj: bpy.types.Object):
    """Clear action and NLA tracks to avoid cross-action contamination."""
    ad = arm_obj.animation_data
    if ad is None:
        return
    ad.action = None
    if ad.nla_tracks:
        for tr in list(ad.nla_tracks):
            ad.nla_tracks.remove(tr)


def bind_action(arm_obj: bpy.types.Object, action: bpy.types.Action):
    if arm_obj.animation_data is None:
        arm_obj.animation_data_create()
    arm_obj.animation_data.action = action


# ─────────────────────────────────────────────────────────────────────────────
# Skinning utilities
# ─────────────────────────────────────────────────────────────────────────────

def build_vgroup_to_bone_mapping(mesh_obj, arm_obj):
    """Return dict {vgroup_index -> bone_name} for groups that match a bone."""
    bone_names = set(arm_obj.data.bones.keys())
    vg_to_bone = {}
    for i, vg in enumerate(mesh_obj.vertex_groups):
        if vg.name in bone_names:
            vg_to_bone[i] = vg.name
    return vg_to_bone


def build_vertex_groups_sparse(mesh_obj, vg_to_bone: dict, bone_name_to_index: dict, dtype=np.float64):
    """
    Returns:
      vert_groups:  len=V list[list[(bone_idx, weight)]]
      skin_matrix:  (V, B) dense skinning weight matrix
    """
    verts       = mesh_obj.data.vertices
    V           = len(verts)
    vert_groups = [[] for _ in range(V)]
    skin_matrix = np.zeros((V, len(bone_name_to_index)), dtype=dtype)

    for i, vert in enumerate(verts):
        groups = []
        for g in vert.groups:
            w = float(g.weight)
            if w <= 0.0:
                continue
            bname = vg_to_bone.get(g.group)
            if bname is None:
                continue
            bidx = bone_name_to_index.get(bname)
            if bidx is None:
                continue
            skin_matrix[i, bidx] = w
            groups.append((int(bidx), w))
        vert_groups[i] = groups

    return vert_groups, skin_matrix


# ─────────────────────────────────────────────────────────────────────────────
# Skeleton topology utilities
# ─────────────────────────────────────────────────────────────────────────────

def children_from_parents(parents):
    ch = [[] for _ in range(len(parents))]
    for j, p in enumerate(parents):
        if p >= 0:
            ch[p].append(j)
    return ch


def name_is_control_bone(name: str) -> bool:
    return (
        any(name.startswith(p) for p in _CONTROL_PREFIXES)
        or any(name.lower().endswith(s) for s in _CONTROL_SUFFIXES_LOWER)
    )


def rotation_amplitude(j, anim):
    """
    Maximum rotation angle (radians) of joint j relative to its first-frame
    orientation, across all frames.
    """
    rot_0    = anim.rotations[0:1, j]
    delta    = (-rot_0) * anim.rotations[:, j]
    cos_half = np.abs(delta.qs[:, 0]).clip(0.0, 1.0)
    return float(np.max(2.0 * np.arccos(cos_half)))


def prune_secondary_roots(armature, name_to_weight_sum):
    def get_subtree_weight(bone, weight_dict):
        w = weight_dict.get(bone.name, 0)
        for child in bone.children:
            w += get_subtree_weight(child, weight_dict)
        return w

    all_roots = [bone for bone in armature.data.bones if bone.parent is None]
    if len(all_roots) <= 1:
        logger.info("Only one or no root bone found. Skipping prune_secondary_roots.")
        return

    root_weights = []
    for rb in all_roots:
        total_w = get_subtree_weight(rb, name_to_weight_sum)
        root_weights.append((rb.name, total_w))
        logger.info(f"Root bone '{rb.name}' has total subtree weight: {total_w:.4f}")

    best_root_name = max(root_weights, key=lambda x: x[1])[0]
    logger.info(f"Keeping best root: '{best_root_name}'")

    bones_to_remove = []
    for rb_name, _ in root_weights:
        if rb_name != best_root_name:
            rb_obj = armature.data.bones.get(rb_name)
            if rb_obj:
                bones_to_remove.extend([rb_obj.name] + [b.name for b in rb_obj.children_recursive])

    if bones_to_remove:
        logger.info(f"Removing {len(bones_to_remove)} bones from secondary root subtrees.")
        bpy.context.view_layer.objects.active = armature
        bpy.ops.object.mode_set(mode='EDIT')
        eb = armature.data.edit_bones
        for b_name in bones_to_remove:
            if b_name in eb:
                eb.remove(eb[b_name])
        bpy.ops.object.mode_set(mode='OBJECT')
        bpy.context.view_layer.update()


def collapse_unused_root(anim: Animation):
    """Remove an unskinned root with a single child; the child becomes the new root.

    Uses direct local-space composition instead of global FK round-trip
    to avoid floating-point drift.
    """
    parents = anim.parents.copy()
    F, J    = anim.positions.shape[:2]
    assert J == len(parents)

    root_ids = np.where(np.array(parents) == -1)[0]
    assert len(root_ids) == 1, "Multiple root joints found."
    root_id = root_ids[0]

    all_children = children_from_parents(parents)
    assert len(all_children[root_id]) == 1, "Root must have exactly one child."
    true_root_id = all_children[root_id][0]

    def get_all_descendants(idx):
        res = [idx]
        for c in all_children[idx]:
            res.extend(get_all_descendants(c))
        return res

    keep      = sorted(get_all_descendants(true_root_id))
    new_index = {old: new for new, old in enumerate(keep)}
    newJ      = len(keep)

    # Build new parent array
    new_parents = np.full((newJ,), -1, dtype=np.int32)
    for old_j in keep:
        if old_j != true_root_id:
            new_parents[new_index[old_j]] = new_index[parents[old_j]]

    # Copy local transforms for all kept bones
    new_rot_qs = anim.rotations.qs[:, keep].copy()
    new_pos    = anim.positions[:, keep].copy()
    new_offsets = anim.offsets[keep].copy()

    # Compose root transform into the new root (former child):
    # new_child_local = old_root_local * old_child_local
    new_root_idx = new_index[true_root_id]
    root_rot = anim.rotations[:, root_id]
    new_rot_qs[:, new_root_idx] = (root_rot * anim.rotations[:, true_root_id]).qs
    new_pos[:, new_root_idx] = (
        anim.positions[:, root_id] + root_rot * anim.positions[:, true_root_id]
    )

    # Compose rest-pose offset
    rest_root_rot = Quaternions(anim.rotations.qs[0:1, root_id])
    new_offsets[new_root_idx] = (
        anim.offsets[root_id] + (rest_root_rot * anim.offsets[true_root_id:true_root_id+1])[0]
    )

    new_anim = Animation(
        rotations=Quaternions(new_rot_qs),
        positions=new_pos,
        orients=anim.orients[keep].copy(),
        offsets=new_offsets,
        parents=new_parents,
    )
    return new_anim, keep


# ─────────────────────────────────────────────────────────────────────────────
# Skeleton pruning
# ─────────────────────────────────────────────────────────────────────────────

# --- Prunable bone detection ------------------------------------------------

def _is_prunable(j, skin_matrix, anims_list, rest_anim, names,
                 offset_eps, pos_var_eps, rot_eps,
                 mean_bone_len=1.0, is_leaf=True,
                 consider_parent_rotate=True, end_effector_suffixes=()):
    """
    Return True if bone j should be removed from the skeleton.
    Works with one or more animation clips for aggregated decisions.

    Conditions (checked in order, first match wins):

      (0) Name convention   — Blender control/mechanism prefix or suffix,
                              except a leaf ending in one of
                              *end_effector_suffixes*, which (4) decides.
      (1) Near-zero offset  — bone head coincident with parent in rest pose.
      (2) Near-zero position— bone stays at parent origin in ALL clips.
      (3) Non-rigid (leaf)  — bone length varies from rest in ANY clip;
                              likely an IK-stretch control.
      (4) Zero rotation DOF — bone never rotates above threshold in ALL clips.
          For leaf bones, when *consider_parent_rotate* is True, only prune
          if the parent also doesn't rotate in ANY clip — a static leaf on a
          rotating parent is a meaningful end-effector (e.g. spider toe tip).
          When False, prune such leaves regardless of parent motion.

    Distance conditions are normalized by mean_bone_len (scale-agnostic).
    """
    # Skinned bones are never prunable
    if _max_weight(skin_matrix, j) >= _SKINNING_WEIGHT_EPS:
        return False

    if name_is_control_bone(names[j]) and not (                           # (0)
            is_leaf and names[j].lower().endswith(tuple(end_effector_suffixes))):
        return True

    norm = max(mean_bone_len, 1e-9)
    rest_pos_j = rest_anim.positions[0, j]

    if np.linalg.norm(rest_pos_j) / norm < offset_eps:                   # (1)
        return True

    if all(np.max(np.linalg.norm(a.positions[:, j], axis=-1)) / norm     # (2)
           < offset_eps for a in anims_list):
        return True

    if is_leaf:                                                           # (3)
        if any(np.max(np.linalg.norm(a.positions[:, j] - rest_pos_j,
                                     axis=-1)) / norm > pos_var_eps
               for a in anims_list):
            return True

    if rot_eps > 0.0 and all(rotation_amplitude(j, a) < rot_eps          # (4)
                             for a in anims_list):
        if is_leaf and consider_parent_rotate:
            parent_j = anims_list[0].parents[j]
            if parent_j >= 0 and any(rotation_amplitude(parent_j, a) >= rot_eps
                                     for a in anims_list):
                return False  # parent rotates → keep this end-effector
        return True

    return False


# --- Bone merge operation ---------------------------------------------------

def _merge_passthrough_bone(anims_list, rest_anim, names, skin_matrix, j):
    """Collapse pass-through bone j into its single child across all clips.

    The child inherits j's transform so that global positions are preserved.
    """
    parents   = list(anims_list[0].parents)
    childrens = children_from_parents(parents)
    c         = childrens[j][0]

    # Compose rest-pose offset: child_new = j_offset + rot_j * child_offset
    new_offsets = anims_list[0].offsets.copy()
    rest_rot_j0 = Quaternions(rest_anim.rotations.qs[0:1, j])
    new_offsets[c] = new_offsets[j] + (rest_rot_j0 * new_offsets[c:c+1])[0]

    # Re-parent child to j's parent, build index mapping
    new_parents    = list(parents)
    new_parents[c] = parents[j]
    keep_idxs      = [i for i in range(len(parents)) if i != j]
    old_to_new     = {old: new for new, old in enumerate(keep_idxs)}
    final_parents  = np.array(
        [old_to_new[new_parents[i]] if new_parents[i] >= 0 else -1
         for i in keep_idxs],
        dtype=np.int32,
    )

    # Update rest anim
    rest_rot_j    = rest_anim.rotations[:, j]
    new_rest_pos  = rest_anim.positions.copy()
    new_rest_rots = rest_anim.rotations.qs.copy()
    new_rest_pos[:, c]  = rest_anim.positions[:, j] + rest_rot_j * rest_anim.positions[:, c]
    new_rest_rots[:, c] = (rest_rot_j * rest_anim.rotations[:, c]).qs
    new_rest_anim = Animation(
        rotations=Quaternions(new_rest_rots[:, keep_idxs]),
        positions=new_rest_pos[:, keep_idxs],
        orients=rest_anim.orients[keep_idxs],
        offsets=new_offsets[keep_idxs],
        parents=final_parents,
    )

    # Update each animation clip
    new_anims = []
    for anim in anims_list:
        rot_j         = anim.rotations[:, j]
        new_anim_pos  = anim.positions.copy()
        new_anim_rots = anim.rotations.qs.copy()
        new_anim_pos[:, c]  = anim.positions[:, j] + rot_j * anim.positions[:, c]
        new_anim_rots[:, c] = (rot_j * anim.rotations[:, c]).qs
        new_anims.append(Animation(
            rotations=Quaternions(new_anim_rots[:, keep_idxs]),
            positions=new_anim_pos[:, keep_idxs],
            orients=anim.orients[keep_idxs],
            offsets=new_offsets[keep_idxs],
            parents=final_parents,
        ))

    new_names = [names[i] for i in keep_idxs]
    new_skin  = skin_matrix[:, keep_idxs]
    return new_anims, new_rest_anim, new_names, new_skin


# --- Helpers ----------------------------------------------------------------

def _compute_mean_bone_len(rest_anim):
    """Mean bone length from rest-pose offsets, excluding root."""
    bone_lens  = np.linalg.norm(rest_anim.offsets[1:], axis=-1)
    valid_lens = bone_lens[bone_lens > 1e-6]
    return float(valid_lens.mean()) if len(valid_lens) > 0 else 1.0


def _find_deepest_in_chain(j, children_map, cand_set):
    """Walk from candidate j down the single-child chain to the deepest candidate."""
    while children_map[j][0] in cand_set:
        j = children_map[j][0]
    return j


def _find_root(parents):
    """Return the index of the root joint (parent == -1)."""
    return int(np.where(np.array(parents) == -1)[0][0])


# --- Pruning passes --------------------------------------------------------

def _pass_prune_leaves(anims_list, rest_anim, names, skin_matrix,
                       offset_eps, pos_var_eps, rot_eps, min_joints,
                       consider_parent_rotate=True, end_effector_suffixes=()):
    """Pass 1: iteratively remove prunable leaf bones."""
    count = 0
    mbl = _compute_mean_bone_len(rest_anim)
    while True:
        n_joints  = len(anims_list[0].parents)
        childrens = children_from_parents(anims_list[0].parents)
        candidates = [j for j in range(n_joints)
                      if len(childrens[j]) == 0
                      and _is_prunable(j, skin_matrix, anims_list, rest_anim, names,
                                       offset_eps, pos_var_eps, rot_eps,
                                       mean_bone_len=mbl, is_leaf=True,
                                       consider_parent_rotate=consider_parent_rotate,
                                       end_effector_suffixes=end_effector_suffixes)]
        if not candidates:
            break
        keep = [j for j in range(n_joints) if j not in set(candidates)]
        if len(keep) < min_joints:
            break
        logger.info(f"Pruning leaf bones: {[names[j] for j in candidates]}")
        anims_list  = [a[:, keep].copy() for a in anims_list]
        rest_anim   = rest_anim[:, keep].copy()
        names       = [names[j] for j in keep]
        skin_matrix = skin_matrix[:, keep]
        count += len(candidates)
    return anims_list, rest_anim, names, skin_matrix, count


def _pass_promote_root(anims_list, rest_anim, names, skin_matrix):
    """Pass 2: collapse unskinned single-child root into its child."""
    count = 0
    while True:
        root_idx = _find_root(anims_list[0].parents)
        children = children_from_parents(anims_list[0].parents)[root_idx]
        if not (len(children) == 1
                and _max_weight(skin_matrix, root_idx) < _SKINNING_WEIGHT_EPS):
            break
        logger.info(f"Promoting root child (removing '{names[root_idx]}')")
        new_anims = []
        keep_idxs = None
        for anim in anims_list:
            new_anim, ki = collapse_unused_root(anim)
            if keep_idxs is None:
                keep_idxs = ki
            else:
                assert ki == keep_idxs, "Root-clean keep_idxs mismatch across clips"
            new_anims.append(new_anim)
        rest_anim, rest_ki = collapse_unused_root(rest_anim)
        assert rest_ki == keep_idxs, "Root-clean keep_idxs mismatch for rest_anim"
        anims_list  = new_anims
        names       = [names[j] for j in keep_idxs]
        skin_matrix = skin_matrix[:, keep_idxs]
        count += 1
    return anims_list, rest_anim, names, skin_matrix, count


def _pass_merge_passthrough(anims_list, rest_anim, names, skin_matrix,
                            offset_eps, pos_var_eps, rot_eps, min_joints):
    """Pass 3: merge prunable single-child (non-root) bones, deepest first."""
    count = 0
    mbl = _compute_mean_bone_len(rest_anim)
    while True:
        n_joints  = len(anims_list[0].parents)
        childrens = children_from_parents(anims_list[0].parents)
        root_idx  = _find_root(anims_list[0].parents)
        candidates = [j for j in range(n_joints)
                      if j != root_idx
                      and len(childrens[j]) == 1
                      and _is_prunable(j, skin_matrix, anims_list, rest_anim, names,
                                       offset_eps, pos_var_eps, rot_eps,
                                       mean_bone_len=mbl, is_leaf=False)]
        if not candidates:
            break
        cand_set = set(candidates)
        j = _find_deepest_in_chain(candidates[0], childrens, cand_set)
        logger.info(f"Merging pass-through bone '{names[j]}' into its child")
        anims_list, rest_anim, names, skin_matrix = \
            _merge_passthrough_bone(anims_list, rest_anim, names, skin_matrix, j)
        count += 1
    return anims_list, rest_anim, names, skin_matrix, count


# --- Main entry points ------------------------------------------------------

def prune_skeleton_shared(anims_list, rest_anim, names, skin_matrix,
                          offset_eps=1e-3, pos_var_eps=1e-3,
                          rot_eps=np.deg2rad(2.0), min_joints=4,
                          consider_parent_rotate=True, end_effector_suffixes=()):
    """Iterative skeleton pruning across multiple animation clips.

    Guarantees identical topology across all clips.  Three passes per
    iteration, repeated until no pass makes progress:

      1. Remove prunable leaf bones
      2. Promote child when root is unskinned with single child
      3. Merge prunable pass-through bones into their children

    Args:
        consider_parent_rotate: If True (default), leaf bones that never
            rotate are preserved when their parent rotates — treating them
            as meaningful end-effectors (e.g. spider toe tips). If False,
            such leaves are pruned regardless of parent motion.
        end_effector_suffixes: Lowercase name suffixes (e.g. ``('_tip',)``)
            that mark a leaf as an end effector rather than a control bone,
            so the name rule does not prune it.
    """
    stats = {"leaf": 0, "root_promoted": 0, "passthrough": 0}

    while len(anims_list[0].parents) > min_joints:
        anims_list, rest_anim, names, skin_matrix, n_leaf = \
            _pass_prune_leaves(anims_list, rest_anim, names, skin_matrix,
                               offset_eps, pos_var_eps, rot_eps, min_joints,
                               consider_parent_rotate=consider_parent_rotate,
                               end_effector_suffixes=end_effector_suffixes)

        anims_list, rest_anim, names, skin_matrix, n_root = \
            _pass_promote_root(anims_list, rest_anim, names, skin_matrix)

        anims_list, rest_anim, names, skin_matrix, n_pass = \
            _pass_merge_passthrough(anims_list, rest_anim, names, skin_matrix,
                                    offset_eps, pos_var_eps, rot_eps, min_joints)

        stats["leaf"]          += n_leaf
        stats["root_promoted"] += n_root
        stats["passthrough"]   += n_pass

        if n_leaf + n_root + n_pass == 0:
            break

    logger.info(f"Pruning summary: {stats}, final joints: {len(anims_list[0].parents)}")
    return anims_list, rest_anim, names, skin_matrix


# ─────────────────────────────────────────────────────────────────────────────
# Motion filtering (T-pose frame removal)
# ─────────────────────────────────────────────────────────────────────────────

def remove_tpose_frames(anim, rest_anim, rot_thresh=np.deg2rad(1.0)):
    """Remove frames whose non-root joint rotations match the rest pose.

    For each frame, computes the maximum rotation angle (over all non-root
    joints) between the frame's local rotation and the rest-pose rotation.
    Frames where this maximum is below *rot_thresh* are considered T-pose
    duplicates and removed.

    Args:
        anim:        Animation with shape (F, J, ...).
        rest_anim:   Single-frame rest-pose Animation (1, J, ...).
        rot_thresh:  Maximum allowed rotation deviation (radians) for a
                     frame to be considered identical to the T-pose.

    Returns:
        (pruned_anim, n_removed)  — the filtered Animation and the count
        of removed frames.  Returns the original if no frames are removed
        or if removing them would leave fewer than 2 frames.
    """
    F, J = anim.rotations.qs.shape[:2]
    if J < 2:
        return anim, 0

    # rest rotation for non-root joints: (1, J-1, 4)
    rest_rot = rest_anim.rotations[:, 1:]            # Quaternions (1, J-1)
    frame_rot = anim.rotations[:, 1:]                # Quaternions (F, J-1)

    # relative rotation: rest^-1 * frame  →  identity when poses match
    delta = (-rest_rot) * frame_rot                  # (F, J-1)
    # angle = 2 * arccos(|w|)
    cos_half = np.abs(delta.qs[..., 0]).clip(0.0, 1.0)   # (F, J-1)
    angles = 2.0 * np.arccos(cos_half)                    # (F, J-1)

    max_angle_per_frame = angles.max(axis=1)               # (F,)
    keep_mask = max_angle_per_frame >= rot_thresh

    n_removed = int((~keep_mask).sum())
    if n_removed == 0:
        return anim, 0

    keep_indices = np.where(keep_mask)[0]
    if len(keep_indices) < 2:
        # Don't strip if it would leave fewer than 2 frames
        return anim, 0

    pruned = Animation(
        rotations=Quaternions(anim.rotations.qs[keep_indices]),
        positions=anim.positions[keep_indices],
        orients=anim.orients.copy(),
        offsets=anim.offsets.copy(),
        parents=anim.parents.copy(),
    )
    return pruned, n_removed


# ─────────────────────────────────────────────────────────────────────────────
# Animation extraction helpers
# ─────────────────────────────────────────────────────────────────────────────

def extract_rest_pose(anim_data_bones, armature, dtype=np.float64, apply_world=True):
    """Extract local rest-pose positions and rotations for all bones."""
    nbones         = len(anim_data_bones)
    rest_local_pos = np.zeros((nbones, 3), dtype=dtype)
    rest_local_rot = np.zeros((nbones, 4), dtype=dtype)

    for idxb, bone in enumerate(anim_data_bones):
        if bone.parent:
            mat = bone.parent.matrix_local.inverted() @ bone.matrix_local
            rest_local_pos[idxb] = np.array(mat.to_translation(), dtype=dtype)
            rest_local_rot[idxb] = np.array(mat.to_quaternion(),  dtype=dtype)
        else:
            if apply_world:
                mat = armature.matrix_world @ bone.matrix_local
                scale = np.array(armature.matrix_world.to_scale(), dtype=dtype)
                rest_local_pos[idxb] = np.array(mat.to_translation(), dtype=dtype) / scale
            else:
                mat = bone.matrix_local
                rest_local_pos[idxb] = np.array(mat.to_translation(), dtype=dtype)
            rest_local_rot[idxb] = np.array(mat.to_quaternion(),  dtype=dtype)

    return rest_local_pos, rest_local_rot


def extract_animation_frames(armature, start_frame, end_frame, nbones, dtype=np.float64, apply_world=True):
    """Scrub through frames and extract per-frame local bone transforms."""
    nframes        = end_frame - start_frame + 1
    anim_local_pos = np.zeros((nframes, nbones, 3), dtype=dtype)
    anim_local_rot = np.zeros((nframes, nbones, 4), dtype=dtype)

    pose_bones = armature.pose.bones
    assert len(pose_bones) > 0, f"No pose bones in armature {armature.name}"

    for idxf, f in enumerate(range(start_frame, end_frame + 1)):
        bpy.context.scene.frame_set(f)  # evaluates the depsgraph

        for idxb, bone in enumerate(pose_bones):
            if bone.parent:
                mat = bone.parent.matrix.inverted() @ bone.matrix
                anim_local_pos[idxf, idxb] = np.array(mat.to_translation(), dtype=dtype)
                anim_local_rot[idxf, idxb] = np.array(mat.to_quaternion(),  dtype=dtype)
            else:
                if apply_world:
                    mat = armature.matrix_world @ bone.matrix
                    scale = np.array(armature.matrix_world.to_scale(), dtype=dtype)
                    anim_local_pos[idxf, idxb] = np.array(mat.to_translation(), dtype=dtype) / scale
                else:
                    mat = bone.matrix
                    anim_local_pos[idxf, idxb] = np.array(mat.to_translation(), dtype=dtype)
                anim_local_rot[idxf, idxb] = np.array(mat.to_quaternion(),  dtype=dtype)

    return anim_local_pos, anim_local_rot


# ─────────────────────────────────────────────────────────────────────────────
# Skeleton setup (Blender scene → numpy arrays)
# ─────────────────────────────────────────────────────────────────────────────

def compute_bone_weight_sums(mesh, armature):
    """Sum skin weights per bone across all vertices of *mesh* (one mesh or a
    list of meshes)."""
    weight_sums = {bname: 0.0 for bname in armature.data.bones.keys()}
    for m in (mesh if isinstance(mesh, (list, tuple)) else [mesh]):
        vg_to_bone = build_vgroup_to_bone_mapping(m, armature)
        for v in m.data.vertices:
            for g in v.groups:
                bname = vg_to_bone.get(g.group)
                if bname:
                    weight_sums[bname] += g.weight
    return weight_sums


def build_skeleton_arrays(armature, mesh, dtype=np.float64, apply_world=True):
    """Extract skeleton topology, rest pose, and skin matrix from Blender objects.

    *mesh* is one mesh, a list of meshes (their skin matrices are stacked,
    rows in list order) or None.

    Returns:
        bone_names, parents_array, rest_local_pos, rest_local_rot, skin_matrix
    """
    bones = armature.data.bones
    bone_names = list(bones.keys())
    bone_name_to_index = {b.name: i for i, b in enumerate(bones)}

    meshes = [] if mesh is None else (list(mesh) if isinstance(mesh, (list, tuple)) else [mesh])
    if not meshes:
        skin_matrix = np.zeros((0, len(bone_names)), dtype=dtype)
    else:
        skin_matrix = np.concatenate([
            build_vertex_groups_sparse(m, build_vgroup_to_bone_mapping(m, armature),
                                       bone_name_to_index)[1]
            for m in meshes], axis=0)

    parents_array = np.array([
        -1 if bone.parent is None else bones.find(bone.parent.name)
        for bone in bones
    ], dtype=np.int32)

    rest_local_pos, rest_local_rot = extract_rest_pose(bones, armature, dtype, apply_world=apply_world)

    return bone_names, parents_array, rest_local_pos, rest_local_rot, skin_matrix


def build_rest_animation(parents_array, rest_local_pos, rest_local_rot, nbones):
    """Build a single-frame Animation object from rest pose arrays."""
    return Animation(
        rotations=Quaternions(rest_local_rot[None]),
        positions=rest_local_pos[None],
        orients=Quaternions.id(nbones),
        offsets=rest_local_pos,
        parents=parents_array,
    )


# ─────────────────────────────────────────────────────────────────────────────
# Coordinate conversion (Z-up → Y-up)
# ─────────────────────────────────────────────────────────────────────────────

def _apply_root_rotation(anim, root_quat):
    """Apply *root_quat* to the root joint of an Animation (rotations, positions, offsets)."""
    rots = anim.rotations.copy()
    pos = anim.positions.copy()
    off = anim.offsets.copy()
    rots[:, 0] = root_quat * anim.rotations[:, 0]
    pos[:, 0] = root_quat * anim.positions[:, 0]
    off[0] = (root_quat * anim.offsets[0:1])[0]
    return Animation(
        rotations=rots, positions=pos,
        orients=anim.orients, offsets=off, parents=anim.parents,
    )


def apply_zup_to_yup(anim, rest_anim):
    """Rotate root bone -90 deg around X to convert Z-up to Y-up coordinate system."""
    root_quat = Quaternions.from_euler(np.array([[-np.pi / 2, 0, 0]]))
    return _apply_root_rotation(anim, root_quat), _apply_root_rotation(rest_anim, root_quat)


# ─────────────────────────────────────────────────────────────────────────────
# High-level pipeline helpers (shared by FBX and GLB exporters)
# ─────────────────────────────────────────────────────────────────────────────

def load_scene(import_fn, path, fps=30):
    """Reset scene, set FPS, import via *import_fn*, select main armature/mesh.

    Returns (armature, mesh). Mesh may be None if none found.
    """
    reset_scene()
    set_scene_fps(fps=fps)
    import_fn(str(path))

    armatures = find_armatures()
    assert len(armatures) > 0, f"No armature found in {path}."
    armature = choose_main_armature(armatures)
    logger.info(f"Using armature: {armature.name}, bones={len(armature.data.bones)}")

    meshes = find_meshes()
    mesh = choose_main_mesh(meshes) if meshes else None
    if mesh is not None:
        logger.info(f"Using mesh: {mesh.name}, vertices={len(mesh.data.vertices)}")

    return armature, mesh


def prepare_skeleton(armature, mesh=None, dtype=np.float64, apply_world=True):
    """Prune secondary roots, build skeleton arrays, and Z→Y rest poses.

    When *mesh* is None (e.g. Mixamo clips without a character mesh), the
    secondary-root prune step is skipped and skin_matrix is returned empty.
    A list of meshes gives the skin weights of all of them
    (:func:`build_skeleton_arrays`).

    Returns a dict with keys: nbones, bone_names, parents_array,
    rest_local_pos, rest_local_rot, skin_matrix, rest_anim, rest_anim_shared.
    """
    if mesh is not None:
        weight_sums = compute_bone_weight_sums(mesh, armature)
        prune_secondary_roots(armature, weight_sums)
        bpy.context.view_layer.update()

    nbones = len(armature.data.bones)
    bone_names, parents_array, rest_local_pos, rest_local_rot, skin_matrix = \
        build_skeleton_arrays(armature, mesh, dtype, apply_world=apply_world)

    rest_anim = build_rest_animation(parents_array, rest_local_pos, rest_local_rot, nbones)
    _, rest_anim_shared = apply_zup_to_yup(rest_anim, rest_anim)

    return {
        'nbones': nbones,
        'bone_names': bone_names,
        'parents_array': parents_array,
        'rest_local_pos': rest_local_pos,
        'rest_local_rot': rest_local_rot,
        'skin_matrix': skin_matrix,
        'rest_anim': rest_anim,
        'rest_anim_shared': rest_anim_shared,
    }


def extract_all_actions(armature, frame_ranges, rest_local_pos, parents_array,
                        rest_anim, nbones, dtype=np.float64, apply_world=True):
    """Extract (name, Animation) for every action in *frame_ranges*.

    Args:
        frame_ranges: dict mapping action_name -> (start_frame, end_frame).

    Applies Z-up → Y-up conversion to each extracted clip.
    """
    extracted = []
    for action_name, (start_frame, end_frame) in frame_ranges.items():
        action = bpy.data.actions.get(action_name)
        if action is None:
            logger.warning(f"Action '{action_name}' not found; skipping.")
            continue

        clear_animation_state(armature)
        bind_action(armature, action)

        anim_local_pos, anim_local_rot = extract_animation_frames(
            armature, start_frame, end_frame, nbones, dtype, apply_world=apply_world
        )

        anim = Animation(
            rotations=Quaternions(anim_local_rot),
            positions=anim_local_pos,
            orients=Quaternions.id(nbones),
            offsets=rest_local_pos,
            parents=parents_array,
        )
        anim, _ = apply_zup_to_yup(anim, rest_anim)
        extracted.append((action_name, anim))

    return extracted


def save_rest_pose_vis(tpos_save_dir, save_name, rest_anim_pruned):
    """Render and save the rest-pose skeleton PNG for one asset."""
    os.makedirs(tpos_save_dir, exist_ok=True)
    tpos_path = os.path.join(tpos_save_dir, f"{save_name}.png")
    rest_global_pos = positions_global(rest_anim_pruned)
    save_skeleton_tpose(
        save_path=tpos_path,
        parents=rest_anim_pruned.parents,
        positions=rest_global_pos[0],
    )
    logger.info(f"Saved rest pose visualization: {tpos_path}")
    return tpos_path


# ─────────────────────────────────────────────────────────────────────────────
# Shared NPZ save and summary helpers
# ─────────────────────────────────────────────────────────────────────────────

def save_motion(motion_path, vis_path, anim, rest_anim, names, skin_matrix, fps,
                action_name="", save_vis=True):
    """Save motion NPZ (float64) and optional MP4.

    The MP4 preview dominates per-clip export time; pass ``save_vis=False``
    to skip it on bulk runs.
    """
    if save_vis:
        global_pos = positions_global(anim)
        save_skeleton_motion(
            save_path=vis_path,
            parents=anim.parents,
            positions=global_pos,
            fps=fps,
        )
        logger.info(f"Saved visualization: {vis_path}")

    # Written beside the target and renamed into place, so an interrupted run
    # never leaves a truncated NPZ that a resumed run would take as done.
    tmp_path = f"{motion_path}.{os.getpid()}.tmp"
    try:
        with open(tmp_path, 'wb') as f:
            np.savez(
                f,
                rest_local_pos=rest_anim.positions[0],
                rest_local_rot=rest_anim.rotations[0].qs,
                anim_local_pos=anim.positions,
                anim_local_rot=anim.rotations.qs,
                offsets=anim.offsets,
                names=np.array(names),
                skin_matrix=skin_matrix,
                fps=fps,
                parents=anim.parents,
                action_name=action_name,
            )
        os.replace(tmp_path, motion_path)
    except BaseException:
        if os.path.exists(tmp_path):
            os.remove(tmp_path)
        raise
    logger.info(f"Saved motion data: {motion_path}")


def scan_clip_frames(motion_dir):
    """Scan saved NPZ files in motion_dir and return {clip_name: nframes}."""
    frames = {}
    if not os.path.isdir(motion_dir):
        return frames
    for npz_file in sorted(os.listdir(motion_dir)):
        if not npz_file.endswith('.npz'):
            continue
        clip_name = os.path.splitext(npz_file)[0]
        try:
            data = np.load(os.path.join(motion_dir, npz_file), allow_pickle=True)
            frames[clip_name] = int(data['anim_local_rot'].shape[0])
        except Exception:
            pass
    return frames


def write_clip_frames_json(path, frames, fps=30):
    """Write clip_frames.json: a pure {clip_name: nframes} mapping."""
    total_frames = sum(frames.values())
    total_clips = len(frames)
    total_duration_sec = total_frames / fps if fps else 0.0
    with open(path, 'w') as f:
        json.dump(frames, f, indent=2)
    logger.info(f"Saved clip frames ({total_clips} clips, {total_frames} frames, "
                f"{total_duration_sec / 60:.1f} min) to {path}")


def write_summary_json(path, frames, fps=30):
    """Write summary.json with the dataset-level summary of the export."""
    total_frames = sum(frames.values())
    total_duration_sec = total_frames / fps if fps else 0.0
    with open(path, 'w') as f:
        json.dump({
            "total_clips": len(frames),
            "total_frames": total_frames,
            "total_duration_sec": round(total_duration_sec, 2),
            "total_duration_min": round(total_duration_sec / 60, 2),
            "fps": fps,
        }, f, indent=2)
    logger.info(f"Saved export metadata to {path}")


def write_export_summary(output_dir, all_joint_names, fps=30, worker_suffix=""):
    """Write per-run summary JSONs: clip_frames, joint_names, joint_count,
    and (for non-sharded runs) summary.json with the dataset-level summary.

    ``all_joint_names`` only covers assets exported by *this* run — assets
    skipped via their completion marker return nothing. Writing it verbatim
    would therefore truncate ``joint_names.json`` on every resumed run, so
    for the canonical (non-sharded) file it is merged over the durable
    per-asset markers and whatever the file already held. Shard files stay
    run-local; :func:`~data_process.tools.merge_summaries.merge_summaries`
    does the same union for them.

    Args:
        output_dir:      Root directory containing the "motions/" NPZ folder.
        all_joint_names: dict mapping obj_type/save_name -> list[str] bone names.
        fps:             Frame rate used for duration summary.
        worker_suffix:   Optional suffix (e.g. "_worker0") appended to filenames.
                         When set, summary.json is left to merge_summaries so
                         parallel workers never race on it.
    """
    frames = scan_clip_frames(os.path.join(output_dir, "motions"))
    write_clip_frames_json(
        os.path.join(output_dir, f"clip_frames{worker_suffix}.json"),
        frames, fps=fps,
    )
    if not worker_suffix:
        write_summary_json(os.path.join(output_dir, "summary.json"), frames, fps=fps)

    joint_names_path = os.path.join(output_dir, f"joint_names{worker_suffix}.json")
    if worker_suffix:
        merged = dict(all_joint_names)
    else:
        merged = merge_joint_names(output_dir, all_joint_names, log=logger.info)
    with open(joint_names_path, 'w') as f:
        json.dump(merged, f, indent=2)
    logger.info(f"Saved joint names ({len(merged)} entries) to {joint_names_path}")
    all_joint_names = merged

    joint_count = {k: len(v) for k, v in all_joint_names.items()}
    joint_count_path = os.path.join(output_dir, f"joint_count{worker_suffix}.json")
    with open(joint_count_path, 'w') as f:
        json.dump(joint_count, f, indent=2)
    logger.info(f"Saved joint count to {joint_count_path}")


# ─────────────────────────────────────────────────────────────────────────────
# Per-asset completion markers (resume bookkeeping)
# ─────────────────────────────────────────────────────────────────────────────
#
# Re-exported from data_process.utils.export_markers, which is deliberately
# free of any bpy import so plain-Python tools (merge_summaries) can use it.

__all__ = [n for n in dir() if not n.startswith('_')] + [
    "is_asset_complete", "mark_asset_complete",
    "collect_joint_names_from_markers", "merge_joint_names",
]