blender-animation-rigging

Blender アニメーション＆リギングのエキスパート

概要

このスキルでは、Blender 5.x のアニメーションとリギングに関する専門的なガイダンスを提供します。キーフレーム設定、FCurve の編集、ドライバー、ボーンコンストレイント、アーマチュアの作成、IK/FK チェーン、シェイプキー、NLA ストリップ、アニメーションワークフローの Python による自動化を扱います。5.1 の変更点（Smooth Gaussian FCurve モディファイアー、Apply to Basis、レイヤーアクションのパフォーマンス）も含まれます。リファレンスファイルには、コンストレイントの全カタログと Python API のパターンが含まれています。

MCP 優先のアプローチ

キーフレームの挿入、アーマチュアの作成、コンストレイントの接続、実行中の Blender セッションでのアクションのベイクには、公式 Blender MCP サーバー（Blender Lab、Blender 5.1 以降）を優先してください。MCP サーバーに接続されていない場合に限り、Python スクリプトの出力に切り替えてください。

検出方法： セッションの開始時に、名前が execute_blender_code、get_objects_summary、または search_api_docs に一致するツールを探してください。これらは公式の blender-mcp サーバーに属します。いずれかが存在する場合、MCP を利用できます。

このスキルで使用するツール：

• execute_blender_code — ライブセッションで bpy Python を実行します（主要なアクション）
• get_objects_summary、get_object_detail_summary — 変更前にシーンの状態を確認します
• get_blendfile_summary_datablocks / _missing_files / _of_linked_libraries / _path_info / _usage_guess — ファイルの内容を一覧表示します
• search_api_docs、get_python_api_docs、search_manual_docs — 呼び出す前に正しい API／オペレーター名を確認します
• get_screenshot_of_window_as_image / _as_json、get_screenshot_of_area_as_image — スクリーンショットまたは要約ツールで視覚的な結果を確認します
• jump_to_tab_by_name、jump_to_tab_by_space_type、jump_to_view3d_object_by_name、jump_to_view3d_object_data_by_name — UI を操作して、変更が見えるようにします
• render_thumbnail_to_path、render_viewport_to_path — すばやく視覚的なフィードバックを取得します

ワークフロー： get_* / search_* ツールで確認 → execute_blender_code で変更 → スクリーンショットまたは要約ツールで検証します。失敗箇所を特定しやすくするため、コードブロックは小さく、冪等性を保ってください。

セットアップについては、docs/blender-mcp-setup.md を参照してください。

タスクの判断ツリー

• 「オブジェクト X をアニメーション化する」 → キーフレーム挿入のパターンを使用します（「キーフレームのパターン」を参照）
• 「リグ／アーマチュアを作成する」 → 「アーマチュアの作成」セクションと references/python_api.md を参照します
• 「IK を設定する」 → 「IK チェーンの設定」を参照します
• 「ドライバーを作成する」 → 「ドライバーのレシピ」を参照します
• 「コンストレイントを追加する」 → 正しいタイプとプロパティについて references/constraint_reference.md を参照します
• 「シェイプキーを操作する」 → 「シェイプキーのパターン」を参照します
• 「NLA エディターを使用する」 → 「NLA の管理」を参照します
• 「FCurve を編集する」 → references/python_api.md の「FCurve の操作」を参照します
• 「ボーンのロール／向きが正しくない」 → 「モード切り替え時の注意点」を参照します

Blender 5.1 の変更点

Smooth（ガウス）FCurve モディファイアー（5.1 の新機能）

1. 新しい FCurve モディファイアータイプ：ブレンドモード 'GAUSSIAN' を備えた 'SMOOTH'
2. 従来の Smooth モディファイアーより滑らかな補間を提供します
3. Python では fcurve.modifiers.new('Smooth', 'SMOOTH') を適用し、その後ブレンドタイプを設定します
4. モーションキャプチャーデータのジッター低減に役立ちます

Apply to Basis（5.1 の新機能）

1. 現在のポーズを新しいレストポーズとして適用するオペレーターです（ポーズをレスト状態にベイク）
2. Python：bpy.ops.pose.apply_to_basis()
3. リギング後のボーンの向きの修正に役立ちます

レイヤーアクションのパフォーマンス（5.1）

1. レイヤー化（非破壊）アニメーションのパフォーマンスが大幅に向上しました
2. 複雑な NLA／レイヤー設定の評価オーバーヘッドが低減されました
3. レイヤー化アニメーションが有効な状態でのビューポート再生が改善されました

ANIM_OT_convert_legacy_action の削除（5.1）

1. bpy.ops.anim.convert_legacy_action オペレーターは削除されました
2. 従来の単一ストリップ NLA アクションは、レイヤーアクションシステムによって自動的に処理されるようになりました
3. このオペレーターを参照しているスクリプトを更新してください

キーフレームのパターン

基本的なキーフレーム設定

import bpy

obj = bpy.context.active_object

# Set value and insert keyframe
obj.location = (0, 0, 0)
obj.keyframe_insert(data_path="location", frame=1)

obj.location = (5, 0, 0)
obj.keyframe_insert(data_path="location", frame=60)

# Keyframe specific channel (e.g., X location only)
obj.keyframe_insert(data_path="location", index=0, frame=1)

# Keyframe rotation
obj.rotation_euler = (0, 0, 0)
obj.keyframe_insert(data_path="rotation_euler", frame=1)

# Keyframe scale
obj.keyframe_insert(data_path="scale", frame=1)

キーフレームを設定できるプロパティ

プロパティ	data_path	コンポーネント
位置	"location"	0=X、1=Y、2=Z
回転（オイラー角）	"rotation_euler"	0=X、1=Y、2=Z
回転（クォータニオン）	"rotation_quaternion"	0=W、1=X、2=Y、3=Z
スケール	"scale"	0=X、1=Y、2=Z
カスタムプロパティ	'["prop_name"]'	—
マテリアル値	マテリアルノードの入力経由	—
シェイプキー値	"value"（キーブロック上）	—
モディファイアプロパティ	'modifiers["name"].property'	—

アーマチュアの作成

import bpy
from mathutils import Vector

# Create armature data and object
armature = bpy.data.armatures.new("MyArmature")
arm_obj = bpy.data.objects.new("MyArmature", armature)
bpy.context.collection.objects.link(arm_obj)
bpy.context.view_layer.objects.active = arm_obj

# Enter edit mode to create bones
bpy.ops.object.mode_set(mode='EDIT')
edit_bones = armature.edit_bones

# Root bone
root = edit_bones.new("Root")
root.head = (0, 0, 0)
root.tail = (0, 0, 0.5)

# Spine chain
spine = edit_bones.new("Spine")
spine.head = root.tail
spine.tail = (0, 0, 1.0)
spine.parent = root
spine.use_connect = True

chest = edit_bones.new("Chest")
chest.head = spine.tail
chest.tail = (0, 0, 1.5)
chest.parent = spine
chest.use_connect = True

# Arm bones (left)
upper_arm_l = edit_bones.new("UpperArm.L")
upper_arm_l.head = (0.2, 0, 1.4)
upper_arm_l.tail = (0.7, 0, 1.4)
upper_arm_l.parent = chest

lower_arm_l = edit_bones.new("LowerArm.L")
lower_arm_l.head = upper_arm_l.tail
lower_arm_l.tail = (1.2, 0, 1.4)
lower_arm_l.parent = upper_arm_l
lower_arm_l.use_connect = True

# Return to object mode
bpy.ops.object.mode_set(mode='OBJECT')

IK チェーンの設定

import bpy

arm_obj = bpy.data.objects["MyArmature"]
bpy.context.view_layer.objects.active = arm_obj
bpy.ops.object.mode_set(mode='POSE')

# Add IK constraint to the last bone in the chain
pose_bone = arm_obj.pose.bones["LowerArm.L"]
ik = pose_bone.constraints.new('INVERSE_KINEMATICS')
ik.target = bpy.data.objects["IK_Target"]  # Empty or other object
ik.chain_count = 2  # Number of bones in chain (0 = to root)
ik.use_rotation = False  # Optional: also match target rotation
ik.influence = 1.0

# IK with pole target (for knee/elbow direction)
ik.pole_target = bpy.data.objects["Pole_Target"]
ik.pole_angle = 0.0  # Adjust if elbow/knee points wrong direction

bpy.ops.object.mode_set(mode='OBJECT')

ドライバーのレシピ

シンプルな式ドライバー

import bpy

obj = bpy.context.active_object

# Add driver to Z location
fcurve = obj.driver_add("location", 2)  # index 2 = Z
driver = fcurve.driver
driver.type = 'SCRIPTED'
driver.expression = "frame / 24"  # Z = current second

変数を使用するドライバー

# Drive Y scale from another object's X location
fcurve = obj.driver_add("scale", 1)  # Y scale
driver = fcurve.driver
driver.type = 'SCRIPTED'

var = driver.variables.new()
var.name = "ctrl_x"
var.type = 'TRANSFORMS'
var.targets[0].id = bpy.data.objects["Controller"]
var.targets[0].transform_type = 'LOC_X'
var.targets[0].transform_space = 'WORLD_SPACE'

driver.expression = "ctrl_x * 2"

カスタムプロパティを使用するドライバー

fcurve = obj.driver_add("location", 0)  # X location
driver = fcurve.driver
driver.type = 'SCRIPTED'

var = driver.variables.new()
var.name = "my_val"
var.type = 'SINGLE_PROP'
var.targets[0].id = bpy.data.objects["Controller"]
var.targets[0].data_path = '["my_custom_property"]'

driver.expression = "my_val"

ドライバーの変数タイプ

タイプ	説明
'SINGLE_PROP'	RNA プロパティの値
'TRANSFORMS'	オブジェクト／ボーンのトランスフォームチャンネル
'ROTATION_DIFF'	2 つのボーン間の回転差
'LOC_DIFF'	2 つのオブジェクト／ボーン間の距離
'CONTEXT_PROP'	アクティブなシーン／ビューレイヤーのプロパティ

TRANSFORMS 変数のトランスフォームタイプ

LOC_X、LOC_Y、LOC_Z、ROT_X、ROT_Y、ROT_Z、ROT_W、SCALE_X、SCALE_Y、SCALE_Z、SCALE_AVG

シェイプキーパターン

シェイプキーの作成

import bpy

obj = bpy.context.active_object
mesh = obj.data

# Create basis (reference shape)
if mesh.shape_keys is None:
    obj.shape_key_add(name="Basis", from_mix=False)

# Add shape keys
key_smile = obj.shape_key_add(name="Smile", from_mix=False)
# Modify vertices for the smile shape
for i, v in enumerate(key_smile.data):
    if mesh.vertices[i].co.z > 0.5:  # Upper face
        v.co.y += 0.1

key_frown = obj.shape_key_add(name="Frown", from_mix=False)
for i, v in enumerate(key_frown.data):
    if mesh.vertices[i].co.z > 0.5:
        v.co.y -= 0.1

シェイプキーのアニメーション化

# Access shape keys
shape_keys = obj.data.shape_keys
key_blocks = shape_keys.key_blocks

# Set value and keyframe
key_blocks["Smile"].value = 0.0
key_blocks["Smile"].keyframe_insert(data_path="value", frame=1)

key_blocks["Smile"].value = 1.0
key_blocks["Smile"].keyframe_insert(data_path="value", frame=30)

シェイプキーのプロパティ

key = key_blocks["Smile"]
key.value = 0.5           # Current blend value (0-1)
key.slider_min = 0.0      # Minimum slider value
key.slider_max = 1.0      # Maximum slider value
key.mute = False           # Mute this shape key
key.relative_key = key_blocks["Basis"]  # Reference shape
key.vertex_group = ""      # Limit influence to vertex group

NLA の管理

NLA ストリップの作成と管理

import bpy

obj = bpy.context.active_object

# Ensure animation data exists
if obj.animation_data is None:
    obj.animation_data_create()

# Push current action to NLA track
action = obj.animation_data.action
if action:
    track = obj.animation_data.nla_tracks.new()
    track.name = "Walk Cycle"
    strip = track.strips.new(name="Walk", start=1, action=action)
    obj.animation_data.action = None  # Clear active action

NLA ストリップのプロパティ

strip.frame_start = 1
strip.frame_end = 60
strip.repeat = 3.0              # Loop count
strip.scale = 1.0               # Time scale (0.5 = half speed)
strip.blend_type = 'REPLACE'    # REPLACE, COMBINE, ADD, SUBTRACT, MULTIPLY
strip.influence = 1.0           # Blend influence (0-1)
strip.mute = False
strip.use_auto_blend = True     # Auto-blend between adjacent strips
strip.blend_in = 5.0            # Blend-in frames
strip.blend_out = 5.0           # Blend-out frames
strip.use_reverse = False       # Play in reverse
strip.extrapolation = 'HOLD'    # NOTHING, HOLD, HOLD_FORWARD

モード切り替え時の注意点

1. 編集ボーンとポーズボーン：armature.edit_bones は編集モードでのみアクセスできます。object.pose.bones はポーズモードとオブジェクトモードでアクセスできます。
2. ボーンデータの損失：モードを切り替えるとボーンデータが更新されます。モードの切り替えをまたいで編集ボーンの参照をキャッシュしないでください。
3. コンストレイントのターゲット：ポーズモードで設定する必要があります。コンストレイントのプロパティはオブジェクトモードで読み取れます。
4. 編集モード中のシェイプキー：編集モードでメッシュを変更すると、ベースがアクティブな場合を除き、ベースではなくアクティブなシェイプキーが変更されます。
5. キーフレーム挿入のコンテキスト：keyframe_insert() はどのモードでも動作しますが、bpy.ops.anim.keyframe_insert() には正しいコンテキストが必要です。
6. ボーンロール：編集モードで edit_bone.roll を設定します。ロールが正しくないと IK 平面が反転します。
7. レストポーズとポーズ：armature.bones[].head_local はレストポーズです。pose.bones[].head はポーズ時の位置であり、読み取り専用で、行列から計算されます。

アニメーションの問題のデバッグ

• アニメーションが再生されない：フレーム範囲（開始／終了）を確認し、アクションが割り当てられているか、NLA ストリップがミュートされていないかを確認します。
• 誤ったチャンネルにキーフレームが設定される：FCurve の data_path と array_index を確認します。
• IK が反転する：ポールターゲットの位置、または編集モードでのボーンロールを調整します。
• ドライバーが更新されない：循環依存がないか確認し、式の構文が有効であることを確認して、変数のターゲットを確認します。
• シェイプキーがブレンドされない：ベースシェイプが存在し、relative_key が正しく設定されていることを確認します。
• コンストレイントが機能しない：影響度（0 は無効）を確認し、ターゲットオブジェクトが存在するか、ボーン名のスペルが正しいかを確認します。

コンストレイントのリファレンス

タイプ文字列、プロパティ、使用例を含む約 45 種類すべてのコンストレイントの完全な一覧については、references/constraint_reference.md を参照してください。

主なカテゴリ：

• モーショントラッキング：「Track」または「Motion」を grep します。
• トランスフォーム制御：「Copy」、「Limit」、または「Transform」を grep します。
• IK／リギング：「Inverse」、「Spline」、または「Stretch」を grep します。
• リレーションシップ：「Child Of」、「Pivot」、または「Follow」を grep します。

Python API リファレンス

キーフレームの挿入、FCurve の操作、ドライバーの作成、アーマチュア／ボーンの設定、NLA ストリップ、シェイプキーの管理など、Python API のパターン全般については、references/python_api.md を参照してください。