Skip to content

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

Python
13.2 KB
Raw Blame
"""Export a directory of rigged GLB/GLTF files (e.g. Objaverse) to NPZ motion data.

Pipeline per file: import scene → select armature/mesh → discover actions →
extract animations → Z-up → Y-up → prune skeleton (shared across clips) →
remove T-pose frames → save per-clip NPZ + MP4 + rest-pose PNG.

Files can be sharded across parallel Blender processes with
``--worker_id`` / ``--num_workers``; each worker writes its own summary
JSONs (``*_worker{i}.json``).

``--save_glb`` also writes ``rigs/<asset>.glb`` per asset: the asset in its
rest pose on the pruned skeleton, without animation
(``processed_assets.export_asset_glb``); every clip NPZ of the asset drives it as a
character (``mesh_animation``). On an existing export it only adds the missing
GLBs (the NPZs are not rewritten). ``--glb_only`` does only that, also for an
export without completion markers (the released ones): it builds the missing
GLBs of the assets whose NPZs are already in ``motions/`` and writes nothing
else.

Usage (Blender headless):
    blender -b -P data_process/motion_export/export_objaverse.py -- \
        --data_dir dataset/raw/objaverse/glb \
        --output_dir dataset/export/objaverse
"""

import bpy
import sys
import os
import numpy as np
import argparse
from pathlib import Path
from loguru import logger
from tqdm import tqdm

sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))

from data_process.utils.blender_export import (
    asset_names,
    import_gltf, list_gltf_files, sanitize_action_name, unique_clip_names,
    load_scene, prepare_skeleton, extract_all_actions, save_rest_pose_vis,
    prune_skeleton_shared, remove_tpose_frames, discover_pose_actions,
    save_motion, write_export_summary,
    is_asset_complete, mark_asset_complete,
)
from data_process.utils.asset_files import (
    REPLACED_DIR, asset_glb_missing, remove_asset_glb, report_glb_errors, set_aside_old_clips,
)
from data_process.utils.processed_assets import add_asset_glb, build_asset_glb

# ─────────────────────────────────────────────────────────────────────────────
# Main export pipeline
# ─────────────────────────────────────────────────────────────────────────────

def export_objaverse(gltf_path, save_name, output_dir, fps=30, dtype=np.float64,
                     min_frames=5, consider_parent_rotate=True, save_vis=True,
                     save_glb=False, glb_only=False):
    """Export every pose action in one GLB/GLTF file. Returns ``{save_name: joint_names}``.

    ``save_glb`` also writes the asset's processed GLB, ``glb_only`` only that
    (module docstring).
    """
    assert os.path.exists(gltf_path), f"GLTF file not found: {gltf_path}"

    if glb_only:
        # Existing NPZs only, markers or not; never (re-)exports.
        if asset_glb_missing(output_dir, save_name):
            add_asset_glb(save_name, output_dir,
                          lambda: load_scene(import_gltf, gltf_path, fps=fps)[0],
                          source_path=gltf_path)
        return {}

    motion_save_dir = os.path.join(output_dir, "motions")
    vis_save_dir = os.path.join(output_dir, "videos")
    tpos_save_dir = os.path.join(output_dir, "tpose")

    if is_asset_complete(output_dir, save_name):
        if not (save_glb and asset_glb_missing(output_dir, save_name)):
            logger.info(f"Asset '{save_name}' already complete, skipping: {gltf_path}")
            return {}
        logger.info(f"Asset '{save_name}' already exported; adding its processed GLB")
        add_asset_glb(save_name, output_dir,
                      lambda: load_scene(import_gltf, gltf_path, fps=fps)[0],
                      source_path=gltf_path)
        return {}
    remove_asset_glb(output_dir, save_name)
    existing = sorted(Path(motion_save_dir).glob(f"{save_name}-*.npz")) if os.path.isdir(motion_save_dir) else []
    if existing:
        # Pruning is joint across all of an asset's clips, so a partial
        # (or pre-marker) export must be redone as a whole.
        logger.warning(f"'{save_name}' has {len(existing)} clip(s) but no completion "
                       f"marker (partial or pre-marker export); re-exporting; the old clips go to "
                       f"{REPLACED_DIR}/.")
        set_aside_old_clips(output_dir, save_name)

    logger.info(f"Processing GLTF: {gltf_path}")
    os.makedirs(motion_save_dir, exist_ok=True)
    os.makedirs(vis_save_dir, exist_ok=True)

    armature, mesh = load_scene(import_gltf, gltf_path, fps=fps)
    assert mesh is not None, f"No mesh found in {gltf_path}; cannot build skin matrix."

    action_names, frame_ranges = discover_pose_actions()
    logger.info(f"Total relevant actions: {len(action_names)}")
    if not action_names:
        logger.info(f"No valid actions in {gltf_path}; skipping.")
        mark_asset_complete(output_dir, save_name, status="skipped",
                            reason="no pose actions")
        return {}

    skel = prepare_skeleton(armature, mesh, dtype=dtype, apply_world=True)
    extracted = extract_all_actions(
        armature, frame_ranges,
        skel['rest_local_pos'], skel['parents_array'],
        skel['rest_anim'], skel['nbones'], dtype=dtype,
    )

    anims_list = [anim for _, anim in extracted]
    anims_list, rest_anim_pruned, names_pruned, skin_matrix_pruned = prune_skeleton_shared(
        anims_list, skel['rest_anim_shared'], skel['bone_names'].copy(), skel['skin_matrix'].copy(),
        consider_parent_rotate=consider_parent_rotate,
    )

    # No joint-count gate here: stage 4 (feature_extraction --min_joints /
    # --max_joints) decides which skeletons enter training, so the export
    # stays complete.
    save_rest_pose_vis(tpos_save_dir, save_name, rest_anim_pruned)

    # Distinct actions can sanitize to the same name; disambiguate over the
    # full discovered list so the renderer derives identical clip names.
    clip_suffixes = unique_clip_names(action_names)

    scene_fps = bpy.context.scene.render.fps
    saved_clips = []
    for i, (action_name, _) in enumerate(extracted):
        anim = anims_list[i]

        anim, n_tpose = remove_tpose_frames(anim, rest_anim_pruned)
        if n_tpose > 0:
            logger.info(f"Removed {n_tpose} T-pose frames from '{action_name}', "
                        f"{anim.positions.shape[0]} frames remaining")
        if anim.positions.shape[0] < min_frames:
            logger.info(f"Skipping '{action_name}': only {anim.positions.shape[0]} frames "
                        f"after T-pose removal (min={min_frames})")
            continue

        clean_action_name = clip_suffixes.get(
            action_name, sanitize_action_name(action_name) or "action")
        clip_name = f"{save_name}-{clean_action_name}"
        motion_path = os.path.join(motion_save_dir, f"{clip_name}.npz")
        vis_path = os.path.join(vis_save_dir, f"{clip_name}.mp4")
        save_motion(motion_path, vis_path, anim, rest_anim_pruned,
                    names_pruned, skin_matrix_pruned, scene_fps,
                    action_name=action_name, save_vis=save_vis)
        saved_clips.append(clip_name)

    mark_asset_complete(output_dir, save_name,
                        status="exported" if saved_clips else "skipped",
                        n_clips=len(saved_clips),
                        reason="" if saved_clips else "no clips above min frame count",
                        joint_names=names_pruned if saved_clips else None)
    # After the marker, from a clip this run saved and a fresh import (the
    # scene now sits at the last extracted frame, and an animated armature
    # object or parent empty would carry that pose): exactly what --glb_only
    # builds. A failure is recorded, not raised.
    if save_glb and saved_clips:
        build_asset_glb(save_name, os.path.join(motion_save_dir, f"{saved_clips[0]}.npz"),
                        output_dir, lambda: load_scene(import_gltf, gltf_path, fps=fps)[0],
                        source_path=gltf_path)

    # Return once per asset (skeleton type), not per clip
    if saved_clips:
        return {save_name: names_pruned}
    return {}


# ─────────────────────────────────────────────────────────────────────────────
# Entry point
# ─────────────────────────────────────────────────────────────────────────────

def parse_args():
    parser = argparse.ArgumentParser(description="Export GLB/GLTF files to NPZ motion data.")
    parser.add_argument('--data_dir', type=str, required=True,
                        help='Directory containing GLB/GLTF files.')
    parser.add_argument('--output_dir', type=str, required=True,
                        help='Output directory for NPZ motion data.')
    parser.add_argument('--fps', type=int, default=30,
                        help='Scene FPS for import and export.')
    parser.add_argument('--consider_parent_rotate', action=argparse.BooleanOptionalAction, default=True,
                        help='Preserve non-rotating leaves whose parent rotates during pruning '
                             '(see prune_skeleton_shared; use --no-consider_parent_rotate to disable).')
    parser.add_argument('--min_frames', type=int, default=5,
                        help='Skip clips shorter than this after T-pose removal.')
    parser.add_argument('--worker_id', type=int, default=0,
                        help="Worker index for sharding files across workers.")
    parser.add_argument('--num_workers', type=int, default=1,
                        help="Total number of workers.")
    parser.add_argument('--vis', action=argparse.BooleanOptionalAction, default=True,
                        help="Render the per-clip MP4 preview (use --no-vis for bulk runs).")
    parser.add_argument('--save_glb', action='store_true',
                        help="Also write rigs/<asset>.glb: the asset in its rest pose on the "
                             "pruned skeleton (no animation; the clip NPZs drive it), for "
                             "mesh_animation. On an existing export, only the missing GLBs are added.")
    parser.add_argument('--glb_only', action='store_true',
                        help="Only add missing rigs/<asset>.glb to an existing export, for the "
                             "assets whose NPZs are already in motions/: no NPZ, completion marker "
                             "or summary JSON is written, and none is required.")

    argv = sys.argv[sys.argv.index("--") + 1:] if "--" in sys.argv else sys.argv[1:]
    return parser.parse_args(argv)


def main():
    args = parse_args()

    gltf_paths = list_gltf_files(Path(args.data_dir))
    assert len(gltf_paths) > 0, f"No GLB/GLTF files found in {args.data_dir}"
    logger.info(f"Found {len(gltf_paths)} GLB/GLTF files in {args.data_dir}")
    # Same names as render_objaverse (identity for objaverse's hex ids);
    # checked over the full list, before sharding, so every worker agrees.
    names = asset_names(gltf_paths)

    # Shard files across workers
    if args.num_workers > 1:
        gltf_paths = gltf_paths[args.worker_id::args.num_workers]
        logger.info(f"Worker {args.worker_id}/{args.num_workers}: processing {len(gltf_paths)} files")

    os.makedirs(args.output_dir, exist_ok=True)
    error_log = os.path.join(args.output_dir, f'export_errors_worker{args.worker_id}.log')
    all_joint_names = {}
    n_failed = 0
    for glb_path in tqdm(gltf_paths, desc="Exporting GLB/GLTF files"):
        try:
            saved = export_objaverse(glb_path, names[glb_path], output_dir=args.output_dir,
                                     fps=args.fps, min_frames=args.min_frames,
                                     consider_parent_rotate=args.consider_parent_rotate,
                                     save_vis=args.vis, save_glb=args.save_glb,
                                     glb_only=args.glb_only)
            if saved:
                all_joint_names.update(saved)
        except Exception as e:  # noqa: BLE001 — keep the batch going
            n_failed += 1
            logger.exception(f"Failed to export {glb_path}")
            with open(error_log, 'a') as log_file:
                log_file.write(f"Failed to export {glb_path}: {e}\n")

    if not args.glb_only:
        worker_suffix = f"_worker{args.worker_id}" if args.num_workers > 1 else ""
        write_export_summary(args.output_dir, all_joint_names, fps=args.fps,
                             worker_suffix=worker_suffix)

    if args.save_glb or args.glb_only:
        report_glb_errors(args.output_dir)
    if n_failed:
        logger.error(f"{n_failed}/{len(gltf_paths)} assets failed; see {error_log}")
        sys.exit(1)


if __name__ == "__main__":
    # Blender exits 0 even on an uncaught exception, which hides failures from
    # `set -e` and from Slurm's afterok dependencies.
    try:
        main()
    except SystemExit:
        raise
    except Exception:
        logger.exception("export_objaverse failed")
        sys.exit(1)