scenario-maya-rigging

Maya リギング

熟練したリギングでは、あらゆる値の意味を説明でき、あらゆる動作を測定できることが重要です。関節は実際の回転中心に置いて向きを計算し、コントロールはゼロ値のまま配置を offsetParentMatrix に設定します。IK/FK とスペースの切り替えでは何も動かず、スケールや距離、ショットごとの複数キャラクター、アニメーターがすべてにキーを打つ状況にも耐えるリグを作ります。リグはビルドスクリプトとデータから生成される成果物です。ここに記載された関連スキルが利用可能なスキルにない場合は、ユーザーにインストールを依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で作業を進める場合は、ツールスキーマに基づいて進め、不足している点を明記してください。

必須の背景知識： scenario-maya-expert（実行チャネル、レビューの反復、2027 年のバージョンに関する注意点）。

モジュール scripts/mx_rig.py （sys.path.insert(0, "<skills>/scenario-maya-rigging/scripts"); import mx_rig as R）：まだ Maya では実行していません。純粋な数学処理はオフラインでテスト済みです（test_rig_offline.py）。Maya がインストールされている環境では、tests/code/maya-rigging/run_all.sh を実行し、test_rig_probe で矛盾が見つかった箇所を修正してください。

方針（熟練者ならではの違い）

• 値は整理し、それぞれの役割を一か所に集約します。 静止時の回転はゼロにし、向きは jointOrient に設定します（または、設定しません：Fragapane）。コントロールの配置は offsetParentMatrix に設定します（antCGi、Maya Learning Channel）。OPM は行列を合成します。world = local * OPM * dagParentWorld（2027 transform node）。相対的に駆動する場合は .matrix を渡します。あるいは worldMatrix に DAG 親の worldInverseMatrix を掛け、そのうえで translate、rotate、jointOrient をゼロにします。そうしないと二重に適用されます（Maya Learning Channel、antCGi の脚が逆回転する問題）。
• 目測せず、計算します。 回転が設定されている関節や子のない関節では、-orientJoint は警告なく処理をスキップします（2027 cmds.joint）。ボーンに沿う第 2 のワールド軸は一意に定まりません（antCGi のつま先）。R.joint_chain は位置から jointOrient を計算します。チェーン平面上に極を置けばドリフトはゼロになります（R.pole_vector_position）［追加］。
• 完成の基準はアニメーターが決めます。 ニュートラル状態で IK/FK を切り替えてもポップせず、アクティブなモードだけが表示され、ほかはすべてロックされている必要があります。アニメーターは「階層を選択してすべてにキーを打つ」ためです。限界点には制限を設け、四肢の動作は左右で対称にし、目と顔の向きを統一します（antCGi）。
• 制約を積み重ねる前に行列を使い、ブレンドの仕組みを理解します。 OPM、blendMatrix、pickMatrix を使えばチャンネルを自由に保てます（Maya Learning Channel は手から 20 個のジョイントを削減）。blendMatrix は順序付きのスタックで、各ターゲットがその前のターゲットを上書きします（均等な 3 分割なら、1、1/2、1/3）。parentMatrix（2025）は正規化を行い、ターゲットごとのオフセットを保存します（2027 Help）。スペースそのものではなく、スペースのオフセットターゲットをブレンドしてください。そうしないと IK が反転します（antCGi）。
• ビルド済みのリグは破棄可能なものにします。 ガイド、ビルドスクリプト、シリアライズしたウェイトと設定を用意し、修正はデータに反映します（Miquel Campos、mGear：「すべてをシリアライズし、毎回必ずクリーンな状態からビルドします」；Bungie）。チェーンの識別には名前ではなく、メタデータとジョイントラベルを使います（Bungie）。skinCluster が読み取るのはインフルエンスのワールド行列と bindPreMatrix のみです。バインドポーズをリセットし、そのためにジョイントを再ビルドしないでください（Fragapane）。
• 構造が速度を左右します。 Evaluation Graph は静的なカーブを処理対象から外し、最初に値が異なるキーで再評価します。カーブがなければ、リグは「ひどく動かなくなります」（Fragapane；Using Parallel Maya 2027）。コンポーネントを分割し、安価な計算を複製してでも、軽いグローバル処理を早く完了させます（Fragapane）。Python ノード、シーンを照会するエクスプレッション、駆動された frozen は使わず、四肢の外側にホストを配置します（Miquel Campos）。最適化の前に、DG、Serial、Parallel の結果が一致することを確認してください。
• 極端な条件でテストします。 スケール 1.24 と 1.6（antCGi）、100 万単位離れた位置と上下逆さまの状態（Fragapane）、リファレンスされた 3 体のキャラクター、ビルド中の簡易バインド（antCGi）でテストしてください。
• デフォメーション用スケルトンはコントロールリグと分離します。 エンジンに渡すのはジョイント、スキン、ブレンドシェイプのみです。原点にルートを 1 つ置き、エンジンの命名規則とジョイント数の上限を守ります（antCGi、Unreal および Unity のドキュメント、Bungie）。

最初に確認する項目

入力	変更点	指定がない場合のデフォルト（出典がある場合は［追加］）
対象	映画向けキーフレームリグか、エンジン用スケルトンか（名前、軸、インフルエンス、単一ルート）	特徴的なキーフレームリグ、カスタム
カメラ距離、スタイル	自動リガーかカスタムか、ツイストジョイントと補正ジョイント；スタイライズする場合：まず粗いプロポーションリグとアートディレクション用のペイントオーバーを作成し、初日から最終的な狙いをメモする（Miquel Campos）	ヒーローキャラクター：カスタム；群衆：Quick Rig
スケルトンの規約	エンジンアニメーションを再利用する場合、エンジンの名前と階層に合わせる必要があります	ボーンに沿ってX軸を下向きにし、ローカルZ軸で曲げ、正のZ軸で屈曲
アニメーターの規約	IK/FKのデフォルト、スペース、色、ピッカー	腕はFK、脚はIK；スペースはワールド、コグ、胸、頭；要確認
ショットの負荷	1ショットあたりのキャラクター数、密度の高いメッシュ	参照されたキャラクター3体
顔、モーションキャプチャ、予算	face to scenario-maya-deformation；HumanIK；ジョイント数とインフルエンス数	あご、目、エイムコントロール；リードに確認する（antCGi：「節約する価値があります」）

パスを選択する

Quick Rig + HumanIK	AdvancedSkeleton	mGear Shifter	カスタム（mx_rig）
+Z向きの二足歩行；ゲーム用または背景キャラクター向けの「細部まで見られない」キャラクター（Maya Learning Channel）；アニメーションをリターゲットする場合はHumanIK（2027 Help）；15ノード、厳密なTポーズ	適合スケルトンからボディと顔を作成し、適合を切り替えて再構築；Convert to BlendShapes Onlyでエンジンにエクスポート	多数のキャラクター、チーム、Unrealエクスポーター；まずOS向けの2027ビルドを確認［要確認］	ヒーローキャラクター用リグ、厳密なエンジン用スケルトン、エージェントが再構築して検証する必要があるリグ：このワークフロー

ワークフロー

1. モデルをゲートにかけます。 mx_validate.validate(profile="model") がクリーンであることを確認します。cm 単位で、仕様どおりの高さ（約 180）にし、足を y = 0 に置き、X 軸上で中央に配置し、フリーズします。目線はまっすぐ前に向け、ナックル、肘、膝にはループを設けます。 顔には口用のバッグを用意します（antCGi）。問題はリストにして差し戻します。依頼なしにクライアントのモデルを編集してはいけません。 ゲート条件：不合格なし。ワイヤーシートを確認済み。
2. ジョイントを配置します。 エッジループ上のピボットに配置します。胸郭の下に脊椎ジョイントを置き（antCGi）、手首は手のひらから分離し（Fragapane）、肘は後ろに曲げ、膝は前に曲げます。上腕と太ももの最初のツイストジョイントは肩または股関節とともに最上部に置き、中間のツイストジョイントは親の向きを保つよう位置で配置します（antCGi）。ゲート条件：どの四肢でも R.chain_plane がエラーを出さないこと。ワイヤーフレーム上のジョイントを確認済み。
3. 構築して向きを設定します。 四肢には R.joint_chain(spec, parent, up="plane")、脊椎と首には up=(0, 0, 1), up_axis="y"、ルート、重心、頭、目、足には world=[...] を使います（antCGi：アニメーター、エンジンでの足の配置）。鎖骨には end_aim= を使います。既存のスケルトンには R.orient_with_cmds を使います（脚と脊椎は 'zup'）。R.mirror_chain：四肢の動作、目と顔の向きを確認します。コントロールの回転順序を設定します（R.rotate_order(twist, main)；Fragapane）。R.set_preferred_angles(root) を使います。ゲート条件：R.rig_check(joints=bind) がクリーンであること。ミラーの誤差が 1e-3 cm 以内であること。すべての指が同じ軸と符号で曲がり、親指が固定され、1 つの属性で握り拳を作れること（antCGi）。
4. バインドスケルトンを scenario-maya-deformation に渡します（コントロールの構築中にバインドされます）。ジョイントのみ、階層は 1 つ、ラベル、rig_check の JSON を渡します。
5. コントロールリグ。 R.ikfk_limb(bind[:3], name, rig_parent, ctrl_parent, own_solver=char + "_ikRPsolver")：同じ種類のハンドルは 1 つのソルバーノードを共有するため、シーン内に複数のキャラクターがいると競合します（Fragapane：「問題が起きることがあります」、2027 Help）。脚には extra=[ball, toe], orient_end=False を指定し、その後 R.foot_pivots_from_mesh を使って R.reverse_foot を設定します。脊椎は P9 を使います。R.space_switch(ctrl, [None, cog, chest], names=[...]) を設定します。R.ikfk_match(meta, to="fk"|"ik", key=True) は保存済みのオフセットを使います（antCGi は代わりに、FK の肘の下にポールロケーターを追加し、IK の足と同じ向きにした足首ロケーターを使います）。ゲート条件：R.neutral_switch_test を実施し、ポールのずれが 1e-3 未満であること。R.space_test が期待どおりであること。FK と IK を異なるポーズにし、R.blend_sweep_test でフリップが見つからないこと。ロールスイープでかかと、ボール、つま先が順番に接地すること。共有ソルバーのエラーがないこと。コントロールがゼロ位置にあること。
6. スケールとストレッチ。 ルートスケールは、そのスケールを継承しないグループにのみ適用します。ストレッチの基準長にルートの scaleY を掛けます。IK 脊椎ジョイントはワールドピボットのスケールグループの下に配置します。segmentScaleCompensate がスケールを妨げるためです（antCGi）。ゲート条件：1.24 と 1.6 で、ニュートラル状態とストレッチ状態の両方において R.scale_test が 1e-3 cm 未満であること。
7. ロックダウンします。 R.lockdown を実行します。FK のヒンジが曲げ軸を保つこと、制限、コントローラータグ、選択セットを確認します。ゲート条件：R.lockdown_audit と R.opm_audit(rig) が空であること。リグが引き続き正常に動作すること。
8. パフォーマンス。 まずキーを設定します（R.rom_keys。使用する各属性に異なる値を 2 つ設定します）。キーのないリグはプロファイルが速く見えても、実態を反映しません。R.eval_census(rig)、R.eval_ab(bind, meshes, frames) を実行します。R.prepare_eval_graph(root=rig) はすべてのコントロールにタグを付けます（アニメーターの Preferences > Settings > Animation > Include controllers in evaluation graph を設定すると、最初のキー以降はグラフが再構築されなくなります）。さらに、セッションでカーブマネージャーを有効にします。R.gpu_override_census(meshes) を実行し、GUI の Evaluation HUD にゼロ以外の k 数が表示されることを確認します。表示されない場合は deformerEvaluator -meshes で理由を確認します。DG、Serial、Parallel、GPU Override を、リファレンスされたキャラクター 1 体と 3 体でプロファイルします。日付入りのプロファイルを保存します（Miquel Campos）。ゲート条件：センサスのエラーがないこと。各モードの結果が 1e-5 以内で一致すること。高密度メッシュがすべて GPU 上にあるか、その理由が記録されていること。
9. レビューします。 R.rom_keys を実行してから、mx_review.playblast（GUI）または R.pose_review（ヘッドレス）を使います。ショットの距離で R.precision_test を実行します。references/critique.md を参照します。ゲート条件：フレームを確認済み。肘、膝、肩、手首、足の見え方が適切であること。
10. 納品します。 新しいバージョン、クリーンな validate(profile="rig")、テスト JSON、プレイブラスト、未検証の項目を用意します。

数値

値	基準	出典
ツイストジョイント：上腕 2 個（上部、中間部）、前腕 1 個、大腿 2 個、ふくらはぎ 1 個、さらに手首と足	ボーン	antCGi
ポールロケーターを手から 30 単位離して配置。計算上のポール距離＝長い方のセグメント	肘	antCGi；[追加]
スイッチ、ドリフト、スケール誤差は 1e-3 cm 未満。中間ブレンド経路は直接角度の max(1 deg, 5%) 以内	バインドジョイント	[追加] ゲート
フットブレーク 25 deg：ボールは 25 までロールし、その後は 50 - roll。つま先は roll - 25。制限は footRoll -40..80、footBank -60..60	footRoll	antCGi
中央脊椎のツイスト減衰率 1、0.5、0.25	リボンジョイント	antCGi
精度：1e5 単位で問題が発生し、1e6 でちらつきが発生	リグの最上位ノード	Fragapane
リムの外にホストを配置：1 フレームあたり 20 ms から 17 ms へ	1 キャラクター	Miquel Campos
GPU Override：頂点数が 2000 超（NVIDIA）、500（AMD）の場合。MAYA_OPENCL_DEFORMER_MIN_VERTS を 0 にするとすべてを送信	メッシュあたり	Using Parallel Maya 2027
blendMatrix の均等な比率：1、1/2、1/3 ...。inputMatrix を数える場合：1/2、1/3 ...	順序付きスタック	2027 Help；[追加]
HumanIK は 15 ノード、Unity は 4 インフルエンス、Unreal FBX 2020.2	エンジン仕様	ドキュメント

品質ゲート

コード（mx_rig）：rig_check（静止時の回転、向き、コントロール、ポール、共有ソルバー、OPM の二重化、評価の全数調査、ロックダウン）、neutral_switch_test、blend_sweep_test、space_test、scale_test、precision_test、eval_ab、gpu_override_census、game_skeleton_check；scenario-maya-expert の validate(profile="rig")。

ビジュアル：ワイヤーフレームの正面図と側面図で配置を確認します。すべてのコントロール軸について、正面、側面、斜め前方から ROM プレイブラストを作成します。フットロールをスクラブし、極端なポーズでリグをスケーリングします。膝のポップ、肘の反転、手首のキャンディラッパー変形、肩のつぶれ、足の滑りに注意してください。

よくある間違い

間違い	発生する現象	修正方法
回転のあるジョイントに Orient Joint を実行する	何も変わらず、エラーも出ない	先に回転をフリーズするか、R.joint_chain を使います
ボーンに沿う第2ワールド軸（脚での「yup」、前向きのつま先でのワールド Z）	太ももとふくらはぎの軸が一致しない	ボーンを横切る軸を指定します。R.orient_with_cmds はこの指定を拒否します
肘や膝がまっすぐな状態	IK が誤った方向、または逆方向に曲がる	あらかじめ曲げてから再構築し、優先角を設定します
ポールがチェーンの平面から外れている、またはポールが近すぎる	拘束時に肘がずれる。手を動かすと腕が反転する	R.pole_vector_position を使い、さらに後方へ離します
移動する親の下で worldMatrix を OPM に接続する、または OPM 駆動後に値を残す	二重変換、逆方向の回転	親の worldInverseMatrix または .matrix を使います。R.bake_to_opm、R.opm_audit を使います
平均を求めるために blendMatrix のウェイトを均等にする	最後のターゲットが優先される	1、1/2、1/3 を使うか、parentMatrix ノードを使います
空間自身のマトリックスへブレンドする	コントロールがターゲットに飛び、IK が反転する	オフセットしたターゲットを使います（R.space_switch）
シーン共有のソルバーにハンドルを設定する	参照キャラクター同士が干渉する。1つの編集が全リグに影響する	キャラクターごとに own_solver を設定します
四肢の内部に設定用ホストを置く	再生が遅くなる（ノードレベルのサイクル）	四肢の親空間にホストを置きます
IK/FK ブレンドの中間で反転する	つま先や手首が途中で回転する	コンストレイントブレンド：interpType を Shortest に設定（antCGi）。マトリックスブレンド：R.blend_sweep_test で測定します
キーのないリグをプロファイリングする	アニメーション後に数値が急落する。最初のキーでカクつく	先にキーを設定します。コントローラータグと事前の設定を使います
GPU Override HUD が「Enabled (0 k)」と表示される	GPU 上で何も変形しない	R.gpu_override_census、deformerEvaluator -meshes を使います
スケールが二重に接続されている、またはストレッチが正規化されていない	スケールが二重にかかる。リグのスケールに合わせて四肢が伸びる	スケールを継承しないグループのみをスケールします。基準の長さにルートの scaleY を掛けます
グループ、ハンドル、ロケーターがロックされていない	「すべてにキー設定」でリグが壊れる	R.lockdown を使います
スプラインカーブが開始ジョイントの下にある。ヘルパーがバインドジョイントの下にある	依存関係の循環。エンジンへのエクスポートでエラーが発生する	どちらもバインドスケルトンの外に配置します

引き継ぎ

• 受け取るもの（scenario-maya-modeling または scenario-maya-retopology-uv から）：validate(profile="model") を通過したメッシュ。単位は cm、Y アップ、前方は +Z、足元は y = 0、中央揃え、フリーズ済み、対称、あらかじめ曲げた四肢、目は前向きです。
• scenario-maya-deformation へ渡すもの：バインドスケルトン（ジョイントのみ、ルートは 1 つ、向きを設定済み、回転はゼロ、ラベル付き）、rig_check JSON、バインドジョイントをコンストレイントでブレンドするか OPM でブレンドするか（ポーズリーダーがこれに依存します）。ウェイトはデータとして受け取り、修正シェイプは再接続します。
• scenario-maya-animation へ渡すもの：リファレンス用のリグ、ゼロ位置でタグ付けされたコントロール、問題のない validate(profile="rig")、スイッチ一覧、ROM プレイブラスト、既知の制限事項。
• ゲーム用リグを scenario-maya-pipeline-scripting へ渡すもの：問題のない game_skeleton_check。OPM エクスポートが実証済みでない限り、バインドはコンストレイントでブレンドします。FBX は先方でエクスポートします。

Maya 2027 に関する注意事項

• 2026 年の名称変更：addDL、multiplyDL、pointMatrixMultDL。従来の数式ノード名では単位なしノードが作成されます。condition、multiplyDivide、reverse、blendMatrix に変更はありません。
• parentMatrix（2025）には Snap と Initialize Target Offset があります。axisFromMatrix が軸ごとのノードに置き換わります。
• Orient Joint：負の主軸は 2027.1 で修正済みです。副軸の自動方向設定は 2025 以降に対応しています。
• ikHandle に表示されるのは RP、SC、スプラインのみです。スプリングおよび 2 ボーンソルバーは先に読み込んでください。FBIK は Serial を強制するため、HumanIK を使用してください。
• GPU Override：2027.2 では既知の問題として、有効時にスクラブするとクラッシュします（無効にするか、invisibility evaluator を無効にしてください）。資料で扱われているのは AMD と NVIDIA の OpenCL のみです。そのため、Apple GPU では HUD を確認してください［要検証］。エバリュエーターの設定はセッションごとで、シーンには保存されません。
• Skin Tools のレイヤーがあると、削除するまで従来のウェイトツールがブロックされます（scenario-maya-deformation）。PySide6 のみ対応しています。PyMEL は同梱されていません。

参考資料

• references/procedures.md：各段階のコードとテストです。リグコードを書く前に確認してください。
• references/expert-notes.md：専門家による判断と意見の相違です。判断基準がここに記載されていない場合に確認してください。
• references/critique.md：評価基準です。各ゲートで使用してください。
• references/gui-paths.md：メニュー、Profiler、HUD です。GUI を操作する際に確認してください。
• references/sources.md：出典、URL、タイムスタンプです。