[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons
Python
"""Drive a rigged character with an *exported* motion NPZ and save GLB/FBX.
Takes the NPZ format written by the export stage
(``rest_local_pos`` / ``rest_local_rot`` / ``anim_local_pos`` /
``anim_local_rot`` / ``names`` / ``parents`` / ``offsets``) and re-applies it
to a character whose armature uses the same bone names. Useful for
round-trip checks of the export and for re-rendering exported clips.
For *generated* motions (feature NPZ + ``cond.npy``) use
:mod:`data_process.mesh_animation.animate_motion` instead.
``--char_path`` may be omitted with ``--dataset_type``: the processed export
asset ``dataset/export/<ds>/rigs/<name>.glb`` is used (run_export.sh
--save_glb / --glb_only), whose skeleton is the NPZ's, so nothing is merged;
<name> is the clip's object type, for Mixamo ``--character`` (default Michelle).
Usage (Blender headless):
blender -b -P data_process/mesh_animation/animate_npz.py -- \\
--char_path my_model.glb \\
--anim_path <export_dir>/motions/my_model-Walk.npz \\
--output_dir outputs/animated
"""
import argparse
import os
import sys
import numpy as np
from loguru import logger
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
from Animation import Animation, Quaternions # noqa: E402
from data_process.mesh_animation.common import ( # noqa: E402
DEFAULT_MIXAMO_CHARACTER,
clip_output_path,
drive_and_export,
load_character,
npz_scalar,
parse_blender_argv,
resolve_processed_asset,
)
from data_process.utils.blender_rig import EXTRA_BONES_STRATEGIES # noqa: E402
def build_anims_from_export_npz(anim_data):
"""Build ``(anim, rest_anim, bone_names)`` from an export-stage NPZ."""
bone_names = anim_data['names'].tolist()
nbones = anim_data['anim_local_rot'].shape[1]
scale_factor = npz_scalar(anim_data, 'scale_factor', 1.0)
anim_positions = anim_data['anim_local_pos'] / scale_factor
rest_positions = anim_data['rest_local_pos'][None] / scale_factor
offsets = anim_data['offsets'] / scale_factor
parents = anim_data['parents']
anim = Animation(
rotations=Quaternions(anim_data['anim_local_rot']),
positions=anim_positions,
orients=Quaternions.id(nbones),
offsets=offsets,
parents=parents,
)
rest_anim = Animation(
rotations=Quaternions(anim_data['rest_local_rot'][None]),
positions=rest_positions,
orients=Quaternions.id(nbones),
offsets=offsets,
parents=parents,
)
return anim, rest_anim, bone_names
def animate_character(char_path, anim_path, output_dir, char_anim_type='glb',
extra_bones_strategy='merge', skip_if_exists=False):
"""Drive a character mesh with an export NPZ and save as GLB/FBX.
Args:
char_path: Character FBX/GLB (provides mesh + armature).
anim_path: Motion NPZ produced by the export stage.
output_dir: Destination directory (created if missing).
char_anim_type: Export format, ``'glb'`` or ``'fbx'``.
extra_bones_strategy: How to treat armature bones absent from the
animation (see :func:`sync_armature_bones`).
skip_if_exists: Return early when the output file already exists.
"""
assert os.path.exists(anim_path), f"Animation file not found: {anim_path}"
output_path = clip_output_path(anim_path, output_dir, char_anim_type)
if skip_if_exists and os.path.exists(output_path):
logger.info(f"Output already exists, skipping: {output_path}")
return
os.makedirs(output_dir, exist_ok=True)
char_armature = load_character(char_path)
anim_data = np.load(anim_path, allow_pickle=True)
anim, rest_anim, bone_names = build_anims_from_export_npz(anim_data)
drive_and_export(
char_armature, anim, rest_anim, bone_names,
fps=npz_scalar(anim_data, 'fps', 30),
output_path_no_ext=os.path.splitext(output_path)[0],
formats=(char_anim_type,),
extra_bones_strategy=extra_bones_strategy,
)
def parse_args():
parser = argparse.ArgumentParser(
description="Drive a rigged character with an exported motion NPZ.")
parser.add_argument("--char_path", type=str, default=None,
help="Character FBX/GLB (mesh + armature). Default with "
"--dataset_type: the processed export asset.")
parser.add_argument("--dataset_type", type=str, default=None,
choices=['truebones', 'objaverse', 'mixamo', 'general'],
help="Resolve --char_path from dataset/export/<ds>/rigs/.")
parser.add_argument("--character", type=str, default=None,
help=f"Mixamo character (default {DEFAULT_MIXAMO_CHARACTER}).")
parser.add_argument("--anim_path", type=str, required=True,
help="Export-stage motion NPZ whose bone names match the rig.")
parser.add_argument("--output_dir", type=str, default='outputs/animated')
parser.add_argument("--char_anim_type", type=str, default='glb', choices=['glb', 'fbx'])
parser.add_argument("--extra_bones_strategy", type=str, default='merge',
choices=list(EXTRA_BONES_STRATEGIES),
help="What to do with armature bones missing from the animation.")
return parse_blender_argv(parser)
if __name__ == "__main__":
args = parse_args()
char_path = args.char_path
if char_path is None:
if not args.dataset_type:
raise SystemExit("--char_path is required without --dataset_type")
char_path = resolve_processed_asset(args.anim_path, args.dataset_type, 'export',
args.character)
animate_character(
char_path=char_path,
anim_path=args.anim_path,
output_dir=args.output_dir,
char_anim_type=args.char_anim_type,
extra_bones_strategy=args.extra_bones_strategy,
)