Pose Lab

Pose Lab

Blenderで一人称視点の腕とライフルのポーズを決めるための、計測に基づく空間的な回答。

モデルは、画像から3D空間を判断するのが苦手です。ライフルのどちら側が目を向いているか、指がレシーバーの内側に入り込んでいないか、銃をどの方向に回しても排莢口を見せられないのではないか、といったことです。Pose Labは、代わりにモデルへ数値を提示します。名前付き座標系で位置を報告し、オブジェクトがどれだけ深くめり込んでいるかを示します。面がどれだけ正対しているか、目に何が見えるかを計測します。ソルバーは目標に対するライフルの動きを探索し、どの動きでも達成できない目標を報告します。アニメーションでは、同じチェック項目を使ってクリップをフレームごとにスキャンし、問題を修正します。

一人称視点シューティングゲーム用に、チャンバーのチェック処理を手作業で作る中で、これを開発しました。ある疑問の答えを得るために、Blenderを何度も実行する必要がありました。ライフルを回して、目に排莢口を見せられるのか。Pose Labなら、solveを1回呼び出すだけです。私のゲームのAKリグでは、回転だけの場合、60サンプルのうち目標を達成したものは0でした。これはジオメトリ上の事実です。目は銃身に沿って見ているからです。ライフルを回転させて移動させると、各目標を個別には達成できましたが、400サンプルの中に4つすべてを同時に満たすものはありませんでした。つまり、このチェックにはライフルの位置を変えるだけでは不十分で、新しい手のポーズが必要です。組み込みサンプルリグでは、回転だけの場合も排莢口の目標を達成したサンプルは60のうち0でしたが、回転と移動を組み合わせると、9秒ですべての目標を満たせました。

モデルに提供する情報

ツール	回答する内容
list_rigs, load_rig, describe	リグ、フレーム、符号規則、名前付きポイント、クリップ、可動パーツ
pose_idle, pose_clip, move_part, snapshot	リグをポーズにする方法：一度に1つのクリップ、キャリアを引いた状態、保存済みポーズ
move_gun	ライフルをロール、スイング、ピッチさせて移動します。腕のIKで手の保持を維持します
reach	腕のIKで手首をポイントに届かせます（前腕との干渉を避けるには、肘のポールを試してください）
turn_bone	骨を、その先端を通る軸の周りに回転させます：指の関節、手首、腕全体
where, distance	名前付きフレーム内の位置
clearance	ライフルが前腕、手のひら、指にどれだけ深く入り込んでいるかを表面までの距離と位置で測定します
purpose	すべての手が対象に対して動作します：保持（つまむ、または包む）、引く（つまむ、または引っ掛ける）、押す、パーツに添える、またはパーツに手を伸ばす。何もないところに指を曲げることはありません
anatomy	各腕が人間の腕の可動限界に収まっているかを確認します：肘、手首、各指の関節、およびポーズに違反するすべてのルール
grip	各手がライフルにどう触れているか：手の甲ではなく手のひらで触れているか、手のひら自体で保持しているか、両側でどれだけ深く入り込んでいるか
arm_ranges	可動限界の根拠となる調査内容：各関節のAAOSの可動域、機能的可動域、チェックした値、参照元
faces_eye, visible, screen	表面が目にどれだけ正対しているか、目に見える面積、画面上の位置
solve	目標に対するライフルの動きを検索します。各目標と、条件を満たしたサンプルの割合を報告します
render	コンタクトシート：プレイヤー視点と外側からのビューを並べ、各タイルにBlenderのビュー名を表示します
record_clip, load_clip	キー設定されたポーズ、またはファイル（.pose.json、FBX、BVH）からクリップを作成します
scan_clip	すべてのフレームをチェックし、最悪の値、その発生時点、失敗する時間範囲を報告します
fix_clip	問題を修正し、修正前後のスキャン結果と、修正で対応できない項目を報告します
save_clip	クリップを.pose.jsonのボーンデータと、ゲームエンジン用のFBXとして書き出します
view_cover	腕がプレイヤーの視界をどれだけ覆うかを、全体、左下、中央下の各領域について示します
solve_grip	手の保持位置を検索します：バレル上のマークに合わせた手のひらの位置、肘のポール、手のロールを調整し、握り、干渉回避、腕のルール、視界の予算を満たす保持位置を残します
retarget_clip	別のリグのクリップをこのリグに適用します。この銃固有の保持位置で手を固定し、動作を共有しつつ銃固有の握りを維持します
check_set	ゲート用にクリップの全チェックを1つのサマリーにまとめます：最悪のクリアランス、ルールに違反するフレーム、手が保持を解くフレーム

フレームと符号

すべての位置は名前付きフレームで入力・出力されるため、軸を推測する必要はありません。

• gun：銃のボーンの座標系。Unreal形式の軸、単位はcm：+Xは銃の左、+Yはバレルに沿った方向、+Zは上（デフォルト）
• arms：腕の座標系。Unreal形式の軸、単位はcm
• view：目から見た座標系、単位はcm：+Xは右、+Yは前、+Zは上

回転はプレイヤーが使う表現に合わせています：roll + は銃の右側を上げ、swing + は銃口を左に向け、pitch + は銃口を上に向けます。移動（right、forward、up）は視点基準です。

グリップを握った手は、アイドルポーズですでにライフルに触れています（指がトリガーにかかり、指がハンドガードを包みます）。基準値を得るには、pose_idleでclearanceを呼び出し、それらの部位セグメントをignoreのワイルドカードで除外してください。組み込みのサンプルでは、左の親指がアイドル時にハンドガードへ2.7 cm入り込んでいます。clearanceはライフルの表面までを測定するため（レイパリティによって内側か外側かを判定）、メッシュの角の点の間にある平面の内側に部位が入っている場合も検出できます。

腕のルール（anatomy）

ポーズがライフルを避けていても、人間の腕では取れない姿勢の場合があります。anatomy は各腕を次の制限に照らして確認します。

関節	ルール
肩	手が銃を扱っている間、肘は肩より少なくとも 2 cm 低い位置にある
肘	5～150 度で曲がるヒンジであり、まっすぐに伸ばし切らない
前腕	手の回転を担う（橈骨が尺骨の上を回る）：親指を上にした状態から、肘のヒンジ面を基準に測って、回内と回外はそれぞれ最大 80 度
前腕の皮膚	前腕のツイストボーンがあるリグでは、回転が前腕全体に分散される：1 つのリンク（肘の末端、各ツイストボーン、手首）が回転できるのは最大 50 度
手首	手首自体はひねらない。ツイストボーンのないリグでは、手のひねりはアイドル状態のグリップに対して最大 30 度
手首	前腕の軸から 30 度以内で、その可動域内にある：屈曲 80 度、伸展 70 度、橈屈 20 度、尺屈 30 度
指	各関節は手のひらに向かってのみ曲がる：ナックル -30～100 度、中節 -5～110 度、末節 -10～90 度
指	各指はそれぞれの平面内に収まる：中節はヒンジから最大 15 度、末節は中節の平面から最大 25 度
親指	ナックルは手のひらを横切る方向に -10～60 度、末節は -15～90 度曲がる。基部は人差し指の中手骨から最大 80 度広がり、手のひらの裏側に位置するのは最大 20 度

手首と肘の可動域は AAOS の通常値で、AAOS 1965 の表を Greene と Heckman 1994 が再掲載したものに基づいています。他の表では、指と親指の値が 10～25 度異なります。手首の 30 度の軸、肘の最小 5 度、肘が肩より低い位置にあるというルールは、このゲームで銃を持つ手を表現するための実用的なルールであり、関節の可動域ではありません。手首のルールは日常動作より厳しくなっています。Ryu 1991 によると、日常動作では伸展が最大 60 度、尺屈が最大 40 度使われます。指の制限は、ナックルと中節で AAOS よりも屈曲を 10 度多く許容しています。デフォルト値をこのままにする理由は docs/ANATOMY.md に記載されています。各関節の標準可動域と機能的可動域、チェック対象の値、出典（AAOS、Eaton、Morrey 1981、Palmer 1985、Ryu 1991、Hume 1990、Bain 2015、Soucie 2011）が説明されています。arm_ranges は同じデータをモデルに返します。

anatomy の応答には、各腕について、肩より下にある肘の高さ、肘の曲がり、屈曲と橈屈に分けた手首の曲がり、手首のひねり、各指の関節の曲がりとひねり、およびポーズが違反しているすべてのルールを示す bad が列挙されます。各ルールでは、報告された値をそのまま読み取ります。角度は 1 度単位、肘の高さは 0.1 cm 単位です。rigs.json のリグの limits、finger_limits、thumb_limits の各エントリは、すべての値を上書きします。solve では {"type": "anatomy"} をゴールとして指定できます。

move_gun、reach、fix_clip は、手首のひねりを伴う形で手を配置します。手のひねりを前腕に移すため、手首の関節は曲げるだけになります。手を固定したままライフルを 60 度回転させても、手首のひねりはありません。

破られたルールは、ライフル、グリップ、または肘の極の位置を動かして修正してください。関節をさらに曲げないでください。

サンプルリグのアイドル状態のグリップは、手首のルールに違反しています。左手首は前腕から 44 度、右手首は 58 度曲がっています。anatomy チェックを使って fix_clip を実行すると、左側は 29 度になります。右側は 58 度のままです。右側を修正する回転では、どれもライフルが手のひらの裏に入り込むため、その手には手首の回転ではなく、新しいグリップか肘の位置が必要です。

手の接触（grip）

手は手のひらと、指の手のひら側でライフルを握ります。clearance は通常、手のひらと指を除外して実行します。そこでは握った手がライフルに触れるためです。これにより、手が反対側にある場合も見えなくなります。grip は各手について、接触そのものを確認します。

ルール	デフォルト
ライフルに触れる手は、手の甲ではなく手のひらをライフルに向けます（palm_faces_rifle が 0 より大きい）	hold_within_cm 1.0 以内
ライフルを握る手は、指先だけでなく手のひらをライフルに当てます（palm_gap_cm）	palm_within_cm 1.5
ライフルが手の甲や各指の甲に入り込まないようにします	back_max_cm 0.1
手のひら側は少し押し込んでもかまいません。カプセル形状は手のひらより丸みがあるためです	palm_max_cm 1.0

各指の節の手のひら側は、指を曲げたときに向く側です。親指の腹は横向きなので、その接触は手のひら側の深さにのみ加算されます。結果には、各手の touching（一部でも hold_within_cm 以内にある）、holding（接触しており、手のひらがライフルを向き、表面が palm_within_cm 以内にある）、palm_gap_cm、palm_faces_rifle、palm_contact_cm、back_contact_cm、手の甲が接触している場所、および bad が含まれます。hold が true の場合、握れていない手はルール違反になります。

部品（マガジンやグリップ）を握る手は、つまむ必要もあります。grasp が true の場合、親指と指が部品の反対側から触れている（皮膚が contact_cm（0.3）以内にある）必要があり、部品表面からのそれぞれの方向のなす角は 180 - 2 atan(friction) 度以上（friction が 0.5 の場合は 127 度）でなければなりません。結果には grasping、grasp_opposition_deg、digits_touching が含まれます。ライフルに手を添える場合や、取っ手に手を引っかける場合はつまむ意図がないため、grasp は指定しないでください。solve では {"type": "grip"} をゴールとして指定し、scan_clip をチェックとして使用します。サンプルのリグでは、前腕を軸に手を 180 度回転させるとチェックに失敗します。通常の握り方でも失敗します。左手の親指はハンドガードに 2.8 cm 入り込み、右手のひらはピストルグリップに 1.2 cm 押し込まれ、引き金にかけた指の甲はトリガーガードに 0.8 cm 入り込みます。サンプルはそのままにしてあるため、ベンチマークの数値は本来の意味を保っています。

Motion：クリップのスキャンと修正

scan_clip はクリップをフレームごとに再生し、各フレームでチェックを実行します。チェック項目はソルバーの目標 （clearance、anatomy、grip、faces_eye、visible、on_screen、barrel）と、次の3つです。

• contact：手の特定の点を目印に合わせます。たとえば、指先をチャージングハンドルに合わせます（a、b、max_cm）
• hold：ref_s 時点のグリップ位置から、ライフル上で手がどれだけずれているかを確認します（side、max_cm）
• pop：フレーム間で最も速いボーン速度を測り、急な跳ねを検出します（bones、max_cm_per_s）

各チェックには during: [from_s, to_s] を指定できます。fix_clip はクリップのコピーを修正します。

• pop：良好なフレームを基に、跳ねたフレームを補間し直します
• hold：腕の IK で手をグリップ位置に戻します
• contact：手首を動かして、指定した点を目印に合わせます
• clearance：手首の位置を保ったまま、肩から手首への線を軸に各肘を必要最小限の角度で動かし、干渉を解消します。 さらに、その動きを前後のフレームにかけてなめらかにします
• anatomy：肘が肩の下にあり、曲げられる範囲内に収まるまで、同じように肘を動かします。次に、手首を可動範囲内に戻し、 各指の関節も可動範囲内に戻します。ライフルが手の甲に食い込むほど手首を回すことはありません。その方法では修正できない手首は、 そのまま残り、スキャン結果にも表示されます。手首を回すとグリップ上で手が動くため、グリップを正確な位置に保つ必要がある場合は hold チェックを追加してください。
• grip：修正しません。fix_clip は修正前後の状態を報告します。左右逆の hold は、グリップを新たに設定する必要があります。

修正前と修正後のスキャン結果を報告します。また、腕が届かない位置に手がなければならないフレームも一覧表示します。 そのような問題は、新しいポーズでしか修正できません。

examples/motion_test.py は、よくある2つの問題を含むクリップをサンプルリグで記録します。ライフルは両端だけにキーを設定した状態で 75度回転して戻るため、キーの間では手がライフルからずれます。また、1フレームで15 cm跳ねます。スキャンと修正の結果は次のとおりです。

チェック	修正前	修正後
ライフル上での左手のずれ	2.27 cm	0.48 cm
ライフル上での右手のずれ	1.67 cm	0.45 cm
手の最高速度（pop）	450 cm/s	33 cm/s
clearance	0.93 cm	0.0 cm

修正では43フレーム中34フレームを変更し、修正後はすべてのチェックに合格しました。また、左腕がグリップまで0.46 cm届かないフレームを6つ検出しました。 それでも0.5 cmの制限には合格しています。（0.3.1 より前では clearance は0.0 cmと表示されていました。コーナーの点がライフル内部の前腕に当たっていませんでした。）

インストール

Blender と Python 3.10 以降が必要です。Windows 10 で Blender 5.2.2 と Python 3.14 を使ってテストしました。 macOS、Linux、または古いバージョンの Blender ではまだテストしていません。

uvx poselab-mcp

または pip install poselab-mcp を実行してから、poselab-mcp を実行してください。

Claude Code に追加します。

claude mcp add poselab -- uvx poselab-mcp

または、任意の MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "poselab": {
      "command": "uvx",
      "args": ["poselab-mcp"],
      "env": { "POSELAB_BLENDER": "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe" }
    }
  }
}

設定

変数	説明
POSELAB_BLENDER	Blender が PATH または通常のインストールフォルダーにない場合に指定する、Blender の実行ファイル
POSELAB_RIGS	独自のリグを記述する rigs.json（examples/rigs.example.json を参照）
POSELAB_OUT	Pose Lab が書き込みを行う唯一のフォルダー（レンダリング、保存したクリップ、ワーカーのログ）。既定値は ~/.poselab

リグ

組み込みのサンプル（load_rig {"rig": "sample"}）では、ファイルは必要ありません。Pose Lab はコードから Blender 内にリグを構築します。 Unreal マネキンのボーン名を持つ2本の腕で、後方にスライドするチャージングハンドル付きの AR スタイルのライフルを持ちます。

独自のリグは FBX ファイルから作成します。腕のメッシュ、アイドルポーズ、ライフル、クリップを用意します。rigs.json（examples/rigs.example.json をコピー）に記述し、 POSELAB_RIGS にそのファイルを指定してください。クリップには、同じスケルトン上の FBX アニメーションか、ボーンデータを含む <clip>.pose.json を使用できます。 形式は {"fps": 30, "frames": [{"bone": [[x, y, z], [w, x, y, z]], ...}, ...]} で、アイドルアーマチュアに対する各ボーンのローカル位置と回転を指定します。 （Blender は自らエクスポートした FBX アニメーションを再インポートすると誤って読み取ります。これを避けるにはボーンデータを使ってください。 describe は各 FBX クリップのスケルトン適合度を報告します。）

安全性

• Pose Lab はリグファイルとクリップファイルを読み取るだけです。レンダー、保存済みクリップ、ログを書き込むのは POSELAB_OUT 内だけです。
• Blender ワーカーは空いているポートで 127.0.0.1 のみをリッスンし、セッションのランダムトークンを含むリクエストにのみ応答します。Pose Lab 独自のコマンドのみを実行します。

動作の仕組み

• poselab_mcp/server.py：MCP サーバー（公式 Python SDK、stdio）。
• poselab_mcp/worker_client.py：最初の呼び出し時にヘッドレス Blender を 1 つ起動し、リグを読み込んだままにします。
• poselab_mcp/blender/lab.py：Blender 内で、リグ、フレーム、計測、IK、ソルバー、レンダーを扱います。
• poselab_mcp/blender/sample.py：組み込みのサンプルリグです。

テスト

python examples/selftest.py

MCP クライアントと同じ方法でサーバーを起動し、サンプルリグを読み込みます。その後、上記の質問を再現します。回転だけではポートは表示されず、回転と移動を行うと表示されます。コンタクトシートは ~/.poselab/renders/sheet.png に出力されます。

python examples/motion_test.py

上記の問題のあるクリップを記録してスキャンし、修正して、~/.poselab/clips/ に roll_fixed.pose.json と roll_fixed.fbx を保存します。

blender -b -P examples/anatomy_faults.py

サンプルに既知の問題を 1 つずつ加え、チェックで見逃した場合は失敗します。横に折れ曲がった指、前腕に対してねじれた手、平らな面にめり込んだ手、指先だけの接触、バイトオーダーマーク付きのリグファイルです。これらは実際のリグのベンチマーク（下記）から取得しています。

ベンチマーク

benchmarks/ では、レンダーだけを使う場合と比べて、Pose Lab の計測を使うほうがモデルによるリグのポーズ付けが改善するかを評価します。サンプルリグに対して 5 つのタスクを実行し、Pose Lab で採点します。採点機能の確認には、スクリプト化されたオラクルと何もしない対照群を使用します。benchmarks/README.md を参照してください。

benchmarks/runs/2026-10-09-toangtown-m24 では、実際のゲーム用リグを使ってチェック自体をテストします。マガジンに手を添える 8 つのポーズのうち、7 つには既知の問題があります。Pose Lab 0.3.0 は 5 つを検出し、クリッピングの深さを実際の 40% として読み取りました。0.3.1 は 7 つすべてを検出し、深さも正確に読み取ります。

ライセンス

MIT