unirig

unirig — 3D リギングの自動化（スケルトン → スキン → マージ）

キーワード：unirig · auto-rigging · skeleton prediction · skinning weights

ユーザーに変更のライセンスがあるアセットのみをリギングしてください。UniRig は MIT ライセンスですが、そのチェックポイント、Rig-XL／VRoid／Objaverse のデータ、ユーザー自身のモデルには、それぞれ個別の利用条件があります。

UniRig は 2 段階の自己回帰型リギングフレームワークです。GPT のようなトランスフォーマーがメッシュ形状からトポロジー的に妥当なスケルトンを予測し、続いてボーン点クロスアテンションモデルが頂点ごとのスキニングウェイトを予測します。3 段階目では、予測したリグを元の（高解像度でテクスチャ付きの）アセットにマージします。

最もよくある失敗は、マージ段階を省略すること、または間違ったファイルをマージすることです。ステップ 5 を参照してください。次によくある失敗は、環境に CUDA 拡張機能がひそかに欠けていることです。

このスキルを使用する場合

• 静的な 3D キャラクター／クリーチャー／プロップをリギング済みアセットにしたい
• スケルトンのみが必要、またはすでに編集したスケルトン用のスキンウェイトが必要
• CUDA マシンに UniRig をインストールして動作確認したい、または自分のマシンで実行できないことを事前に確認したい
• モデルのディレクトリを一括でリギングしたい
• UniRig、その後継の SkinTokens、従来型／ホスト型のリギングツールの中から選びたい
• リギング済みの出力があり、ジョイントとスキンウェイトが実際に反映されたか確認したい

手順

ステップ 1：事前確認事項を集め、段階を選ぶ

実行前に、次の 4 点を確認してください。

• アセット：ファイル形式（.obj、.fbx／.FBX、.dae、.glb、.gltf、.vrm）、ポリゴン数、単体モデルかディレクトリか、テクスチャの有無
• 目的：スケルトンのみ、スキンのみ、またはリギング済みの成果物
• ハードウェア：NVIDIA GPU と CUDA のバージョン、VRAM、OS（CUDA がなければ推論不可のため、別の方法へ案内）
• 制約：インストールにかけられる労力（UniRig には spconv、flash_attn、torch_scatter、 torch_cluster、bpy が必要）、およびスケルトンを手作業で制御する必要があるか

振り分けルール：

1. スケルトンのない静的メッシュ → スケルトン段階（--stage skeleton）
2. スケルトンがある（予測済み、または手動編集済み）→ スキン段階（--stage skin）
3. 元のジオメトリ／マテリアルを保持する必要がある成果物 → マージ段階（--stage merge）
4. 3 段階すべてを一度に実行 → --stage all（scripts/rig.sh のデフォルト）
5. CUDA GPU がない、またはアーティストが名前／IK／制約を制御する必要がある → 別の方法へ案内 （references/route-outs-and-troubleshooting.md を参照）

ステップ 2：インストール前に環境を確認する

bash scripts/doctor.sh            # human-readable readiness report
bash scripts/doctor.sh --json     # machine-readable, for agent branching

doctor.sh は、Python 3.11、torch と CUDA の利用可否、spconv、torch_scatter、 torch_cluster、flash_attn、bpy、trimesh、UniRig のチェックアウト、launch/inference スクリプト、Hugging Face への接続可否を報告します。実行を妨げる項目が不足している場合は終了コード 1 を返すため、エージェントは実行できないリグを約束する前に作業を中止できます。チェックアウトが ~/.cache/unirig/UniRig にない場合は、--unirig-home <path>（または UNIRIG_HOME）を使用してください。

ステップ 3：スキルをインストールし、マシンの条件を満たしている場合は上流リポジトリもインストールする

npx skills add https://github.com/akillness/jeo-skills --skill unirig

bash scripts/install.sh --repo-only          # clone/update UniRig only
bash scripts/install.sh --cuda cu121         # clone + create venv + install deps
bash scripts/install.sh --cuda cu121 --torch 2.4.0 --vrm

インストーラーは、意図的に慎重な動作をするよう設計されています。

• --force が指定されていない限り、nvidia-smi がないマシンには CUDA 専用のホイールをインストールしません。
• spconv-<cuda> と PyG のホイールインデックスは --cuda／--torch から導出されます。単一の固定ホイールを推測するのではなく、上流 README に合わせます。
• flash_attn は最後に試行され、失敗は握りつぶされずに報告されます。ソースからビルドする方法については、トラブルシューティングのリファレンスを参照してください。
• --vrm を指定すると、同梱の Blender VRM アドオンも登録されます。

依存関係の詳細は references/environment-and-install.md を参照してください。

ステップ 4：ドライランで実行計画を確認してから実行する

# print the exact upstream commands without executing them
bash scripts/rig.sh --input examples/giraffe.glb --output results/giraffe_rigged.glb --dry-run

# run the whole pipeline (skeleton → skin → merge)
bash scripts/rig.sh --input examples/giraffe.glb --output results/giraffe_rigged.glb

# one stage at a time
bash scripts/rig.sh --stage skeleton --input model.glb --output results/model_skeleton.fbx
bash scripts/rig.sh --stage skin --input results/model_skeleton.fbx --output results/model_skin.fbx
bash scripts/rig.sh --stage merge --source results/model_skin.fbx --target model.glb \
  --output results/model_rigged.glb

# whole directory (skeleton and skin stages only — upstream merge takes one file pair)
bash scripts/rig.sh --stage skeleton --input-dir assets/ --output-dir results/skeletons/

rig.sh は、launch/inference/generate_skeleton.sh、generate_skin.sh、merge.sh を呼び出す、薄く誠実なラッパーです。入力の拡張子を検証し、最終出力と同じ場所に中間ファイルのパス <input>_skeleton.fbx ／ <input>_skin.fbx を生成します（--skeleton-out ／ --skin-out で上書きできます）。UNIRIG_HOME から各ステージを順番に実行し、予想される成果物が見つからない場合は、実際には書き出されていないリグを報告することなく失敗します。--seed、--faces-target-count、--num-runs、--add-root、--force-override、--skeleton-task、--skin-task は、上流のデフォルト値も含め、そのまま上流に渡されます。

ステップ 5：2 つのマージルールを守る

1. スケルトンファイルではなく、スキンファイルをマージします。 merge.sh --source <skeleton>.fbx は、スキニングウェイトのないアーマチュアを生成します。納品可能なリグには、*_skin.fbx の出力を使用してください。
2. スキニングの前にスケルトンを修正します。 ボーン（尾、翼、余分な四肢など）が欠けていると、スキンの品質は大きく低下します。Blender で予測されたスケルトンを手動編集してから、編集済みの FBX に対して --stage skin を再実行してください。異なる --seed 値を指定すると異なるスケルトン候補が生成されるため、確定前にいくつか試すのは手軽です。

ステージのフラグ、デフォルト値、設定ファイル、tmp/ の npz キャッシュについては、references/inference-pipeline.md に記載されています。

ステップ 6：納品物を実際に検証し、決めつけない

python3 scripts/inspect_glb.py results/model_rigged.glb
python3 scripts/inspect_glb.py results/model_rigged.glb --json

inspect_glb.py は標準ライブラリのみで動作します（torch も Blender も不要です）。GLB／glTF の JSON チャンクを解析し、メッシュ、ノード、skins、ジョイント数、アニメーション、およびメッシュプリミティブに JOINTS_0／WEIGHTS_0 属性が含まれているかどうかを報告します。ファイルにスキンがない場合は終了コード 1 を返します。これはまさに「誤ってスケルトンファイルをマージした」ケースです。FBX の出力は、Blender または bpy で確認してください（トラブルシューティングのリファレンスを参照）。FBX はバイナリ形式のため、標準ライブラリのみでは解析できません。

ステップ 7：トレーニングとデータセット（依頼された場合のみ）

トレーニング、Rig-XL／VRoid のデータレイアウト、raw_data.npz のキーのスキーマ、Rignet の検証タスクについては、references/training-and-datasets.md に記載されています。推論だけが必要な依頼では、トレーニングを開始しないでください。公開済みのチェックポイントは、初回の推論時に自動でダウンロードされます。

例

例 1：「この GLB キャラクターにリグを設定してください」

doctor.sh → rig.sh --dry-run で計画を表示 → rig.sh → inspect_glb.py で出力にスキンとジョイントがあることを確認します。

例 2：「尾にボーンがありません」

問題のあるスケルトンに対してスキニングを再実行しないでください。別の --seed で再サンプリングするか、Blender でスケルトンの FBX を編集してから、編集済みのファイルに対して --stage skin を実行し、再度マージしてください。

例 3：「MacBook を使っています」

doctor.sh はブロック状態で終了します。そのことを率直に伝え、CUDA マシン／クラウド GPU、ホスト型の Tripo リギングサービス、または従来型の Mixamo／AccuRig／Rigify に案内してください。CPU フォールバックがあるかのように装わないでください。

例 4：「UniRig と SkinTokens のどちらが優れていますか？」

SkinTokens は同じ研究室による後継モデルです（統合された自己回帰型スキントークンを使用し、強化学習でトレーニングされ、スキニングで 98～133％、ボーン予測で 17～22％の向上が報告されています）。新しい作業には SkinTokens を推奨してください。ユーザーが公開済みチェックポイント、Rig-XL のツール群、またはすでに動作している環境を必要とする場合は、UniRig を引き続き使用してください。

チェックリスト

1. シェルに触れる前に、アセット／目標／ハードウェア／制約の情報を収集します。
2. 最初に doctor.sh を実行し、ブロック要因のある環境では、やみくもにインストールせず、その旨を報告します。
3. NVIDIA GPU のないマシンには、CUDA 専用の wheel を決してインストールしません。
4. 長時間の GPU 実行の前に、パイプラインをドライランし、上流の正確なコマンドを提示します。
5. スキニングの前にスケルトンを修正します。トポロジーがおかしい場合は、シードをサンプリングします。
6. 元のアセットには *_skeleton.fbx ではなく、*_skin.fbx をマージします。
7. inspect_glb.py（GLB）または Blender（FBX）で成果物を検証します。コマンドの終了コードだけを根拠に成功を主張してはいけません。
8. UniRig が適切なツールでない場合は、SkinTokens、ホステッドサービス、または従来型のリガーを正直に案内します。

参考資料

• references/environment-and-install.md — Python 3.11、torch/CUDA の対応表、spconv/PyG/flash_attn の注意点、チェックポイント、VRM アドオン
• references/inference-pipeline.md — 抽出／スケルトン／スキン／マージに関するすべての上流フラグとデフォルト、設定、tmp/ の npz キャッシュ
• references/training-and-datasets.md — Rig-XL/VRoid データ、raw_data.npz スキーマ、設定の階層化、トレーニングと Rignet の検証タスク
• references/route-outs-and-troubleshooting.md — UniRig を使わない方がよい場合と、繰り返し発生するインストール／実行時エラー
• scripts/doctor.sh — 準備状況のレポート（--json、ブロック時は終了コード 1）
• scripts/install.sh — スキルプラグインと、上流リポジトリのクローン／venv／依存関係
• scripts/rig.sh — --dry-run 対応のステージ認識型ラッパー
• scripts/inspect_glb.py — 標準ライブラリを使った GLB/glTF リグ検証ツール
• UniRig repository · 論文 · チェックポイント · 後継の SkinTokens