Skip to content

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

Python
5.1 KB
Raw Blame
#!/bin/bash
# Process one rigged 3D asset (GLB/GLTF/FBX, with or without animation) into
# the model's inputs: <OUTPUT_DIR>/cond.npy (its topology condition),
# <OUTPUT_DIR>/<name>.glb (its canonical asset) and <OUTPUT_DIR>/preview.png
# (facing and joint labels to check), through the same export,
# joint-annotation and feature code as the dataset pipeline
# (data_process/rig_preprocess, see its AGENTS.md). The output directory is
# then an asset for sampling: python -m unimate.inference.sample --asset <OUTPUT_DIR>.
#
# Usage:
#   INPUT=my_robot.glb OUTPUT_DIR=outputs/my_robot bash data_process/scripts/run_rig_preprocess.sh
#   INPUT=rig.fbx OUTPUT_DIR=out FACE_R=R_Thigh FACE_L=L_Thigh bash data_process/scripts/run_rig_preprocess.sh
#   INPUT="dataset/raw/truebones/animation/Dog-*.fbx" PROFILE=truebones ANNOTATE=dataset \
#       OUTPUT_DIR=out/Dog bash data_process/scripts/run_rig_preprocess.sh -- --keep_intermediate
#   VERIFY=1 ...   # then compare the output with the dataset's copy (training assets)
#   # by default a run stops before the cond: check out/annotation.json (see out/REVIEW.md), then
#   ANNOTATION=out/annotation.json INPUT=rig.glb OUTPUT_DIR=out bash data_process/scripts/run_rig_preprocess.sh
#   REVIEW=0 INPUT=rig.glb OUTPUT_DIR=out bash data_process/scripts/run_rig_preprocess.sh   # build directly
#
# Env overrides:
#   INPUT        (required) the asset file; a glob or space-separated list for
#                PROFILE=truebones (one species' clip FBXs); no spaces in paths
#   OUTPUT_DIR   (required)
#   PROFILE      auto (default: truebones for several {Species}-{Action}.fbx clips;
#                with ANNOTATE=dataset, the dataset of --dataset_export_dir, passed after --;
#                else general) | general | objaverse | truebones: the dataset whose
#                processing to reproduce
#   ANNOTATE     llm | rule | dataset: joint-name / facing source (default: llm when
#                DEEPSEEK_API_KEY / OPENAI_API_KEY is set for the model, else rule;
#                rule when ANNOTATION, ANNOTATE_NAMES or ANNOTATE_FACE is given)
#   ANNOTATE_NAMES, ANNOTATE_FACE  rule | llm: one source differing from ANNOTATE
#                (not with ANNOTATE=dataset), e.g. ANNOTATE_FACE=llm for rule names
#                with an LLM-chosen face pair
#   NAME         object type for the asset (default: from its file name)
#   FACE_R, FACE_L  raw names of the facing pair (overrides the annotation);
#                BODY_AXIS=1 when it is a head / tail axis
#   EXP_DIR      training run whose joint width (config.json) the asset is checked
#                against (default: the released UniML3D models' width, 71)
#   FORMATS      canonical asset files: glb (default) or glb,fbx
#   SAVE_CLIPS   1: keep the feature clips in <OUTPUT_DIR>/motions/ (ground truth
#                for in-betweening / motion editing)
#   REST_ROTATION  stand up a rest pose authored lying down / upside down, e.g. x180,
#                x90, x-90 (preview.png and summary.json notes show when it is needed)
#   REVIEW       1 / 0: stop after the annotation, before the cond, and write
#                annotation.json, annotation_preview.png and REVIEW.md to check the
#                joint labels and the facing pair (by hand, or with an LLM / agent) /
#                build directly. Default: review, except with ANNOTATION or ANNOTATE=dataset
#   ANNOTATION   a reviewed annotation.json: its labels and facing pair replace the
#                annotation, and the run continues to the cond
#   VERIFY       1: run `verify` afterwards when the asset was built (exit 1 on a difference)
#   CONDA_ENV    conda environment to activate (default: unimate)
# Arguments after `--` go to `python -m data_process.rig_preprocess run`
# (--keep_intermediate, --overwrite, LLM options, ...).

set -euo pipefail
source "$(dirname "${BASH_SOURCE[0]}")/_common.sh"

handle_help "$@"
[[ "${1:-}" == "--" ]] && shift

INPUT=${INPUT:?Set INPUT to the asset file}
OUTPUT_DIR=${OUTPUT_DIR:?Set OUTPUT_DIR}
read -r -a INPUTS <<< "$INPUT"
# shellcheck disable=SC2206
INPUTS=(${INPUTS[@]})          # expand globs

ARGS=(--input "${INPUTS[@]}" --output_dir "$OUTPUT_DIR"
      --profile "${PROFILE:-auto}" ${ANNOTATE:+--annotate "$ANNOTATE"})
[[ -n "${FORMATS:-}" ]] && ARGS+=(--formats "$FORMATS")
[[ "${SAVE_CLIPS:-0}" == 1 ]] && ARGS+=(--save_clips)
[[ -n "${REST_ROTATION:-}" ]] && ARGS+=(--rest_rotation "$REST_ROTATION")
[[ -n "${ANNOTATE_NAMES:-}" ]] && ARGS+=(--annotate_names "$ANNOTATE_NAMES")
[[ -n "${ANNOTATE_FACE:-}" ]] && ARGS+=(--annotate_face "$ANNOTATE_FACE")
[[ -n "${NAME:-}" ]] && ARGS+=(--name "$NAME")
[[ -n "${EXP_DIR:-}" ]] && ARGS+=(--exp_dir "$EXP_DIR")
[[ -n "${FACE_R:-}" ]] && ARGS+=(--face_r "$FACE_R")
[[ -n "${FACE_L:-}" ]] && ARGS+=(--face_l "$FACE_L")
[[ "${BODY_AXIS:-0}" == 1 ]] && ARGS+=(--body_axis)
[[ "${REVIEW:-}" == 1 ]] && ARGS+=(--review)
[[ "${REVIEW:-}" == 0 ]] && ARGS+=(--no_review)
[[ -n "${ANNOTATION:-}" ]] && ARGS+=(--annotation "$ANNOTATION")

python -m data_process.rig_preprocess run "${ARGS[@]}" "$@"
if [[ "${VERIFY:-0}" == 1 && -f "$OUTPUT_DIR/cond.npy" ]]; then
    python -m data_process.rig_preprocess verify --output_dir "$OUTPUT_DIR"
fi