[SIGGRAPH Asia 2026] UniMate: One Unified Model to Animate Diverse Skeletons
Python
"""Visualize skeleton T-poses with joint names annotated, for manual review.
Workflow companion for ``face_select*``: when automatic face-joint
resolution produces ``"source": "empty"`` (or picks the wrong pair), render
the T-pose with every joint labeled so the left/right symmetric pair can be
identified by eye. Each motion NPZ produces one PNG.
Accepts the export-stage NPZ layout (see
:func:`data_process.utils.blender_export.save_motion`) whose relevant fields are:
rest_local_pos : (J, 3) local bone offsets at rest
rest_local_rot : (J, 4) local bone rotations at rest (quaternions)
names : (J,) joint name strings
parents : (J,) parent joint indices (-1 for root)
offsets : (J, 3) bind-pose offsets (optional — falls back to
rest_local_pos when absent)
The T-pose global positions are reconstructed via forward kinematics on the
rest pose and passed to :func:`save_skeleton_tpose_annotated`.
Modes:
- Single: ``--npz_path X`` → one PNG.
- Batch (default): ``--motions_dir M [--output_dir O]`` → one PNG per
unique key (prefix before the first ``-``) discovered in ``M``.
- Batch (face_json): ``--face_json F --motions_dir M [--source empty] [--output_dir O]``
→ one PNG per key in F whose ``source`` field matches ``--source``.
See ``data_process/scripts/run_joints_vis_tpose.sh`` for the typical batch call.
"""
import argparse
import json
import os
import sys
from pathlib import Path
import numpy as np
from tqdm import tqdm
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..', '..'))
from Animation import Animation, Quaternions, positions_global # noqa: E402
from data_process.utils.plotting import save_skeleton_tpose_annotated # noqa: E402
REQUIRED_KEYS = ("rest_local_pos", "rest_local_rot", "names", "parents")
DEFAULT_OUTPUT_DIR = "outputs/face_joints_vis"
def load_tpose_from_npz(npz_path):
"""Load rest-pose data from a motion NPZ and compute global T-pose positions.
Returns:
``(parents, joint_names, tpose_positions)`` where ``tpose_positions``
is a float32 ``(J, 3)`` array of global joint coordinates at rest.
"""
data = np.load(npz_path, allow_pickle=True)
missing = [k for k in REQUIRED_KEYS if k not in data.files]
if missing:
raise KeyError(
"{} is missing required keys {}; available: {}".format(
npz_path, missing, list(data.files)
)
)
rest_local_pos = data['rest_local_pos'] # (J, 3)
rest_local_rot = data['rest_local_rot'] # (J, 4) quaternions
parents = np.asarray(data['parents']) # (J,)
names = [str(n) for n in data['names']] # length J
# Prefer the explicit bind-pose offsets when the export recorded them;
# fall back to the rest-pose local translation when absent.
offsets = (np.asarray(data['offsets']) if 'offsets' in data.files
else rest_local_pos)
njoints = len(parents)
rest_anim = Animation(
rotations=Quaternions(rest_local_rot[None]), # (1, J, 4)
positions=rest_local_pos[None], # (1, J, 3)
orients=Quaternions.id(njoints),
offsets=offsets,
parents=parents,
)
tpose_positions = positions_global(rest_anim)[0].astype(np.float32) # (J, 3)
return parents, names, tpose_positions
def render_one(npz_path, output_path, *, font_size, joint_marker_size,
bone_linewidth):
"""Render one NPZ as an annotated T-pose PNG."""
parents, names, tpose_positions = load_tpose_from_npz(npz_path)
os.makedirs(os.path.dirname(output_path) or ".", exist_ok=True)
save_skeleton_tpose_annotated(
save_path=output_path,
parents=parents,
positions=tpose_positions,
joint_names=names,
font_size=font_size,
joint_marker_size=joint_marker_size,
bone_linewidth=bone_linewidth,
)
def find_motion_npz(motions_dir, key):
"""Resolve the first motion NPZ whose prefix-before-'-' matches ``key``.
Motion files are named ``<key>-<clip_name>.npz`` (e.g.
``669a728e57bbceb71e6b8ce6_fbx-mixamo_com.npz``). Any single clip is
enough to render the rest-pose skeleton, so we take the first sorted
match. Returns ``None`` if no file matches.
"""
hits = sorted(Path(motions_dir).glob("{}-*.npz".format(key)))
return hits[0] if hits else None
def collect_keys_from_motions_dir(motions_dir):
"""Collect unique keys (prefix before the first ``-``) from NPZs in ``motions_dir``.
NPZs without a ``-`` in their stem are treated as their own key.
"""
keys = set()
for p in Path(motions_dir).glob("*.npz"):
stem = p.stem
keys.add(stem.split("-", 1)[0] if "-" in stem else stem)
return sorted(keys)
def default_single_output_path(npz_path):
"""Default single-mode output: ``<DEFAULT_OUTPUT_DIR>/<stem>_tpose_annotated.png``."""
return os.path.join(DEFAULT_OUTPUT_DIR,
"{}_tpose_annotated.png".format(Path(npz_path).stem))
def main():
parser = argparse.ArgumentParser(
description=__doc__,
formatter_class=argparse.RawDescriptionHelpFormatter,
)
mode = parser.add_mutually_exclusive_group(required=False)
mode.add_argument(
'--npz_path', type=str, default=None,
help='Single mode: path to a motion NPZ (skips batch logic).',
)
mode.add_argument(
'--face_json', type=str, default=None,
help='Batch mode (alt): path to face_joint_names.json. Motion files '
'are matched as <motions_dir>/<key>-*.npz (prefix before the '
'first "-"). Without this flag, batch mode scans --motions_dir '
'directly for unique keys.',
)
# Batch-only
parser.add_argument(
'--motions_dir', type=str, default=None,
help='[batch] Directory of motion NPZs (default: sibling "motions/" '
'of --face_json).',
)
parser.add_argument(
'--source', type=str, default='empty',
help='[batch] Only render uuids whose "source" field equals this '
'(default: "empty"). Use "ALL" to render every key.',
)
parser.add_argument(
'--output_dir', type=str, default=DEFAULT_OUTPUT_DIR,
help='[batch] Output directory (default: {}).'.format(DEFAULT_OUTPUT_DIR),
)
parser.add_argument(
'--limit', type=int, default=None,
help='[batch] Stop after N uuids (debug aid).',
)
parser.add_argument(
'--overwrite', action='store_true',
help='[batch] Re-render even if the output PNG already exists.',
)
# Single-only
parser.add_argument(
'--output', type=str, default=None,
help='[single] Output PNG path (default: '
'<output_dir>/<input_stem>_tpose_annotated.png).',
)
# Plot knobs
parser.add_argument('--font-size', type=int, default=7,
help='Font size for joint name annotations.')
parser.add_argument('--joint-marker-size', type=float, default=80.0,
help='Joint dot marker size in points^2.')
parser.add_argument('--bone-linewidth', type=float, default=2.0,
help='Bone line width.')
args = parser.parse_args()
plot_kwargs = dict(
font_size=args.font_size,
joint_marker_size=args.joint_marker_size,
bone_linewidth=args.bone_linewidth,
)
# ── Single mode ─────────────────────────────────────────────────────────
if args.npz_path:
if not os.path.exists(args.npz_path):
parser.error("Input NPZ not found: {}".format(args.npz_path))
out = args.output or default_single_output_path(args.npz_path)
render_one(args.npz_path, out, **plot_kwargs)
print("Saved: {}".format(out))
return
# ── Batch mode: resolve the list of keys ────────────────────────────────
# face_json takes precedence when explicitly provided; otherwise we scan
# --motions_dir directly for unique keys.
if args.face_json:
if not os.path.exists(args.face_json):
parser.error("face_json not found: {}".format(args.face_json))
motions_dir = args.motions_dir or str(Path(args.face_json).parent / "motions")
if not os.path.isdir(motions_dir):
parser.error("motions_dir not found: {}".format(motions_dir))
with open(args.face_json) as f:
face = json.load(f)
if args.source == "ALL":
keys = sorted(face.keys())
else:
keys = sorted(
k for k, v in face.items()
if isinstance(v, dict) and v.get("source") == args.source
)
source_desc = "face_json={} source={!r}".format(args.face_json, args.source)
else:
if args.motions_dir is None:
parser.error("--motions_dir is required in batch mode")
motions_dir = args.motions_dir
if not os.path.isdir(motions_dir):
parser.error("motions_dir not found: {}".format(motions_dir))
keys = collect_keys_from_motions_dir(motions_dir)
source_desc = "motions_dir={}".format(motions_dir)
if args.limit is not None:
keys = keys[: args.limit]
if not keys:
print("No entries selected ({})".format(source_desc))
return
os.makedirs(args.output_dir, exist_ok=True)
print("motions_dir : {}".format(motions_dir))
print("output_dir : {}".format(args.output_dir))
print("Rendering {} T-poses ({})".format(len(keys), source_desc))
rendered = skipped_existing = missing_npz = failed = 0
missing_examples = []
failed_examples = []
for key in tqdm(keys, unit="seq", dynamic_ncols=True):
out_path = os.path.join(args.output_dir, "{}.png".format(key))
if (not args.overwrite) and os.path.exists(out_path):
skipped_existing += 1
continue
npz = find_motion_npz(motions_dir, key)
if npz is None:
missing_npz += 1
if len(missing_examples) < 5:
missing_examples.append(key)
continue
try:
render_one(str(npz), out_path, **plot_kwargs)
rendered += 1
except Exception as e: # noqa: BLE001
failed += 1
if len(failed_examples) < 5:
failed_examples.append("{}: {}".format(key, e))
print()
print("rendered : {}".format(rendered))
print("skipped (exists): {}".format(skipped_existing))
print("missing NPZ : {}".format(missing_npz))
if missing_examples:
for k in missing_examples:
print(" - {}".format(k))
if missing_npz > len(missing_examples):
print(" ... ({} total)".format(missing_npz))
print("failed : {}".format(failed))
if failed_examples:
for line in failed_examples:
print(" - {}".format(line))
if failed > len(failed_examples):
print(" ... ({} total)".format(failed))
if __name__ == '__main__':
main()