scenario-blender-rigging

Blender リギング

熟練したリギングとは、ボーンの配置によってリグを定義し、負荷のかかるポーズでの変形によってそれを検証し、アニメーターが実際に使うものに合わせて形作ることです。各専門家に共通する姿勢は、関節を正確に配置し、機能する最もシンプルな仕組みを生成または構築し、それからポーズを付け、測定し、レンダリングして、完成とする前に修正することです。ここに記載された兄弟スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で作業を続ける場合は、ツールのスキーマに基づいて進め、不足している点を明示してください。

必須の背景知識： scenario-blender-expert（実行チャネル、レビューループ、5.2 API の変更）。

モジュール：scripts/bx_rig.py（5.2.1 で、ヘッドレスと GUI の両方をテスト済み）。 import sys; sys.path.append("<skills>/scenario-blender-rigging/scripts"); import bx_rig as R

姿勢（専門家ならではの差）

• 配置が仕様です。 関節は、解剖学的な骨格の位置ではなく、動かすボリュームの中心に配置します（「ボーンは骨、筋肉、組織をシミュレートする」）。膝と肘にはわずかな事前の曲げを加えます。チェーンの曲率が IK 平面そのものだからです。ロールによって各ヒンジを 1 つのローカル軸上に配置し、アニメーターが 1 本のカーブを使えるようにします（CGDive。Demeter は、ポールの位置を決めたのはロールではなく曲げだと説明しています）。
• メタリグがソースであり、生成されたリグは使い捨てです。 修正はすべて、メタリグのボーン、Rigify パラメーター、または生成後スクリプトに反映します。再生成してもコントロール名は維持されるため、ウェイトとアニメーションはそのまま使えます（CGDive、Demeter、Ivan Cappiello）。
• 自動ウェイトは失敗しても通知されないことがあります。 parent_set は FINISHED を返しながら、警告では bone heat の失敗を示すことがあります。ウェイトが割り当てられていない頂点と空の変形グループを測定し、ボクセルプロキシと Data Transfer に切り替えます（CGDive、検証済み）。また、自動ウェイトは股間や脇の下をまたいで漏れるため、右半分から .L のウェイトを取り除きます。
• ウェイトは動きの中で評価し、柔らかすぎるより、しっかりした変形を目指します。 ポーズ中、またはテストアニメーションを使ってウェイトを調整します。各つなぎ目に影響するボーンは 2 本か 3 本までにします（「ボーン同士が影響力を争う」状態を避けます）。ゴムのような変形より、わずかな交差のほうが適切です。剛体パーツにはウェイトを 1.0 で割り当て、ペイントはしません（CGDive、Demeter、Dikko）。
• 一緒に変形するものはすべて、同じソースからウェイトを取得し、転送して適用します。 これにより、アニメーション中に衣服がずれるのを防げます（Dikko、CGDive）。
• 変形ツールはエクスポート先によって決まります。 Preserve Volume の代わりに、セグメントごとに 4 本のツイストボーンを使います。Preserve Volume、Corrective Smooth、B-bones は Blender 専用です。そのため Rigify は DEF ボーンをセグメントに分割します（CGDive、Ivan）。
• クライアントはアニメーターです。 誰も使わない機能は削り、リグを壊すものだけを制限し、自動化されたボーンも手動でアニメーションできるように保ちます（ドライバーの代わりに、コンストレイントと子ボーン、Mix Add、Transformation を使います）。目的に適合したら完了とします（Wayne Dixon、Demeter、CGDive）。
• 顔はキャラクターごとのハイブリッドです。 汎用的なスタイライズドフェイスはありません（Demeter）。制作現場の顔のリグでは、関節、リボン、シェイプキー、ラティスを組み合わせます（Rik Schutte）。

最初に確認すること

入力	変更内容	指定がない場合のデフォルト
対象：Blender レンダリングかゲーム／FBXか	セグメント化された DEF ボーン、最大 4 つの影響度、Preserve Volume／Corrective Smooth／B-bone 変形なし	Blender 専用のキーフレームアニメーション
キャラクター：二足歩行、四足歩行、メカ、プロップ	メタリグのプリセットまたはカスタムサンプル、剛体パーツ群	二足歩行、Rigify
顔の要件とスタイル	なし／Rigify フェイス／ボーン + シェイプキー + 顔上のコントロール	ボディリグ + 目と顎のボーンのみ
指	Rigify Human（指 + 顔）と Basic Human のどちらか	Basic Human（CGDive：最初のリグ）
ポーズ、パーツ、スケール	T ポーズまたは A ポーズ、目／歯／衣服を分離、実寸スケール	計測し、モデルのチェック時に修正
アニメーターの規約	FK／IK のデフォルト、左右の色、指のコントロール	脚は IK、腕は FK、追従 0、左は青、右は赤（要確認）

方法を選ぶ

Rigify	手動／スクリプトによるリグ
標準的な骨格の人間や動物、共通のコントロールを使う多数のキャラクター、迅速で本番品質の結果	特殊な骨格、機械部品、厳格なゲームエンジンの階層構造、小規模に保つ必要があるリグ、または依頼でカスタムコントロール方式が求められる場合
add_metarig の後に fit_metarig、generate	new_bone、twist_chain、fk_ik_switch、ik_chain、foot_roll、make_def_layer、organize
メタリグの種類：腕は正確に 3 ボーン、脚は 4 ボーン + かかと、背骨は 3 ボーン以上、super_copy は 1 ボーン	DEF／MCH／CTRL：変形するのは DEF のみ、MCH はアニメーションさせず、それ以外はすべてコントロール

ワークフロー

1. モデルのチェック。 R.model_check([body, *parts], fix=True): 変換を適用し（シェイプキーを含む）、足を Z=0 に配置し、X 軸上で中央揃えにして、-Y 方向を向かせます。成人の身長を約 1.8 m にします。Mirror モディファイアーを適用するか、ミラーオブジェクトを保持します。GATE: model_check(...)["problems"] == []。
2. ランドマーク。 lm = R.landmarks(body, eyes=eyes): 断面から股、腰、足首、首、脇、手首を特定します。目の中心は目のメッシュから、鼻先と顎は顔の輪郭から特定します。overrides={...} で任意の関節を上書きできます。GATE: 関節の順序が妥当であり、lm["notes"] が空であるか、説明されていること。
3. フィット。 Rigify: meta = R.add_metarig("basic"|"human")、R.fit_metarig(meta, lm)（関節を共有ポイントとして使用し、事前に曲げを設定し、ヒンジのロールを調整し、左側を対称化します。手と顔は類似度を基準に粗くフィットします）。手動: 同じランドマークを使い、new_bone で変形スケルトンを作成します。GATE: R.check_metarig(meta, body) == [] であり、R.placement_sheet([body, eyes], out, arm_obj=meta, views=("front","right","top")) を確認済みであること。center= と size= で頭部を拡大表示します。
4. 顔（Rigify Human）。 フィット後、R.upgrade_face(meta) を実行します（取り消し不可。まぶたの追従 Z は 0.3、下唇は 0.9、Overwrite Widget Meshes はオン）。様式化されたヒーローの顔には、代わりに顎、目、舌のボーンとシェイプキーを使います（ステージ 7）。
5. 生成または構築。 rig, err = R.generate(meta)。err は、ボーン名を含む最初の Rigify エラー行です（"Cannot connect chain - bone position is disjoint"、"Expected 2 eye corners"）。メタリグを修正して再生成します。手動: ツイストチェーン、設定プロパティ付き FK/IK レイヤー、解決済みポール角を使った IK、フットロール、対称化、mirror_drivers、make_def_layer、organize、ウィジェットを設定します。GATE（手動）: static_cycles == []、cycle_check() == []、root_test < 1e-4、レスト状態で FK と IK が一致し、ポール誤差が < 1e-3 であること。
6. バインド。 rep = R.bind(rig, body, garments=[shirt, pants], rigid={eyes: None, teeth: "DEF-teeth.T"}): 自動ウェイト、検証、プロキシへのフォールバック、反対側のストリップ、衣服への転送（適用済み）、剛体アイランド、クリーンアップと正規化、Mirror の後かつ Subdivision の前に Armature を配置します。GATE: rep["ok"]、unweighted == 0、非変形グループがないこと。エクスポートでは max_influences=4。
7. 可動範囲。 dr = R.deformation_report(rig, [body, *garments], R.RIGIFY_POSES)、R.flag_report(dr) を実行し、その後 R.pose_sheet(...) と R.joint_sheet(...) のクローズアップを作成して確認します。GATE: 貫通や説明のつかない潰れがなく、脇、肘、手首のひねり、股、膝、襟のレンダリングが許容範囲であること。
8. この順序で修正。 配置またはロールの問題: メタリグに戻って再生成します。ウェイト: 対象を絞ったデータ編集（strip_opposite_side、assign_rigid、頂点マスクを使った smooth_weights、clean_weights）。深く曲げたときのボリューム: 補正シェイプキー（volume_restore_targets、corrective_from_targets、corrective_driver）。Blender のみのキャンディラッパー: preserve_volume_mask。修正のたびにステージ 7 を再実行し、それ以前のポーズも再確認します（CGDive）。
9. 使いやすさと納品。 In Front をオフにしてコントロールが表示されること、ウィジェット、左右の色分け、MCH/DEF が非表示であること、Rigify UI の行が少なくとも 1 つあること、GUI では rig_ui.py の Auto Run が必要であること、スイッチが正確に 0 または 1 であること、レストポーズがクリーンであること、テストアクションが削除されていることを確認します。数値、レンダリング結果、未検証の項目を報告します。

数値

値	基準	出典
膝／肘の予備曲げ 1〜3 deg（フィット：四肢の長さの 1.2%、2.7 deg）；確認範囲 1〜15	曲げビューのチェーン	CGDive；確認 [追加]
4 本のツイストボーン、Copy Rotation 1.0 / 0.66 / 0.33 / 0.1（太ももは 0.05）	駆動側の端から	CGDive
IK チェーン長 2；IK Stretch 0.1；すねと前腕で IK Y/Z をロック	IK ボーン	Wayne, CGDive
フットロール：かかと X [-90, 0]、つま先 X [0, 90]、内側／外側 Z は一方向	ピボットのローカル座標、ロール 0、上向き	CGDive（検証済み）
ウェイトブラシの Add、強さ 0.1〜0.2、Auto Normalize；継ぎ目では強さ 1 で Mix 0.5	Weight Paint	CGDive
ぼかす前にほぼゼロのウェイトをクリーンアップ（Demeter）；制限値 0.001（CGDive）、bind では 0.01 [追加]；ゲームでは 4 つの影響に制限	頂点ごと	Demeter, CGDive
まぶたの追従 0.15（ボーンフェイス）；Rigify のまぶた追従 Z 0.3（デフォルト 0.7）；下顎と下唇 0.9；口角の顎への追従 0.5	顔	CGDive
手のひら 0.5 / 0.25；肘当ては前腕の回転の 0.2	Copy Rotation Local, Mix Add	CGDive
指のカール：Transformation の Scale Z 0..1 を Rot Z 90..0 deg に変換、Extrapolate	指コントロール	CGDive
アクションコンストレイント：フレーム 1 と 10 にキー、LINEAR、最大値 = 測定したコントロールの移動量	コントロールのローカル Y	CGDive, Demeter
肩のテスト範囲は鎖骨の上げ幅で約 20〜30 deg	解剖学	CGDive
顔：約 16 個の Stop Staring シェイプ；モーションキャプチャには 52 個の ARKit	シェイプキー	CGDive
プロキシのボクセルサイズ H/180、その後 H/90、H/45	キャラクターの身長	[追加、検証済み]
崩れ < 0.85、膨らみ > 1.25（関節帯）、漏れ > 0.001 H、ひずみ 0.5〜1.6	静止状態	[追加]

品質ゲート

コード（すべて bx_rig 内）：check_metarig、weight_report（ウェイトなし、empty_major、 non_deform_groups、over4、sum_dev、mirror_err）、deformation_report + flag_report（ひずみ、関節 ボリューム帯、反対側への漏れ、bx_audit による新たな自己交差）、static_cycles、cycle_check、 root_test、twist_angles、solve_pole_angle、rigid_check。

ビジュアル：生成前に配置シート（正面、右側面、上面；頭部の拡大）を作成します。RIGIFY_POSES のポーズシート（正面、右側面、斜め前）を作成します。問題が検出されたすべてのポーズについて、関節のクローズアップ（腕の関節は正面／上面／斜め前、その他は正面／右側面／斜め前）を確認します。脇の下の潰れ、尖ったりつままれたりした肘や膝、キャンディラッパー状の手首、股間や臀部のボリューム、襟のクリッピング、衣服のずれや交差、歯や目の動きの遅れ、メッシュ内部に隠れたウィジェットに注意します。テスト中、数値上は合格しても、レンダリング画像で腕の破綻や折り目の突起が見られました。必ずレンダリング画像を開いて確認してください。評価基準： references/critique.md。

エンジンとキャプチャ向けの顔の形状

フェイスキャプチャアプリ、エンジン、リップシンクツールは、シェイプキーを完全一致する名前で検索します。大文字・小文字が誤っている名前（JawOpen）や、Basis と同じ値のキーでは何もアニメーションしません。どちらも FBX と glTF のエクスポート後にそのまま残るため［検証済み］、ファイルが完成しているように見えます。

• R.SHAPE_SETS：「arkit」（Apple の 52 個の名前）と「visemes」（Meta Lipsync の 15 個、sil から U まで）があります。リスト、出典、Roblox の 50 個の FACS ポーズについては、次を参照してください。 references/face-shapes.md。
• R.shape_set(face, "arkit", rename={"JawOpen": "jawOpen"}) は名前を変更し、不足しているキーをそれぞれ値 0 で Basis のコピーとして追加し、作成した名前を返します。既存のキーは値を保持します。エクスポート前にすべてのキーを 0 に設定してください。そうしないと、静止状態で顔が変形します。
• Left キーをスカルプトしてから、R.ARKIT_52 のうち Left で終わるすべての n に対し、R.mirror_shape_key(face, n, n[:-4] + "Right") を実行して、それぞれの Right キーを作成します。
• エクスポート前に R.shape_report(face, "arkit") を実行します。ゲート条件：missing、wrong_case、side_conflicts が空で、left_is == "+X" であること。
• empty は、まだスカルプトが必要なキーの一覧です。プレースホルダーを納品する場合はこれを報告し、最終的な頭部では空にしてください。sil ビゼームはニュートラルな顔を表すため、常に empty に残します。
• 左右について：Apple のドキュメントでは、誰から見た「左」か明記せずに「左目」と記載されており、同社の顔座標空間では、顔自身から見た左が +X です。キャラクター自身の左側（+X、.L 側）に Left キーを作成し、セット全体をスカルプトする前にキャプチャを 1 回確認してください。
• Roblox のダイナミックヘッドでは、シェイプキーではなくジョイントポーズを使います。フレーム 0 はニュートラルな顔にし、フレーム 1 から各フレームに 1 つずつポーズを設定します。

よくある間違い

間違い	発生する現象	修正方法
メタリグのスケールまたはポーズが適用されていない	生成されたリグのサイズやポーズが異なる	スケールを適用し、ポーズをレストポーズとして適用する
背骨の先端を動かさずに首を動かす	「ボーンの位置が離れています」と表示される	ジョイントをひとまとまりとして動かす（move_points）
膝や肘がまっすぐになっている	IK が横向きまたは後ろ向きに曲がる	曲がる方向から見て、あらかじめ曲げておく
メタリグに親子付けされている	メッシュが有用な対象に追従しない	生成されたリグにバインドする
ヒートによる失敗に気づかない	メッシュが動かない	weight_report を使う。プロキシ経由にする
アーマチュアがサブディビジョンの下、またはミラーの前にある	処理が遅い。ミラーされた半分がポーズ適用済みの半分をコピーする	armature_first
左脚の太もものウェイトが右脚に設定されている	反対側が動く	strip_opposite_side
目と歯に自動でウェイトが設定されている	ずれたり、突き抜けたりする	assign_rigid
服にライブデータ転送が設定されている	アニメーション中にウェイトが変化する	適用する
アニメーション可能なボーンにドライバーが設定されている	チャンネルにキーを設定できない	Transformation または Copy Rotation Mix Add を使う
アイソレーションのために継承回転がオフになっている	ルートの回転で四肢が崩れる	追従ボーンを使う（World Copy Loc/Rot/Scale）
IK ターゲットがチェーン内で親子付けされている	ジッターや反転が発生する	親子関係を解除する。static_cycles を使う
接続されたボーンの親を変更する	ヘッドが新しい親のテールに移動する	reparent はまず use_connect をクリアする
ドライバーもコピーされると思って対称化する。名前が .L.001 になっている	右側が機能しない	mirror_drivers と side_of を使う
IK/FK が 0.86 のままになっている	変形が混在し、判読しづらい	値を正確に 0 または 1 にする
ARKit のキー名の誤記、または Basis のままになっている	キャプチャアプリやエンジンで何も動かない	shape_set の後に shape_report を使う

Blender 5.2 の注意事項

• Rigify は初期状態で無効です（enable_rigify）。Human メタリグには引き続きレガシーの 顔が含まれます（アップグレードしてください）。Overwrite Widget Meshes もデフォルトではオフです。
• ボーンコレクションとボーンごとの色が、レイヤーとボーングループに置き換わりました。edit_bones.new() はどの コレクションにも追加しません。ポーズ選択には pose.bones[n].select を使います。
• parent_set はアーマチュアモディファイアーを最後に追加します。ウェイト操作（vertex_group_smooth、 _clean）をヘッドレスで実行するにはウェイトペイントモードが必要です。bx_rig は代わりにデータ上でクリーンアップ、 正規化、制限を行います。
• 5.2.1 では shape_key_add により、新しいキーの値が 1.0 のままになります。駆動する前に 0 に設定してください［確認済み］。 範囲外のインデックスを指定した VertexGroup.remove は 5.2.1 でクラッシュします［確認済み］。
• 親の tail を設定すると、接続された子の head も移動します。接続された グループに対する EditBone.transform は、共有端点を二重に移動します［確認済み］。transform_bones を使ってください。
• Python ドライバーの初期キーは (0,0)、(1,1) です。再マッピングしてください（remap_driver）。アクション制約は アクションスロットを自動選択します。デフォルトで有効なのは Insert Available のみです。Python からの keyframe_insert には影響しません。
• カスタムシェイプ：Affect Gizmo（use_transform_at_custom_shape）、Use As Pivot （use_transform_around_custom_shape）。5.2 では Duplicate と Rename、および Add Bone の Axes 整列が追加されました。

参考資料

• references/procedures.md：各ステージのテスト済みコード一式と、その裏付けとなるテストスクリプトです。リグのコードを書く前に読み込んでください。
• references/expert-notes.md：配置、Rigify の内部構造、ウェイト設定、メカニズム、顔に関する専門家の判断とタイムスタンプです。上記で扱われていない判断が必要な場合に読み込んでください。
• references/critique.md：レビューの評価基準です。各ゲートで読み込んでください。
• references/face-shapes.md：ARKit、ビゼーム、Roblox FACS の名前とその出典です。エンジンやキャプチャアプリ向けに顔のシェイプ名を付ける際に読み込んでください。
• references/sources.md：動画、専門家、最適なタイムスタンプです。