Skip to content

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

Python
35.4 KB
Raw Blame
"""Rule-based joint-name cleaning: ``joint_names.json`` → ``clean_joint_names.json``.

Applies prefix stripping, CamelCase splitting, Japanese translation and
canonical anatomical vocabulary mapping. The vocabulary lives in
:mod:`vocab`; :mod:`names_clean_llm` is the LLM-based complement and uses
this module as its fallback.

Usage:
    python -m data_process.joint_annotation.names_clean_rule \
        --input <export_dir>/joint_names.json [--output ...] [--report]
"""

import argparse
import json
import os
import re
import sys
import tempfile
import unicodedata

_REPO_ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
if _REPO_ROOT not in sys.path:
    sys.path.insert(0, _REPO_ROOT)

from data_process.joint_annotation.vocab import (
    CANONICAL,
    ELK_MAP,
    FOREIGN_PARTS,
    JAPANESE_COMPOUND_ANIMALS,
    JAPANESE_COMPOUND_NAMES,
    JAPANESE_WORDS_LOWER,
    JT_MAP,
    MIXAMO_MAP,
    NPC_DIRECT,
    PIRRANA_COMPOUNDS,
    REMOVE_PREFIXES,
    SABRECAT_MAP,
    SIDE_WORDS,
    SPIDER_MAP,
    STANDALONE_MAP,
    is_canonical_label,
)


# ---------------------------------------------------------------------------
# Common helpers
# ---------------------------------------------------------------------------

# Explicit ``_L_`` / ``_R_`` / ``.L`` / ``.R`` side token: an isolated L or R
# delimited by an underscore/dot on the left and by a delimiter, a digit or
# the end of the name on the right. This is the strongest side marker a raw
# bone name carries, so it outranks a bare single-letter prefix.
_SIDE_TOKEN_RE = re.compile(r'[._]([LR])(?=[._]|\d|$)')

# A leading single L/R only marks a side when what follows reads as a word
# ("LThigh", "LEar", "LWing01") or as a short side abbreviation followed by a
# word ("LB_foot", "LT_BackFoot_09", "LFT_ankle_09"). All-caps tokens
# ("ROOT_01", "RIG_01", "LOD", "LEG", "RUG_01") and rig namespaces
# ("LP1:Head") must NOT match — there the L/R is part of the word itself.
_SINGLE_SIDE_RE = re.compile(r'^[LR](?:[A-Z][a-z]|[A-Z]{0,2}_[A-Za-z])')

# Trailing Blender/Rigify decorations: '.NNN' duplicate counters, '.NN' chain
# indices, Objaverse '_NN' global indices, '.x' center markers and '.L'/'.R'
# ('.l'/'.r') side tokens stack in any order at the end of a name
# ('thumb.01.R_037', 'Bone.005.R', 'spine_01.x', 'Index.R.001_013_6'). The
# separator requirement keeps lookup keys like 'Spine2' / 'Tail01' intact.
_TRAILING_TOKEN_RE = re.compile(r'[._](\d+|[LRlr]|x)$')

# 3ds Max Biped numeric finger codes (0-based): 'Finger0'/'Finger01' = thumb
# chain; trailing digits after the code are chain position.
_FINGER_CODE_RE = re.compile(r'^[Ff]inger([0-4])\d*(Nub)?$')
_FINGER_CODE = {"0": "Thumb", "1": "Index", "2": "Middle", "3": "Ring",
                "4": "Pinky"}
# 3ds Max CAT digits (1-based finger, then segment): 'Digit21' = index.
_DIGIT_CODE_RE = re.compile(r'^Digit([1-5])\d*$')
# CMU / mocap-style segmented fingers (1-based): 'Finger1Metacarpal' etc.
_FINGER_SEG_RE = re.compile(
    r'^[Ff]inger([1-5])(Metacarpal|Proximal|Medial|Distal|Tip)\d*$')
_FINGER_ORD = {"1": "Thumb", "2": "Index", "3": "Middle", "4": "Ring",
               "5": "Pinky"}

# 'Bone001(mirrored)' and similar editor bookkeeping — anywhere in the name,
# since the Objaverse global index can trail it: 'Bone018(mirrored)_079'.
_PAREN_DECOR_RE = re.compile(r'\s*\([^)]*\)')

# Any leading '<word>:' rig namespace ('RenWu2:', 'candi_aaaaaa2:'). Known
# ones (mixamorig:, Mutant:, Sif:) are handled earlier with their own maps.
_NAMESPACE_RE = re.compile(r'^[A-Za-z][\w .-]*:')

# Generic 3ds Max Biped container prefix: Bip01_/Bip002 /Bip01-/Bip001L...
# (any index; separator optional when a side letter follows), optionally
# behind a BN_ namespace.
_BIP_PREFIX_RE = re.compile(r'^(?:BN_)?Bip\d+(?:[-_ ]+|(?=[LR][A-Z]))')


# An end bone's name ending: 'LeftToesEND', 'Foot.L_end', 'Bip01 R Toe0Nub'.
_END_SUFFIX_RE = re.compile(r'(?:[_.\s]end|End|END|Nub)$')
# FBX ASCII escapes in names written by some exporters ('FBXASC032' = space).
_FBX_ESCAPE_RE = re.compile(r'FBXASC(\d{3})')
# Words of a raw name: capital runs ('CAT', 'R'), Capitalized or lower-case
# words, digit runs ('LowManRightUpLeg' -> Low Man Right Up Leg).
_WORD_RE = re.compile(r'[A-Z]+(?![a-z])|[A-Z]?[a-z]+|\d+')
# Leg codes of legged robots and quadruped rigs: Front / Rear / Back / Hind,
# then the side ('FR_hip', 'RL_calf', 'fl_knee'); the reviewed labels write
# every hind leg as 'Back'. Accepted only when the rest is a known part.
_LEG_CODE_RE = re.compile(r'^([FRBHfrbh])([LRlr])[_.](\w+)$')
_LEG_QUALIFIER = {'F': 'Front', 'R': 'Back', 'B': 'Back', 'H': 'Back'}


def extract_leg_code(name):
    # type: (str) -> Tuple[str, str]
    """``(side, label)`` of a leg-coded name ('RL_calf' -> Left, 'Back Shin'),
    else ``('', '')``. Runs before the generic side rules, which would read
    'RL_' as Right."""
    m = _LEG_CODE_RE.match(name)
    if not m:
        return '', ''
    label = _part_label(_WORD_RE.findall(m.group(3)))
    if not label or label == 'Bone':
        return '', ''
    return ('Left' if m.group(2).upper() == 'L' else 'Right'), \
        f'{_LEG_QUALIFIER[m.group(1).upper()]} {label}'
# A lower-case side letter glued to, or dotted onto, a part word ('rthigh',
# 'l.brazo'); accepted only when the rest is a known part.
_LOWER_SIDE_RE = re.compile(r'^([lr])[._]?([a-z]{2,})\d*$')


def _part_label(tokens):
    """Canonical label of a run of word tokens ('Up', 'Leg' -> 'Thigh';
    'Muslo' -> 'Thigh'), or '' when none of it is a known part."""
    words = [t for t in tokens if not t.isdigit()]
    if not words:
        return ''
    joined = _canon(''.join(w[:1].upper() + w[1:] for w in words))
    if joined:
        return joined
    out = []
    for w in words:
        value = _canon(w)
        if value is None:
            plain = unicodedata.normalize('NFKD', w).encode('ascii', 'ignore').decode().lower()
            value = FOREIGN_PARTS.get(plain)
        if value:
            out.append(value)
    if not out:
        # A canonical part no map lists ('hip'), when nothing else names it.
        out = [w.capitalize() for w in words
               if w.lower() not in ('end', 'nub') and is_canonical_label(w.capitalize())]
    return ' '.join(out)


def extract_inner_side(name):
    # type: (str) -> Tuple[str, str]
    """Side word inside a name that carries rig words around it, for names the
    prefix/suffix rules miss: 'LowManRightUpLeg', 'robo_RightUpLeg',
    'HumanRCollarbone', 'CATRigRLeg1', 'Muslo_Der_01', 'jambe_droite',
    'rthigh_12', 'l.brazo_1'.

    A side word (``vocab.SIDE_WORDS``, any of its languages) or a single
    capital L/R between words marks the side; the label comes from the words
    after the marker, else before it, and must be a known part (``CANONICAL``
    or ``vocab.FOREIGN_PARTS``) — rig words alone never produce a side.
    Returns ``(side, label)``, or ``('', '')``.
    """
    m = _LOWER_SIDE_RE.match(name)
    if m:
        label = _part_label([m.group(2)])
        if label and label != 'Bone':
            return ('Left' if m.group(1) == 'l' else 'Right'), label
    tokens = _WORD_RE.findall(name)
    marks, sides = [], set()
    for i, tok in enumerate(tokens):
        side = SIDE_WORDS.get(tok.lower())
        if side is None and tok in ('L', 'R') and i > 0:
            side = 'Left' if tok == 'L' else 'Right'
        if side:
            marks.append(i)
            sides.add(side)
    if len(sides) != 1:
        return '', ''
    m = re.search(r'Digit([1-5])', name)
    if m:
        return sides.pop(), _FINGER_ORD[m.group(1)] + ' Finger'
    # Words between markers, those after a marker first (a rig prefix sits
    # before the side, a Romance-language side after the part).
    bounds = [-1] + marks + [len(tokens)]
    segments = [tokens[bounds[k] + 1:bounds[k + 1]] for k in range(len(bounds) - 1)]
    labels = [_part_label(segment) for segment in segments[1:] + segments[:1]]
    labels = [label for label in labels if label and label != 'Bone']
    if not labels:
        return '', ''
    if labels[0] == 'End' and len(labels) > 1:
        # 'ankle_left_tip': the end marker after the side ends the part before it
        return sides.pop(), f'{labels[1]} End'
    return sides.pop(), labels[0]


def strip_trailing_decorations(name):
    # type: (str) -> Tuple[str, str]
    """Peel stacked trailing ``[._]``-separated tokens off *name*.

    Digit groups and ``x`` center markers are dropped; the innermost ``L``/
    ``R`` token wins as the side. Returns ``(side, base)`` with ``side`` one
    of ``""`` / ``"Left"`` / ``"Right"``.
    """
    side = ""
    while True:
        m = _TRAILING_TOKEN_RE.search(name)
        if not m:
            return side, name
        tok = m.group(1)
        if tok in ("L", "l"):
            side = "Left"
        elif tok in ("R", "r"):
            side = "Right"
        name = name[:m.start()]


def _canon(token):
    # type: (str) -> Optional[str]
    """CANONICAL lookup, tolerating all-lower/all-upper raw tokens
    ('thumb' -> 'Thumb Finger'). Exact match wins so CamelCase keys like
    'UpLeg' are never shadowed by their capitalize() form."""
    value = CANONICAL.get(token)
    if value is None and token and token != token.capitalize():
        value = CANONICAL.get(token.capitalize())
    return value


def extract_side_prefix(name):
    # type: (str) -> Tuple[str, str]
    """Extract Left/Right side from common prefix/suffix patterns.

    Handles: R_/L_ prefix, Left_/Right_ prefix, single R/L followed by
    uppercase, _L_NN/_R_NN suffix, _L/_R suffix. Guards against false
    positives on words that begin with R or L followed by a lowercase letter
    (e.g. "Ribcage", "Lower..."), on all-caps tokens that merely start with
    one ("ROOT_01", "RIG_01", "LEG") and on rig namespaces ("LP1:Head").

    Markers are ranked: an explicit ``_L_``/``_R_``/``.L``/``.R`` token beats
    a bare single-letter prefix, because rigs that carry both use the token as
    the real side ("LLeg.R_08" is the RIGHT leg, "LB_R_Shoulder_DEF" the RIGHT
    shoulder). A wrong side here silently rotates the clip 180 degrees, since
    the side flows into face_select -> get_root_facing_quat.

    Returns:
        (side, remaining_name) where side is "" | "Left" | "Right".
    """
    # Trailing Blender/Rigify decorations first: '.L'/'.R' side tokens mixed
    # with '.NNN'/'_NN' counters ('thumb.01.R_037' -> Right 'thumb'). When no
    # side is found the stripped base still flows into the prefix checks.
    side, name = strip_trailing_decorations(name)
    if side:
        # A symmetrized bone keeps its pre-mirror text: Blender renames only
        # the suffix, so 'mixamorig:LeftShoulder.R' / 'r_toe.L' carry a STALE
        # leading side word. The trailing token is the real side — drop the
        # leftover prefix so it can't pollute the vocabulary lookup.
        stripped = re.sub(
            r'^(?:Left|Right)(?=[A-Z])|^(?:Left|Right)[_ ]|^[LR][-_]|^[lr]_',
            '', name)
        return side, stripped or name

    # R_X / L_X / R-X / L-X / R.X / L.X prefix
    if re.match(r'^[RL][-_.]', name):
        side = "Left" if name[0] == "L" else "Right"
        return side, name[2:]

    # "R X" / "L X" prefix with space separator (e.g. "Bip01 L UpperArm"
    # becomes "L UpperArm" after prefix strip, then "UpperArm").
    m = re.match(r'^([RL]) +', name)
    if m:
        side = "Left" if m.group(1) == "L" else "Right"
        return side, name[m.end():]

    # Left_X or Right_X prefix (case-insensitive)
    m = re.match(r'^(Left|Right)_', name, re.IGNORECASE)
    if m:
        return m.group(1).capitalize(), name[len(m.group(0)):]

    # "Left" / "Right" directly followed by uppercase (Mixamo: LeftHandThumb1).
    m = re.match(r'^(Left|Right)(?=[A-Z])', name)
    if m:
        return m.group(1), name[len(m.group(1)):]

    # Single L/R followed by uppercase (e.g., LThigh, RArm). The weakest of
    # the side markers, so it is deliberately narrow:
    #   * an explicit _L_/_R_/.L/.R token later in the name is the real
    #     marker and wins ("LLeg.R_08" is the RIGHT leg, "LB_R_Shoulder_DEF"
    #     the RIGHT shoulder);
    #   * all-caps tokens ("ROOT_01", "RIG_01", "LEG") and rig namespaces
    #     ("LP1:Head") carry no side at all.
    if len(name) > 1 and name[0] in "LR" and name[1].isupper():
        m = _SIDE_TOKEN_RE.search(name, 1)
        if m:
            side = "Left" if m.group(1) == "L" else "Right"
            rest = (name[:m.start()] + name[m.end():]).strip("._")
            return side, rest or name
        if _SINGLE_SIDE_RE.match(name):
            side = "Left" if name[0] == "L" else "Right"
            return side, name[1:]

    # _L_NN or _R_NN suffix
    m = re.search(r'_([LR])_(\d+)$', name)
    if m:
        side = "Left" if m.group(1) == "L" else "Right"
        return side, name[:m.start()] + "_" + m.group(2)

    # _L or _R suffix
    m = re.search(r'_([LR])$', name)
    if m:
        side = "Left" if m.group(1) == "L" else "Right"
        return side, name[:m.start()]

    return "", name


def split_and_map_tokens(name):
    # type: (str) -> str
    """Split a CamelCase/underscore name and map tokens via CANONICAL.

    Tokens mapping to ``""`` (rig noise like 'Joint'/'Jnt') are dropped.
    """
    tokens = re.split(r'(?=[A-Z])|_', name)
    mapped = []
    for t in tokens:
        if not t:
            continue
        base = re.sub(r'\d+$', '', t)
        value = _canon(base)
        if value is not None:
            if value:
                mapped.append(value)
        elif base and len(base) > 1:
            mapped.append(base)
    return " ".join(mapped)


def with_side(side, result):
    # type: (str, str) -> str
    """Prepend side to result, replacing any side the mapping already carries.

    A side extracted from the raw name (``R_``/``L_``, ``_L_``/``_R_``, ...)
    is an explicit marker and outranks one baked into a vocabulary entry, so
    ``with_side("Right", "Left Wing")`` yields ``"Right Wing"`` — otherwise
    ``R_LWing`` would clean to ``Left Wing`` via ``CANONICAL["LWing"]``.
    """
    if not side:
        return result
    m = re.match(r'^(Left|Right)\b\s*', result)
    if m:
        result = result[m.end():]
    return (side + " " + result).strip()


# ---------------------------------------------------------------------------
# Skeleton-specific cleaners
# ---------------------------------------------------------------------------

def clean_japanese_name(name):
    """Handle fully Japanese joint names (Alligator, Pirrana, Tukan style)."""
    side, name = extract_side_prefix(name)

    base = re.sub(r'\d+$', '', name)
    lower = base.lower()
    if lower in JAPANESE_WORDS_LOWER:
        return with_side(side, JAPANESE_WORDS_LOWER[lower])

    # Pirrana-specific compound words (side already encoded in the value)
    if name in PIRRANA_COMPOUNDS:
        return PIRRANA_COMPOUNDS[name]

    return with_side(side, name)


def clean_prefixed_name(raw, prefix, rig_map, strip_trailing_c=False, skip_substrs=()):
    # type: (str, str, dict, bool, tuple) -> str
    """Generic cleaner for rigs with a fixed prefix and a lookup table.

    Strips ``prefix``, optionally drops a trailing ``_C`` (jt center bones),
    extracts Left/Right side, and maps via ``rig_map`` — exact match first,
    then digit-stripped base. Falls back to CANONICAL via
    :func:`split_and_map_tokens`. Names containing any of ``skip_substrs``
    (e.g. ``"Jiggle"`` for NPC physics bones) are dropped.
    """
    name = raw[len(prefix):]
    if strip_trailing_c and name.endswith("_C"):
        name = name[:-2]
    side, name = extract_side_prefix(name)

    for sub in skip_substrs:
        if sub in name:
            return ""  # post_process converts empty -> "Bone"

    result = rig_map.get(name)
    if result is None:
        result = rig_map.get(re.sub(r'\d+$', '', name))
    if result is None:
        result = split_and_map_tokens(name) or name

    return with_side(side, result).strip()


def clean_spider_name(raw):
    """Special handling for Spider skeleton names."""
    if raw in SPIDER_MAP:
        return SPIDER_MAP[raw]

    m = re.match(r'Fang([RL])_(\d+)_', raw)
    if m:
        side = "Right" if m.group(1) == "R" else "Left"
        return "{} Fang".format(side)

    m = re.match(r'Leg_([RL])_(\d)(\d)_', raw)
    if m:
        side = "Right" if m.group(1) == "R" else "Left"
        return "{} Leg".format(side)

    m = re.match(r'_([RL])Toe(\d)_', raw)
    if m:
        side = "Right" if m.group(1) == "R" else "Left"
        return "{} Leg Tip".format(side)

    return raw.strip("_")


def clean_standard_name(raw):
    """Clean standard Bip01/BN prefixed names."""
    name = _NAMESPACE_RE.sub("", raw) or raw
    name = _BIP_PREFIX_RE.sub("", name)

    for prefix in REMOVE_PREFIXES:
        if name.startswith(prefix):
            name = name[len(prefix):]
            break

    name = name.lstrip("_").strip()
    if not name:
        return raw.strip("_")

    code_side, label = extract_leg_code(name)
    if code_side:
        return with_side(code_side, label)
    side, name = extract_side_prefix(name)
    if not side:
        inner_side, label = extract_inner_side(name)
        if inner_side:
            return with_side(inner_side, label)

    # Numeric finger codes, before the chain-index strip eats the code digit:
    # CMU segments ('Finger1Metacarpal', 1-based) and 3ds Max Biped codes
    # ('Finger0'/'Finger01'/'Finger21', 0-based).
    m = _FINGER_SEG_RE.match(name)
    if m:
        label = _FINGER_ORD[m.group(1)] + " Finger"
        if m.group(2) == "Tip":
            label += " End"
        return with_side(side, label)
    m = _FINGER_CODE_RE.match(name)
    if m:
        label = _FINGER_CODE[m.group(1)] + " Finger"
        if m.group(2):
            label += " End"
        return with_side(side, label)
    m = _DIGIT_CODE_RE.match(name)
    if m:
        return with_side(side, _FINGER_ORD[m.group(1)] + " Finger")

    # Strip a trailing chain index: "Thigh_4" -> "Thigh", "Spine02" -> "Spine".
    m = re.match(r'^(.+?)_?(\d+)$', name)
    base = m.group(1).rstrip("_") if m else name

    mapped_base = _canon(base)
    if mapped_base is not None:
        # Placeholders and skip-tokens carry no side ('Bone.005.R' -> 'Bone').
        if not mapped_base or mapped_base == "Bone":
            return "Bone"
        return with_side(side, mapped_base)

    # Handle compound names with underscores
    parts = [p for p in base.split("_") if p]
    mapped = []
    for p in parts:
        # A bare L/R token only fills in a side that extract_side_prefix did
        # not already find; it must NOT override one, because the side it
        # returned came from a stronger marker (an explicit _L_/_R_/.L/.R
        # token). 'r_index_00_L_049' is the LEFT rear-paw index finger — the
        # leading 'r' means "rear", not "right".
        if p in ("L", "l"):
            side = side or "Left"
            continue
        if p in ("R", "r"):
            side = side or "Right"
            continue

        sub_base = re.sub(r'\d+$', '', p)
        sub_mapped = _canon(sub_base)
        if sub_mapped is not None:
            if sub_mapped:
                mapped.append(sub_mapped)
        elif sub_base:
            sub_tokens = [t for t in re.split(r'(?=[A-Z])', sub_base) if t]
            for st in sub_tokens:
                st_mapped = _canon(st)
                if st_mapped is not None:
                    if st_mapped:
                        mapped.append(st_mapped)
                elif st and len(st) > 1:
                    mapped.append(st)

    result = " ".join(mapped)
    if not result:
        # Nothing anatomical survived (pure counters like '1.L', skip tokens
        # like 'internal50.L') -> placeholder, without a side.
        return "Bone"
    if result == "Bone":
        return "Bone"
    return with_side(side, result).strip() or raw


# ---------------------------------------------------------------------------
# Main dispatcher
# ---------------------------------------------------------------------------

# Matches any mixamorig-style namespace: mixamorig:, mixamorig1:, mixamorig7:,
# Mixamorig1:, MIXAMORIG:, ... The trailing digits and case both vary across
# rigs but the vocabulary beneath is the same.
_MIXAMORIG_RE = re.compile(r'^mixamorig\d*[:_]', re.IGNORECASE)


def name_words(raw):
    """Words of a raw joint name for the learned vocabulary: namespace,
    Biped prefix, counters and side markers dropped, lower-cased
    ('mixamorig:LeftUpLeg_012' -> up, leg; 'JNT_Muslo_Der_01' -> jnt, muslo)."""
    name = _PAREN_DECOR_RE.sub('', raw).strip() or raw
    name = _FBX_ESCAPE_RE.sub(lambda m: chr(int(m.group(1))), name)
    name = re.sub(r'^.*:', '', name)
    name = _BIP_PREFIX_RE.sub('', name)
    _, name = strip_trailing_decorations(name)
    words = [w.lower() for w in _WORD_RE.findall(name) if not w.isdigit()]
    return [w for w in words if w not in SIDE_WORDS and w not in ('l', 'r')]


def name_keys(raw):
    """Lookup keys of a raw name, longest first: its words and every shorter
    tail of them, so a rig-specific prefix ('doberman_ref_haunch') still
    reaches a learned tail ('haunch')."""
    words = name_words(raw)
    return ['_'.join(words[i:]) for i in range(len(words))]


def _learned_vocab(_cache=[]):
    """``{name_key: part label}`` learned from reviewed annotations
    (``learned_vocab.json``, written by ``learn_vocab.py``); empty if absent."""
    if not _cache:
        path = os.path.join(os.path.dirname(__file__), 'learned_vocab.json')
        keys = {}
        if os.path.isfile(path):
            with open(path) as f:
                keys = json.load(f).get('keys', {})
        _cache.append(keys)
    return _cache[0]


def _name_side(raw):
    bare = _NAMESPACE_RE.sub('', raw) or raw
    side, _ = extract_side_prefix(_BIP_PREFIX_RE.sub('', bare))
    return side or extract_inner_side(bare)[0]


# Bookkeeping names that say nothing about the body part: a placeholder.
_GENERIC_NAMES = frozenset({'extra', 'helper', 'dummy', 'null', 'joint', 'node', 'bone'})


def clean_joint_name(raw, animal, refine=True):
    """Clean one joint name: the rules below, then (*refine*) the label
    refinements the reviewed annotations support:

    - a placeholder or non-canonical label takes the learned vocabulary's part
      for the name (``learned_vocab.json``), keeping the name's side;
    - a placeholder keeps the side its name marks ('1.L' -> 'Left Bone');
    - a name ending in ``END`` / ``_end`` / ``Nub`` is an end bone
      ('LeftToesEND' -> 'Left Toe End').

    ``refine=False`` is the label set the face resolver uses
    (``rig_preprocess.annotate.rule_annotation``).
    """
    out = _clean_joint_name_rules(raw, animal)
    if not refine or not raw or not raw.strip():
        return out
    cleaned = post_process(out)
    side_m = re.match(r'^(Left|Right) ', cleaned)
    if re.sub(r'^(Left|Right) ', '', cleaned).lower() in _GENERIC_NAMES:
        out = cleaned = with_side(side_m.group(1) if side_m else None, 'Bone')
    if cleaned == 'Bone' or not is_canonical_label(cleaned):
        vocab = _learned_vocab()
        label = next((vocab[k] for k in name_keys(raw) if k in vocab), None)
        if label:
            side = re.match(r'^(Left|Right)\b', cleaned)
            out = with_side(side.group(1) if side else _name_side(raw), label)
            cleaned = post_process(out)
    if cleaned == 'Bone':
        side, _ = strip_trailing_decorations(_PAREN_DECOR_RE.sub('', raw).strip() or raw)
        return with_side(side, 'Bone')
    if (_END_SUFFIX_RE.search(re.sub(r'[._]\d+$', '', raw)) and not cleaned.endswith(' End')
            and not re.match(r'^_?\d+$', cleaned)):
        return out + ' End'
    return out


def _clean_joint_name_rules(raw, animal):
    """Main dispatcher for cleaning a single joint name."""
    if not raw or not raw.strip():
        return raw

    # Editor bookkeeping suffixes: 'Bone001(mirrored)' -> 'Bone001'
    raw = _PAREN_DECOR_RE.sub("", raw).strip() or raw
    raw = _FBX_ESCAPE_RE.sub(lambda m: chr(int(m.group(1))), raw)

    # Generic "BoneNN" placeholders -> "Bone" (dot forms via clean_standard_name)
    if re.match(r'^Bone\d+$', raw):
        return "Bone"

    # Numeric only names — return unchanged
    if re.match(r'^_?\d+$', raw.strip("_")):
        return raw

    m = _MIXAMORIG_RE.match(raw)
    if m:
        return clean_prefixed_name(raw, m.group(0), MIXAMO_MAP)

    if raw in STANDALONE_MAP:
        return STANDALONE_MAP[raw]

    if raw in SABRECAT_MAP:
        return SABRECAT_MAP[raw]

    if animal == "Spider":
        return clean_spider_name(raw)

    if raw.startswith("Sabrecat"):
        return SABRECAT_MAP.get(raw, raw)

    if raw.startswith("NPC_"):
        return clean_prefixed_name(raw, "NPC_", NPC_DIRECT, skip_substrs=("Jiggle",))

    if raw.startswith("Elk"):
        return clean_prefixed_name(raw, "Elk", ELK_MAP)

    if raw.startswith("jt_"):
        return clean_prefixed_name(raw, "jt_", JT_MAP, strip_trailing_c=True)

    # Japanese names: strip side + trailing digits, check vocabulary
    base_lower = re.sub(r'^[RL]_', '', raw).lower()
    base_lower = re.sub(r'\d+$', '', base_lower)
    if base_lower in JAPANESE_WORDS_LOWER:
        return clean_japanese_name(raw)

    if animal in JAPANESE_COMPOUND_ANIMALS and raw in JAPANESE_COMPOUND_NAMES:
        return clean_japanese_name(raw)

    return clean_standard_name(raw)


def limb_context(labels, parents):
    """Resolve the generic limb words a rig's hierarchy disambiguates (Mixamo
    convention, which the reviewed labels follow): a ``Leg`` whose parent is
    a ``Thigh`` is the shin; an ``Arm`` with a ``Forearm`` child is the upper
    arm. Returns a new list."""
    def part(label):
        return re.sub(r'^(Left|Right) ', '', label)

    def side(label):
        m = re.match(r'^(Left|Right) ', label)
        return m.group(1) if m else ''

    out = list(labels)
    for j, label in enumerate(labels):
        p = int(parents[j])
        if part(label) == 'Leg' and p >= 0 and part(labels[p]) == 'Thigh':
            out[j] = with_side(side(label), 'Shin')
        elif part(label) == 'Arm' and any(int(parents[k]) == j and part(labels[k]) == 'Forearm'
                                          for k in range(len(labels))):
            out[j] = with_side(side(label), 'Upper Arm')
    return quadruped_leg_chains(out, parents)


# Segment labels of a quadruped leg chain, root to tip, in the Truebones
# convention the reviewed labels follow: hind legs by chain length, front
# legs after an optional shoulder (a paw tip is a 'Thumb Finger').
_HIND_CHAINS = {1: ['Thigh'], 2: ['Thigh', 'Shin'], 3: ['Thigh', 'Shin', 'Foot'],
                4: ['Thigh', 'Shin', 'Fetlock', 'Foot']}
_HIND_LONG = ['Thigh', 'Shin', 'Fetlock', 'Foot', 'Toe']
_FRONT_CHAIN = ['Upper Arm', 'Forearm', 'Hand', 'Thumb Finger']
_LEG_SEGMENT_RE = re.compile(r'^(Left|Right) (Front|Back|Hind|Rear) Leg\b(.*)$')


def _chain_labels(template, n):
    return [template[min(i, len(template) - 1)] for i in range(n)]


def quadruped_leg_chains(labels, parents):
    """Relabel leg chains named by position rather than by part
    (``Back_Leg_Upper_L`` -> 'Left Back Leg Upper'): every non-canonical
    '<Side> <Front|Back> Leg ...' joint, the joints of its chain (single
    same-side children below, a same-side Shoulder / Hips-like joint above)
    get the segment labels of their position in the chain, except joints
    that already carry a canonical part label. Chains with no such joint are
    left alone. Returns a new list."""
    parents = [int(p) for p in parents]
    children = {}
    for j, p in enumerate(parents):
        children.setdefault(p, []).append(j)
    out = list(labels)
    done = set()
    for j, label in enumerate(labels):
        m = _LEG_SEGMENT_RE.match(label)
        if j in done or not m or is_canonical_label(label):
            continue
        side, front = m.group(1), m.group(2) == 'Front'
        top = j                       # climb to the chain's first leg-segment joint
        while parents[top] >= 0:
            pm = _LEG_SEGMENT_RE.match(labels[parents[top]])
            if not (pm and pm.group(1) == side and (pm.group(2) == 'Front') == front):
                break
            top = parents[top]
        p = parents[top]
        if front and p >= 0 and labels[p] in (f'{side} Shoulder', f'{side} Clavicle'):
            top = p
        chain = [top]
        while True:
            kids = [k for k in children.get(chain[-1], [])
                    if labels[k].startswith(side + ' ')]
            if len(kids) != 1:
                break
            chain.append(kids[0])
        done.update(chain)
        ends = [labels[k].endswith(' End') for k in chain]
        core = [k for k, e in zip(chain, ends) if not e]
        if not core:
            continue
        if front:
            # A shoulder-like first joint, or one more joint than the arm
            # template names before the paw tip, is the shoulder.
            shoulder = (any(w in labels[core[0]] for w in ('Shoulder', 'Clavicle', 'Scapula'))
                        or len(core) > len(_FRONT_CHAIN))
            names = (['Shoulder'] if shoulder else []) + _chain_labels(
                _FRONT_CHAIN, len(core) - shoulder)
        else:
            names = _HIND_CHAINS.get(len(core)) or _chain_labels(_HIND_LONG, len(core))
        last = None
        for k, e in zip(chain, ends):
            if e:
                if last and _replaceable(labels[k][:-len(' End')]):
                    out[k] = with_side(side, f'{last} End')
            else:
                last = names.pop(0)
                if _replaceable(labels[k]):
                    out[k] = with_side(side, last)
                else:
                    last = re.sub(r'^(Left|Right) ', '', labels[k])
    return out


def _replaceable(label):
    """A chain joint's label the position label replaces: a positional leg
    name or any non-canonical one; a canonical part label is kept."""
    return bool(_LEG_SEGMENT_RE.match(label)) or not is_canonical_label(label)


# ---------------------------------------------------------------------------
# Post-processing
# ---------------------------------------------------------------------------

def post_process(name):
    """Final cleanup pass."""
    # rstrip only: a leading '_' marks the untouched numeric passthrough
    # names ('_00') and must survive.
    name = re.sub(r'\s+', ' ', name).strip().rstrip('._ ')

    # Strip trailing chain indices: "Tail 3" -> "Tail"
    name = re.sub(r'\s+\d+$', '', name)

    # Strip numbers before End: "Toe0 End" -> "Toe End"
    name = re.sub(r'(\w)\d+\s+End', r'\1 End', name)

    # Canonical-format rewrites for compositional leftovers. The finger
    # chain's 'Hand' segment is context, not a label word; UE/mixamo split
    # forms collapse to their canonical terms.
    name = re.sub(r'\bHand (Thumb|Index|Middle|Ring|Pinky) Finger\b', r'\1 Finger', name)
    name = re.sub(r'\b(Thumb|Index|Middle|Ring|Pinky) Finger Finger\b', r'\1 Finger', name)
    name = re.sub(r'\bFinger (Thumb|Index|Middle|Ring|Pinky) Finger\b', r'\1 Finger', name)
    name = re.sub(r'\b(?:Up|Upper) Leg$', 'Thigh', name)
    name = re.sub(r'\bLower Leg$', 'Shin', name)
    name = re.sub(r'\b(?:Lower|Fore) Arm$', 'Forearm', name)
    name = re.sub(r'\bToe Base$', 'Toe', name)
    # Trailing side word -> canonical leading position ('Index Finger Left')
    name = re.sub(r'^(?!Left |Right )(.+) (Left|Right)$', r'\2 \1', name)
    name = re.sub(r'^Head Top End$', 'Head End', name)
    name = name.replace('. ', ' ')

    # Dog-specific patches for misrouted head/spine subparts (with or
    # without the chain digit, which earlier passes may already strip)
    name = re.sub(r'^Spine ?\d* ?Tail$', 'Tail', name)
    name = re.sub(r'^Head ?\d* ?Jaw$', 'Jaw', name)
    name = re.sub(r'^Head ?\d* ?Eyelid$', 'Eyelid', name)
    name = re.sub(r'^Head Muzzle$', 'Muzzle', name)
    name = re.sub(r'^Head Jaw End$', 'Jaw End', name)
    name = re.sub(r'^Head Brain$', 'Head', name)

    # Clean leftover Bip01 fragments
    name = re.sub(r'Bip \d+ ', '', name)

    # "Spine Spine" -> "Spine"
    name = re.sub(r'^(\w+) \1$', r'\1', name)

    if re.match(r'^Xtra', name):
        name = "Bone"

    name = re.sub(r'Ponytail\d*.*', 'Appendage', name)

    # Title case consistency: "Right leg" -> "Right Leg"
    words = name.split()
    name = " ".join(w.capitalize() if w[0].islower() and len(w) > 1 else w for w in words)

    name = re.sub(r'^Spine (Left|Right) Wing$', r'\1 Wing', name)
    name = re.sub(r'\s+\d+$', '', name)

    if not name:
        return "Bone"
    return name


# ---------------------------------------------------------------------------
# Coverage reporting
# ---------------------------------------------------------------------------

_UNMAPPED_PATTERN = re.compile(r'[_\d]|[a-z]{2,}[A-Z]')


def _looks_unmapped(cleaned):
    """Heuristic: residual underscores, digits, or CamelCase runs suggest
    the name fell through the rules without hitting a canonical mapping."""
    return bool(_UNMAPPED_PATTERN.search(cleaned))


def report_coverage(clean_data):
    """Per-rig conformance to the shared canonical label format
    (:func:`vocab.is_canonical_label`); 'Bone' counts as conforming."""
    from data_process.joint_annotation.vocab import is_canonical_label
    total = 0
    unmapped = 0
    print("\n=== Canonical-format report ===")
    for animal, labels in clean_data.items():
        bad = [l for l in labels
               if l != "Bone" and not is_canonical_label(l)]
        total += len(labels)
        unmapped += len(bad)
        if bad:
            preview = ", ".join(sorted(set(bad))[:5])
            print("  {:20s} {:3d}/{:3d} residual: {}".format(
                animal, len(bad), len(labels), preview))
    pct = 100.0 * (1 - unmapped / max(total, 1))
    print("Overall: {}/{} labels clean ({:.1f}%)".format(
        total - unmapped, total, pct))


# ---------------------------------------------------------------------------
# CLI
# ---------------------------------------------------------------------------

def main():
    parser = argparse.ArgumentParser(description="Rule-based joint-name cleaning.")
    parser.add_argument("--input", required=True,
                        help="Path to the raw joint_names.json")
    parser.add_argument("--output", default=None,
                        help="Output path (default: sibling 'clean_joint_names.json')")
    parser.add_argument("--report", action="store_true",
                        help="Print a per-rig coverage report")
    args = parser.parse_args()

    input_path = args.input
    output_path = args.output or os.path.join(
        os.path.dirname(input_path), "clean_joint_names.json")

    with open(input_path, "r") as f:
        data = json.load(f)

    clean_data = {}
    for animal, joints in data.items():
        clean_data[animal] = [post_process(clean_joint_name(j, animal)) for j in joints]

    # Atomic write (temp file + os.replace), like every other annotation
    # writer: a crash mid-dump must not leave a truncated
    # clean_joint_names.json that the LLM pass would then "resume" from.
    fd, tmp = tempfile.mkstemp(prefix=os.path.basename(output_path) + ".",
                               suffix=".tmp",
                               dir=os.path.dirname(output_path) or ".")
    try:
        with os.fdopen(fd, "w") as f:
            json.dump(clean_data, f, indent=2)
        os.replace(tmp, output_path)
    except BaseException:
        if os.path.exists(tmp):
            os.unlink(tmp)
        raise

    print("Written {} entries to {}".format(len(clean_data), output_path))

    for animal in list(data.keys())[:5]:
        print("\n--- {} ---".format(animal))
        for raw, clean in zip(data[animal], clean_data[animal]):
            print("  {:50s} -> {}".format(raw, clean))

    if args.report:
        report_coverage(clean_data)


if __name__ == "__main__":
    main()