Skip to content

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

Python
11.1 KB
Raw Blame
"""Render multi-view frames for Objaverse GLB/GLTF animations (EEVEE).

For each GLB, discovers all pose actions and renders each one as
``{glb_stem}-{action}/v00{0..3}/*.png`` — the layout consumed by
``vlm_caption/caption_motion.py``. :mod:`render_general` reuses
:func:`main` with the general dataset's file list and action discovery.

Usage (plain python — EEVEE needs the pip ``bpy`` module's GPU context):
    python -m data_process.motion_rendering.render_objaverse \
        --data_dir dataset/raw/objaverse/glb --output_dir <render_dir>
"""

import os
import sys
import argparse
from pathlib import Path

import bpy  # noqa: F401 — fail fast when the bpy module is unavailable
from loguru import logger

from data_process.utils.blender_export import (
    asset_names,
    discover_pose_actions,
    list_gltf_files,
    unique_clip_names,
)
from data_process.utils.blender_render import (
    RENDER_FPS,
    get_expected_clip_dirs,
    init_render_engine,
    is_asset_render_skipped,
    is_render_complete,
    load_and_prep_asset,
    mark_asset_render_done,
    mark_asset_render_skipped,
    render_action_multiview,
)


def find_pending_stems(output_dir, gltf_stems, require_video=False):
    """Return the subset of GLTF stems that still need rendering.

    A stem is done only when a ``.rendered/`` marker lists the clip
    directories it is expected to produce AND every one of them passes
    :func:`is_render_complete`. Requiring the marker is what distinguishes
    "all actions rendered" from "a worker was killed partway through": the
    directories that do exist are complete in both cases, so judging by
    on-disk directories alone would retire the asset with actions still
    unrendered, permanently. Stems that are done skip the expensive GLB load.

    Action folders are named ``{stem}-{sanitized_action}``; stems may
    themselves contain ``-``, so directory names are matched against the
    known stem set by longest-prefix-at-hyphen rather than splitting on
    the first ``-``.
    """
    output_dir = Path(output_dir)
    stems_set = set(gltf_stems)
    if not output_dir.is_dir():
        return stems_set

    # Assets marked as producing no renders (no armature / actions) are done.
    stems_set = {s for s in stems_set
                 if not is_asset_render_skipped(str(output_dir), s)}

    pending = set()
    for stem in stems_set:
        expected = get_expected_clip_dirs(str(output_dir), stem)
        if not expected:
            # Never finished an end-to-end pass (or predates the marker):
            # re-open it. Completed clip dirs are still skipped per-action.
            pending.add(stem)
            continue
        if not all(is_render_complete(str(output_dir / d), require_video=require_video)
                   for d in expected):
            pending.add(stem)

    return pending


def render_glb(glb_path, output_dir, args, save_name, discover=None):
    """Render multi-view frames for every pose action in one asset file.

    Args:
        save_name: Asset name / clip-folder prefix (``asset_name`` of the
            file, as the exporter names it).
        discover: ``armature -> (action_names, frame_ranges)``; must match
            the exporter of the same dataset (default: every pose action,
            :func:`discover_pose_actions`).
    """
    if is_asset_render_skipped(output_dir, save_name):
        logger.info(f"Previously marked as no-render, skipping: {glb_path}")
        return

    logger.info(f"Processing: {glb_path}")

    armature = load_and_prep_asset(str(glb_path), fps=args.fps)
    if armature is None:
        logger.warning(f"No armature/mesh in {glb_path}; skipping.")
        mark_asset_render_skipped(output_dir, save_name, reason="no armature/mesh")
        return

    # Names are derived from the UNFILTERED action list so they match the
    # export stage, which applies no frame-count filter — deriving them from
    # a filtered subset would shift the collision suffixes out of step.
    if discover is None:
        all_action_names, frame_ranges = discover_pose_actions()
    else:
        all_action_names, frame_ranges = discover(armature)
    clip_suffixes = unique_clip_names(all_action_names)

    action_names = [
        n for n in all_action_names
        if (frame_ranges[n][1] - frame_ranges[n][0] + 1) >= args.min_action_frames
    ]
    logger.info(f"Found {len(action_names)} pose actions "
                f"({len(all_action_names)} before the frame-count filter)")
    if not action_names:
        mark_asset_render_skipped(output_dir, save_name, reason="no pose actions")
        return

    expected_dirs = []
    for action_name in action_names:
        clean_action_name = clip_suffixes[action_name]
        clip_dir_name = f"{save_name}-{clean_action_name}"
        action_dir = os.path.join(output_dir, clip_dir_name)
        expected_dirs.append(clip_dir_name)

        if is_render_complete(action_dir, require_video=args.video):
            logger.info(f"Skipping complete: {action_dir}")
            continue

        start, end = frame_ranges[action_name]
        logger.info(f"Rendering '{action_name}' -> '{clip_dir_name}' "
                    f"frames=[{start},{end}]")

        render_action_multiview(
            armature=armature,
            action_name=action_name,
            start_frame=start,
            end_frame=end,
            save_root=action_dir,
            camera_dist=args.camera_dist,
            scene_scale=args.scale,
            resolution=args.resolution,
            max_render_frames=args.max_render_frames,
            compose_video=args.video,
            fps=args.fps,
        )

    # Only now is the asset known to have had every action handled.
    mark_asset_render_done(output_dir, save_name, expected_dirs)


def main(list_assets=list_gltf_files, discover=None,
         description="Render multi-view frames for Objaverse GLB/GLTF animations (EEVEE)."):
    """CLI entry point.

    Args:
        list_assets: ``data_dir -> [asset paths]``. Each asset renders under
            its :func:`asset_name` (the stem for objaverse's hex ids).
        discover: Action discovery passed to :func:`render_glb`.
    """
    parser = argparse.ArgumentParser(description=description)
    parser.add_argument("--data_dir", type=str, required=True,
                        help="Directory containing the asset files.")
    parser.add_argument("--obj_name", type=str, default=None,
                        help="Single asset name to render (the file stem with "
                             "'-' and whitespace replaced by '_'; default: all files).")
    parser.add_argument("--output_dir", type=str, required=True,
                        help="Output directory.")
    parser.add_argument("--scale", type=float, default=1.0,
                        help="Scene normalization scale.")
    parser.add_argument("--camera_dist", type=float, default=1.5,
                        help="Camera distance from origin.")
    parser.add_argument("--resolution", type=int, default=512,
                        help="Render resolution (square).")
    parser.add_argument("--fps", type=int, default=RENDER_FPS,
                        help="Scene FPS for import and preview video. Must match "
                             "the export stage's --fps: glTF keyframes are stored "
                             "in seconds, so the importer resamples at this rate.")
    parser.add_argument("--samples", type=int, default=64,
                        help="EEVEE TAA render samples.")
    parser.add_argument("--max_render_frames", type=int, default=200,
                        help="Cap on rendered frames per clip (per view).")
    parser.add_argument("--min_action_frames", type=int, default=5,
                        help="Skip actions shorter than this many raw frames "
                             "(default 5 — the shared minimum clip length "
                             "across export and rendering; raw length >= "
                             "post-T-pose-removal length, so no exported clip "
                             "is ever skipped).")
    parser.add_argument("--video", action=argparse.BooleanOptionalAction, default=True,
                        help="Compose each view's frames into v00x.mp4 "
                             "(use --no-video to skip).")
    parser.add_argument("--missing-only", dest="missing_only", action="store_true",
                        help="Scan output_dir first; only load GLBs that have "
                             "at least one missing or incomplete action folder.")
    parser.add_argument("--worker_id", type=int, default=0,
                        help="Worker index for sharding across workers.")
    parser.add_argument("--num_workers", type=int, default=1,
                        help="Total number of workers.")
    parser.add_argument("--gpu_id", type=int, default=None,
                        help="GPU device ID to pin this worker to "
                             "(default: inherit CUDA_VISIBLE_DEVICES).")
    args = parser.parse_args()

    if args.gpu_id is not None:
        os.environ["CUDA_VISIBLE_DEVICES"] = str(args.gpu_id)

    init_render_engine(render_samples=args.samples)

    data_dir = Path(args.data_dir)
    gltf_paths = list_assets(data_dir)
    # Raises when two files share a name; checked before sharding so every
    # worker agrees.
    names = asset_names(gltf_paths)
    if args.obj_name:
        gltf_paths = [p for p in gltf_paths if names[p] == args.obj_name]
        if not gltf_paths:
            parser.error(f"No asset named {args.obj_name!r} in {data_dir} "
                         f"(or it is listed in excluded.csv)")
    else:
        logger.info(f"Found {len(gltf_paths)} asset files in {data_dir}")

    if args.missing_only:
        pending = find_pending_stems(args.output_dir, [names[p] for p in gltf_paths],
                                     require_video=args.video)
        before = len(gltf_paths)
        gltf_paths = [p for p in gltf_paths if names[p] in pending]
        logger.info(f"[missing-only] {len(gltf_paths)}/{before} assets have pending renders.")

    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}: "
                    f"{len(gltf_paths)} files")

    os.makedirs(args.output_dir, exist_ok=True)
    error_log = os.path.join(args.output_dir,
                             f'render_errors_worker{args.worker_id}.log')

    n_failed = 0
    for glb_path in gltf_paths:
        try:
            render_glb(glb_path, args.output_dir, args,
                       save_name=names[glb_path], discover=discover)
        except Exception as e:  # noqa: BLE001 — keep the batch going
            n_failed += 1
            logger.exception(f"Failed to render {glb_path}")
            with open(error_log, 'a') as f:
                f.write(f"{glb_path}\t{e}\n")

    if n_failed:
        logger.error(f"{n_failed}/{len(gltf_paths)} assets failed; see {error_log}")
    return 1 if n_failed else 0


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