Skip to content

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

Python
8.0 KB
Raw Blame
"""Render T-pose 2x2 grid images for rigged assets (EEVEE).

One PNG per asset, saved flat as ``{output_dir}/{name}.png`` (front/back
top row, left/right bottom row) — the "flat" layout consumed by
``vlm_caption/classify_category.py``.

Two input layouts are auto-detected per entry of ``--data_dir``:
  - files:        ``<data_dir>/*.{glb,gltf,fbx}``  -> one grid per asset name
    (the stem with ``-`` and whitespace replaced by ``_``, as the general
    exporter names it; objaverse stems are unchanged)
  - subdirectory: ``<data_dir>/<obj_type>/*.fbx``  -> one grid per object
    type, rendered from its main (all-in-one) FBX — Truebones layout.

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

import os
import sys
import argparse
from pathlib import Path

from loguru import logger

from data_process.utils.blender_export import (
    asset_names, find_main_fbx, load_excluded_stems, sanitize_object_type,
)
from data_process.utils.blender_render import (
    RENDERABLE_EXTS,
    RENDER_FPS,
    init_render_engine,
    load_and_prep_asset,
    render_tpose_grid,
)


def discover_assets(data_dir, species_grids=False):
    """Return (name, path) pairs to render, auto-detecting the layout.

    Files directly under *data_dir* (minus ``excluded.csv``) are rendered
    by asset name; each
    subdirectory is treated as a Truebones-style object type and rendered
    from its main FBX (fallback: first FBX in the subdirectory).

    With *species_grids*, files named ``{Species}-{Action}.*`` are grouped
    by the stem's prefix before the first ``-`` and one grid is rendered
    per species, from its first file (curated Truebones layout).
    """
    data_dir = Path(data_dir)
    assets = []
    seen_species = set()
    # Per-file grids are named like the exporters name them (asset_names
    # raises when two share a name) and skip excluded.csv, as the objaverse
    # and general stages do; species grids keep the Truebones behaviour.
    excluded = set() if species_grids else load_excluded_stems(data_dir)
    files = [p for p in sorted(data_dir.iterdir())
             if p.is_file() and p.suffix.lower() in RENDERABLE_EXTS and p.stem not in excluded]
    names = {} if species_grids else asset_names(files)

    for p in files:
        if species_grids:
            species = p.stem.split('-', 1)[0]
            if species in seen_species:
                continue
            seen_species.add(species)
            assets.append((sanitize_object_type(species), p))
        else:
            assets.append((names[p], p))
    for p in sorted(data_dir.iterdir()):
        if p.is_dir():
            main_fbx = find_main_fbx(str(p))
            if main_fbx is None:
                fbxs = sorted(f for f in p.iterdir()
                              if f.suffix.lower() == ".fbx")
                main_fbx = str(fbxs[0]) if fbxs else None
            if main_fbx is None:
                logger.warning(f"No FBX found in {p}; skipping.")
                continue
            assets.append((sanitize_object_type(p.name), Path(main_fbx)))

    return assets


def render_asset_tpose(name, path, output_dir, args):
    """Render the T-pose grid for one asset to ``{output_dir}/{name}.png``."""
    tpose_path = os.path.join(output_dir, f"{name}.png")
    if os.path.isfile(tpose_path):
        logger.info(f"Skipping complete: {tpose_path}")
        return

    logger.info(f"Processing: {path} -> {name}")

    armature = load_and_prep_asset(str(path),
                                   keep_only_main_mesh=args.keep_main_mesh_only,
                                   fps=args.fps)
    if armature is None:
        logger.warning(f"No armature/mesh in {path}; skipping.")
        return

    render_tpose_grid(
        save_path=tpose_path,
        camera_dist=args.camera_dist,
        scene_scale=args.scale,
        resolution=args.resolution,
    )


def main():
    parser = argparse.ArgumentParser(
        description="Render T-pose 2x2 grid images for rigged assets (EEVEE).")
    parser.add_argument("--data_dir", type=str, required=True,
                        help="Directory of GLB/GLTF/FBX files, or of "
                             "per-object-type FBX subdirectories (Truebones).")
    parser.add_argument("--obj_name", type=str, default=None,
                        help="Single asset name (asset name or object type) "
                             "to render (default: all).")
    parser.add_argument("--output_dir", type=str, required=True,
                        help="Flat directory for the <name>.png grids.")
    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("--fps", type=int, default=RENDER_FPS,
                        help="Scene FPS for import (must match the export "
                             "stage's --fps).")
    parser.add_argument("--resolution", type=int, default=512,
                        help="Render resolution per view (square).")
    parser.add_argument("--samples", type=int, default=64,
                        help="EEVEE TAA render samples.")
    parser.add_argument("--keep-all-meshes", dest="keep_main_mesh_only",
                        action="store_false",
                        help="Keep every mesh, instead of only those skinned to "
                             "or parented under the armature (stray helper "
                             "geometry included).")
    parser.add_argument("--species_grids", action="store_true",
                        help="Group {Species}-{Action}.fbx files by species "
                             "and render one grid per species (curated "
                             "Truebones layout).")
    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)

    assets = discover_assets(args.data_dir, species_grids=args.species_grids)
    logger.info(f"Found {len(assets)} assets in {args.data_dir}")

    if args.obj_name:
        assets = [(n, p) for n, p in assets if n == args.obj_name]
        if not assets:
            parser.error(f"Asset '{args.obj_name}' not found in {args.data_dir}")

    if args.num_workers > 1:
        assets = assets[args.worker_id::args.num_workers]
        logger.info(f"Worker {args.worker_id}/{args.num_workers}: "
                    f"{len(assets)} assets")

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

    n_failed = 0
    for name, path in assets:
        try:
            render_asset_tpose(name, path, args.output_dir, args)
        except Exception as e:  # noqa: BLE001 — keep the batch going
            n_failed += 1
            logger.exception(f"Failed to render {path}")
            with open(error_log, 'a') as f:
                f.write(f"{path}\t{e}\n")

    if n_failed:
        logger.error(f"{n_failed}/{len(assets)} 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 (same guard as the
    # motion renderers).
    try:
        sys.exit(main())
    except Exception:
        logger.exception("render_tpose failed")
        sys.exit(1)