Skip to content

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

Python
13.9 KB
Raw Blame
"""Rule-based facing-direction joint selection → ``face_joint_names.json``.

For each rig this script identifies one symmetric joint pair that defines
the lateral (left-right) axis used to compute the facing direction:

  1. Search clean joint names for any symmetrical "Right <X>" / "Left <X>"
     pair, preferring anatomically meaningful joints (Thigh, Shoulder, ...).
  2. For body-axis animals (snakes like Anaconda) that lack bilateral
     symmetry, use longitudinal body-axis endpoints (tail-tip / head-tip)
     and flag ``"body_axis": true``. Stage 4 turns the tail-to-head vector
     by -90 degrees about Y before the usual cross product with Y-up, so it
     ends up as the facing direction.
  3. Animals with opaque joint names where no meaningful pair can be
     extracted get ``"source": "empty"``.

:mod:`face_select_llm` is the LLM-based complement and uses this
module both as a hint and as its fallback.

Usage:
    python -m data_process.joint_annotation.face_select_rule \
        --input_dir <export_dir> [--output PATH]
"""

import argparse
import copy
import json
import os
import re
from typing import Dict, List, Optional, Tuple

# Clean-name keywords for body-axis endpoint detection (serpentine skeletons
# and any rig with no bilateral symmetry but a clear longitudinal axis).
TAIL_KEYWORDS = {"Tail", "Tail Twist"}
HEAD_KEYWORDS = {"Head", "Skull", "Skull Base", "Head End", "Jaw",
                 "Upper Jaw", "Lower Jaw", "Tongue", "Muzzle", "Nose", "Chin"}

# Priority order for symmetrical pair search (suffix after stripping the
# "Right "/"Left " prefix). Higher entries win.
#
# Ordering rationale (top → bottom):
#   1. Hip-level limbs closest to the rig root give the most stable facing
#      axis (Thigh, Shoulder, and the quadruped "Front Shoulder"/"Back Hip"
#      markers Objaverse quadrupeds use after names_clean_rule.py).
#   2. Whole-limb roots (Upper Arm, Front Leg, Hind Leg, Wing, ...) come
#      next — they're unique per side and rarely ambiguous.
#   3. Aquatic / arthropod homologues (fins, pincers, mandibles) appear
#      where they're anatomically equivalent to the limbs above.
#   4. Mid-limb joints (Forearm, Shin, Knee, Elbow, ...) are good fallbacks
#      but drift a few cm from the true hip axis.
#   5. Extremities (Hand, Foot, Paw, Hoof, Claw) are weakest — they bend a
#      lot during motion — so they sit near the bottom.
#   6. Head-adjacent bilateral parts (Eye, Ear, Whisker, Antenna) are last
#      resorts; they give a cross-head axis, not a hip axis.
#   7. Tail is the absolute bottom (often a chain; the 'body_axis' fallback
#      uses it as a longitudinal endpoint instead).
SYMMETRIC_PAIR_PRIORITY = [
    # --- Hip / shoulder level (best) -----------------------------------
    "Thigh",
    "Shoulder",
    "Front Shoulder",  # quadruped pec (Objaverse)
    "Back Hip",        # quadruped pelvis (Objaverse)
    "Hip",
    "Scapula",
    # --- Whole-limb roots ----------------------------------------------
    "Upper Arm",
    "Arm",
    "Front Leg",
    "Hind Leg",
    "Middle Leg",      # insect / arachnid
    "Back Leg",
    "Wing",
    "Leg",
    # --- Aquatic / arthropod homologues --------------------------------
    "Pectoral Fin",
    "Pelvic Fin",
    "Fin",             # generic fish fin (L_Fin1-style rigs)
    "Gill",
    "Pincer",
    "Mandible",
    "Large Mandible",
    "Lower Mandible",
    "Stinger",
    "Claw",
    "Hand Claw",
    "Antenna",
    # --- Mid-limb joints -----------------------------------------------
    "Forearm",
    "Shin",
    "Knee",
    "Elbow",
    "Ankle",
    "Wrist",
    # --- Extremities ---------------------------------------------------
    "Hand",
    "Palm",
    "Foot",
    "Heel",
    "Front Paw",
    "Back Paw",
    "Paw",
    "Front Hoof",
    "Rear Hoof",
    "Hoof",
    "Fetlock",
    "Cannon",
    "Metacarpus",
    "Pastern",
    "Toe",
    # --- Fingers (hand-to-hand axis; both hands move, so below feet) ---
    "Thumb Finger",
    "Index Finger",
    "Middle Finger",
    "Ring Finger",
    "Pinky Finger",
    "Finger",
    # --- Coat / soft ---------------------------------------------------
    "Neck",
    # --- Head-adjacent bilateral parts (weak) --------------------------
    "Eye",
    "Eyeball",
    "Eyelid",
    "Eyebrow",
    "Ear",
    "Horn",
    "Cheek",
    "Whisker",
    "Fang",
    "Barbel",
    "Tentacle",
    "Feather",
    # --- Last resort ---------------------------------------------------
    "Tail",
]


def strip_trailing_num(name: str) -> str:
    """'Thigh 1' -> 'Thigh'."""
    return re.sub(r"\s+\d+$", "", name)


def _digit_runs(raw_name: str) -> Tuple[str, ...]:
    """All digit groups in a raw name: 'Bip01_R_Thigh_4' -> ('01', '4')."""
    return tuple(re.findall(r"\d+", raw_name))


def _match_pair_by_suffix(
    r_indices: List[int],
    l_indices: List[int],
    raw_names: List[str],
) -> Tuple[int, int]:
    """Pair one Right index with one Left index by matching raw-name digits.

    When multiple joints share the same clean name (e.g. multiple "Right
    Thigh" in Scorpion), pairs are matched by the digit signature of the raw
    name so that 'Bip01_R_Thigh_4' pairs with 'Bip01_L_Thigh_4', not
    'Bip01_L_Thigh_1'. Two tiers:

      1. Full digit signature — rigs whose mirrored bones share every index.
      2. Signature minus the LAST group — the Objaverse export stamps a
         per-joint global index on every name ('Bip01_R_Thigh_1_053' vs
         'Bip01_L_Thigh_1_054'), so the full signatures never match; dropping
         the final group compares only the chain indices.

    Falls back to the first of each side when neither tier matches.
    """
    if len(r_indices) == 1 and len(l_indices) == 1:
        return r_indices[0], l_indices[0]

    for key_fn in (lambda runs: runs, lambda runs: runs[:-1]):
        l_by_sig: Dict[Tuple[str, ...], int] = {}
        for li in l_indices:
            l_by_sig.setdefault(key_fn(_digit_runs(raw_names[li])), li)
        for ri in r_indices:
            li = l_by_sig.get(key_fn(_digit_runs(raw_names[ri])))
            if li is not None:
                return ri, li

    return r_indices[0], l_indices[0]


def find_symmetric_pair(
    clean_names: List[str],
    raw_names: List[str],
    usable=None,
) -> Tuple[Optional[int], Optional[int], Optional[str]]:
    """Find the highest-priority "Right <X>" / "Left <X>" pair.

    *usable* ``(r_idx, l_idx) -> bool`` rejects a pair (e.g. one without
    horizontal separation in the rest pose); the next part in priority order
    is tried. Returns ``(r_idx, l_idx, suffix)`` or ``(None, None, None)``.
    """
    right_map: Dict[str, List[int]] = {}
    left_map: Dict[str, List[int]] = {}
    for i, name in enumerate(clean_names):
        if name.startswith("Right "):
            right_map.setdefault(strip_trailing_num(name[6:]), []).append(i)
        elif name.startswith("Left "):
            left_map.setdefault(strip_trailing_num(name[5:]), []).append(i)

    common = set(right_map) & set(left_map)
    if not common:
        return None, None, None

    ordered = [s for s in SYMMETRIC_PAIR_PRIORITY if s in common]
    ordered += sorted(common - set(SYMMETRIC_PAIR_PRIORITY))
    for suffix in ordered:
        ri, li = _match_pair_by_suffix(right_map[suffix], left_map[suffix], raw_names)
        if usable is None or usable(ri, li):
            return ri, li, suffix
    return None, None, None


def find_body_axis_pair(
    clean_names: List[str],
) -> Tuple[Optional[int], Optional[int]]:
    """Find body-axis endpoints (tail-tip and head-end) from clean names.

    For serpentine animals without bilateral symmetry, facing direction is
    the longitudinal axis from tail-tip to head-end. Uses the last occurrence
    of each keyword set to land on the extremities.
    """
    tail_idx: Optional[int] = None
    head_idx: Optional[int] = None
    for i, name in enumerate(clean_names):
        base = strip_trailing_num(name)
        if base in TAIL_KEYWORDS:
            tail_idx = i
        if base in HEAD_KEYWORDS:
            head_idx = i
    if tail_idx is not None and head_idx is not None:
        return tail_idx, head_idx
    return None, None


# Sentinel for "no facing pair could be determined". Always hand out a
# ``copy.deepcopy`` of it — a shallow ``dict()`` copy shares the r_hip/l_hip
# sub-dicts with this module-level constant, so one in-place mutation of a
# returned entry would poison every other 'empty' entry.
EMPTY_ENTRY = {
    "r_hip": {"raw": "", "clean": ""},
    "l_hip": {"raw": "", "clean": ""},
    "source": "empty",
}


def empty_entry() -> Dict:
    """A fresh, independent copy of :data:`EMPTY_ENTRY`."""
    return copy.deepcopy(EMPTY_ENTRY)


def _make_entry(
    raw_names: List[str],
    clean_names: List[str],
    r_idx: int,
    l_idx: int,
    source: str,
) -> Dict:
    return {
        "r_hip": {"raw": raw_names[r_idx], "clean": clean_names[r_idx]},
        "l_hip": {"raw": raw_names[l_idx], "clean": clean_names[l_idx]},
        "source": source,
    }


def resolve_face_joints(
    clean_names: List[str],
    raw_names: List[str],
    usable=None,
) -> Dict:
    """Resolve one joint pair defining the facing direction (*usable*: see
    ``find_symmetric_pair``)."""
    r_idx, l_idx, suffix = find_symmetric_pair(clean_names, raw_names, usable)
    if r_idx is not None:
        return _make_entry(raw_names, clean_names, r_idx, l_idx, suffix.lower())

    # r_hip = head-end (facing toward), l_hip = tail-tip (facing away from).
    tail_idx, head_idx = find_body_axis_pair(clean_names)
    if tail_idx is not None:
        entry = _make_entry(raw_names, clean_names, head_idx, tail_idx, "body_axis")
        entry["body_axis"] = True
        return entry

    return empty_entry()


def main() -> None:
    parser = argparse.ArgumentParser(
        description=__doc__,
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    parser.add_argument(
        "--input_dir", type=str, nargs="+", required=True,
        help="Directory(ies) containing joint_names.json and clean_joint_names.json",
    )
    parser.add_argument(
        "--raw_name", type=str, default="joint_names.json",
        help="Filename of raw joint names inside each --input_dir",
    )
    parser.add_argument(
        "--clean_name", type=str, default="clean_joint_names.json",
        help="Filename of cleaned joint names inside each --input_dir",
    )
    parser.add_argument(
        "--output_name", type=str, default="face_joint_names.json",
        help="Output filename written inside each --input_dir (ignored if --output is set)",
    )
    parser.add_argument(
        "--output", type=str, default=None,
        help="Explicit output path (default: <input_dir>/<output_name> per directory)",
    )
    args = parser.parse_args()

    # A single --output cannot hold the results of several --input_dir: only
    # the last directory would survive. Make that an error instead.
    if args.output and len(args.input_dir) > 1:
        parser.error(
            "--output takes a single path but {} --input_dir were given; drop "
            "--output (use --output_name, written inside each directory) or "
            "pass one directory at a time.".format(len(args.input_dir)))

    for input_dir in args.input_dir:
        raw_path = os.path.join(input_dir, args.raw_name)
        clean_path = os.path.join(input_dir, args.clean_name)
        with open(raw_path) as f:
            raw_data = json.load(f)
        with open(clean_path) as f:
            clean_data = json.load(f)

        # Drive the loop off the RAW key set: it is the authority on which
        # object types exist, and stage 4 raises when one has no face entry.
        extra = sorted(set(clean_data) - set(raw_data))
        if extra:
            print("WARNING: {} keys in {} are absent from {} and are ignored: "
                  "{}".format(len(extra), clean_path, raw_path, extra[:5]))

        result = {}
        for animal in raw_data:
            raw_names = raw_data[animal]
            if animal not in clean_data:
                raise KeyError(
                    "{!r} is in {} but missing from {}; re-run the joint-name "
                    "cleaner so every object type has cleaned names."
                    .format(animal, raw_path, clean_path))
            clean_names = clean_data[animal]
            # clean_joint_names is indexed POSITIONALLY against raw_names, so a
            # stale/short list would silently emit an r_hip.raw taken from the
            # wrong position — a real bone name that passes stage 4's
            # membership check and yields a wrong facing axis.
            if len(clean_names) != len(raw_names):
                raise ValueError(
                    "{!r}: {} has {} cleaned names but {} has {} raw names; "
                    "{} is stale — re-run the joint-name cleaner."
                    .format(animal, clean_path, len(clean_names),
                            raw_path, len(raw_names), clean_path))
            result[animal] = resolve_face_joints(clean_names, raw_names)

        output_path = args.output or os.path.join(input_dir, args.output_name)
        with open(output_path, "w") as f:
            json.dump(result, f, indent=2)

        sources: Dict[str, List[str]] = {}
        for animal, entry in result.items():
            sources.setdefault(entry["source"], []).append(animal)

        print("Written {} entries to {}\n".format(len(result), output_path))
        for src, animals in sorted(sources.items()):
            print("  [{}] {} entries".format(src, len(animals)))
            for a in animals:
                e = result[a]
                r_clean = e["r_hip"]["clean"] or "(none)"
                l_clean = e["l_hip"]["clean"] or "(none)"
                r_raw = e["r_hip"]["raw"] or "(none)"
                l_raw = e["l_hip"]["raw"] or "(none)"
                body = " [BODY_AXIS]" if e.get("body_axis") else ""
                print("    {:20s}  r={:25s} ({}){}".format(a, r_clean, r_raw, body))
                print("    {:20s}  l={:25s} ({})".format("", l_clean, l_raw))


if __name__ == "__main__":
    main()