AI v2 B1: UniRig arbitrary categories (category hint, re-export, non-humanoid skinning)

[fernandotonon]

Part of #818 (Track B1). Status: ABSENT.

UniRig's model already handles arbitrary categories; our integration is what assumes humanoid. UniRigPredictor::Options has no category/hint field, and AutoRig::Template only offers Humanoid | Biped | Quadruped (the native template path).

Scope

• Category hint plumbed into UniRigPredictor::Options and surfaced on CLI/MCP/GUI.
• Re-export whatever the arbitrary-category path needs from upstream UniRig.
• Rigid/vehicle binding defaults (deformation quality itself is AI: Skinning v2 — Mixamo-quality auto skinning (GVB default, UniRig skin head, weight post-passes, DQS) #819's scope, not this one).

Acceptance

A CC0 wolf, car, tree and monster each auto-rig with usable skinning through GUI, CLI and MCP. Pairs with #1013 (sam2seg) / #1014 (meshseg categories) for the epic's non-human acceptance criterion.

[fernandotonon]

Blocked on #1025.

Starting this, I found that --algo unirig never actually runs the ML model: the hosted encoder.onnx emits 100% NaN latents on every input, so every call silently falls back to the Pinocchio template rig. Details and the ruled-out causes are in #1025; a diagnostic fix is in #1026.

That changes the shape of THIS issue in a useful way. My original framing — "UniRigPredictor::Options has no category field" — was right but incomplete. Reading the tokenizer, the model is already class-conditioned: the vocabulary defines cls_none=263, vroid=264, mixamo=265, articulationxl=266, and we seed the decode with articulationxl (UniRigPredictor.cpp:39, used at the embedTokens({bos, cls}) seed).

So:

• articulationxl is already the right default for arbitrary categories — it is the diverse dataset; vroid/mixamo are the humanoid-specific classes. Exposing a category hint mainly means letting a caller pick a narrower class, not unlocking non-human support.
• The real non-human blocker is that the model never runs at all. No category plumbing can be validated until UniRig: hosted encoder.onnx outputs 100% NaN latents — --algo unirig has never run the ML model #1025 is fixed, because every result currently comes from the humanoid template regardless of what is requested.

Recommend keeping this issue open but unstarted until the encoder is re-exported with parity assertions. At that point the category work is small and genuinely testable (generate with each cls token on a wolf/car/tree and compare joint counts and topology).

[fernandotonon]

Unblocked by #1047 — and the first real data

With #1025 resolved (the encoder was never broken; a corrupted local download was), --algo unirig runs. Two findings that reshape this issue:

1. There is no category conditioning to expose

UniRig's cls tokens are dataset classes, not semantic categories (configs/tokenizer/tokenizer_parts_articulationxl_256.yaml):

cls_token_id:
  vroid: 0
  mixamo: 1   # "currently untrained, do not use it"
  articulationxl: 2

articulationxl (what the C++ already seeds, token 266) is the general class covering humans, animals and articulated objects. So "category hint → model conditioning vocabulary" from the epic body has nothing to plumb; the model already rigs anything. The humanoid limitation is entirely in our post-processing.

2. What the model actually produces on non-humans (local meshes, qtmesh rig --algo unirig)

mesh	verts	joints	what our labeller did
rat (quadruped, OBJ)	30k	5	Hips/Spine/LeftUpLeg/LeftUpLeg_1/RightUpLeg
Buick Riviera (vehicle, glb)	178k	28	full humanoid names — Neck, Head, RightHand, LeftFoot… on a car; 10 unnamed
stylized oak (tree, FBX)	298k	63	humanoid names + RightArm_1… + 45 unnamed
robot (FBX)	10k	—	refused: already rigged (correct)

So the model gives plausible joint counts for the car and tree, but labelJointsAnatomically force-fits the humanoid vocabulary onto them, and the rat collapsed to 5 joints — most likely the frozen farthest-point sampling (#1046): a fixed index subset of a random surface sample loses the thin limbs/tail that FPS would keep.

Proposed scope for this issue (post-processing, not the model)

1. Category-aware labelling — --category auto|humanoid|quadruped|vehicle|vegetation|generic (GUI/CLI/MCP): humanoid keeps today's labeller; the others get a generic hierarchical naming (root, root.1.2… or per-category vocab like wheel_N/branch_N) with the humanoid heuristics gated OFF. auto = today's humanoid template check (spine + two arm chains + two leg chains) else generic.
2. Root selection per category (lowest-centroid joint for creatures; largest-part attachment for vehicles/props).
3. Rigid binding default for vehicles/props (--rigid, hard 1-bone weights; deformation quality otherwise stays AI: Skinning v2 — Mixamo-quality auto skinning (GVB default, UniRig skin head, weight post-passes, DQS) #819).
4. UniRig encoder export: farthest-point sampling was frozen at trace time (N must be ≥ 2048; larger clouds use a fixed index subset, not FPS) #1046 first or alongside — true FPS is likely what the rat needs; verify on the same four meshes.
5. CC0 validation set under tests/assets/nonhuman/ (the Bengal cat on this machine is non-commercial and cannot be committed; Quaternius/Kenney packs are the candidates).

🤖 Generated with Claude Code