まず最初のページ Quickstart — Blender Python API から。
はじめる前に Before Starting
- 開発者用オプション Developer Extra と Python ツールチップを表示 Python Tooltips を有効にすること
- Python コンソールのオートコンプリートを活用せよ
Python コンソールの右クリックメニューの一番下に [オートコンプリートがある。タブキーを押しても発動する。- 途中まで入力した内容が正しくて一択の場合には自動的に補完され、
- 正しいけれど複数候補がある場合は下に緑色の字で候補が表示される。メソッドとかデータとか属性とかの区別はつかない感じでひたすら。
- 完全に間違っている場合は何も表示されない
- テキストディタのテンプレートにサンプルがある
何のサンプルなのかの説明はないので、慣れてから使うものなのだろう...
スクリプトの実行 Running Scripts
コンソールに直接タイプ(もしくはコピペ)するか、テキストエディタに書いてからスクリプト実行する。メニューバー右端に Scripting というメニューがある。
- コンソールでは print 文の結果が見えるが、テキストエディタだと見えない orz
- コンソールに複数行コピペの場合、最後の行は、改行 Enter キーを押さないと実行されていないことがよくある
- パソコンのレスポンスが悪いのか?ショートカットでのコピー&ペーストの動作がもっさりしていて、うまくいかないころがままある
- 文の先頭に空白文字(インデント)があって実行されないことがままある
基本概念 Key Concepts
データアクセス
データブロックにアクセスする
- bpy.data モジュールを使う
配列にアクセスする Accessing Collections
- 要素インデックスには、名前とインデックス数値が使用できるが、名前を使う方が安全なのはいうまでもない
- list 命令にその下に複数のデータがあるものを指定すると、要素に入っているデータの名前が分かる。例えば list(bpy.data.objects)
属性にアクセスする Accessing Attributes
オブジェクトモデルが分かっていないと、何が属性なのか分かりませんが...
コンテクスト
- 例えば bpy.context.selected_objects は、利用者が Blender の画面上で(複数)選択しているものが何かを返す
- bpy.context.active_object なども便利
オペレーター(ツール)
- 利用者が選択できるメニュー項目のことをオペレータというらしい。
オペレーター(ポーリング) Operator Poll()
- そのオペレーターを実施しようとするにあたって、そもそも現在のモードやカーソルの居場所が、正しいかどうかを事前チェックするもの。
次の Python API Overview — Blender Python API は作成したアドオンを Blender に登録する方法とかなので飛ばして Reference API Usage — Blender Python API へ。
データアクセス
ID データブロック
- Blender の最上位レベルのデータの容れ物
- シーン、グループ、オブジェクト、メッシュ、ワークスペース、ワールド、アーマチュア、画像、テクスチャなどの種類からなる Blender のオブジェクトモデルの根幹であり、bpy.data.何とか以下にある。
簡単なデータ処理の例
- 利用者が選択したデータは大抵 bpy.context で処理でき、利用者は現在選択しているものに対する処理を期待するので、ほとんどの場合はこれが適切
- モード(オブジェクト、編集、ポーズ)に依存することがほとんど
- サクッと書かれている Blender あるあるだが、モードが違っていると命令が出せないので手作業の場合と同様、十分に注意が必要である
- 現在、利用者が選択しているオブジェクトの座標を調べたい場合は bpy.context.active_object.location
- 大抵、ローカル座標系が返ってくるので軸方向に注意
- 名称が判明しているオブジェクトの座標を調べたい場合は bpy.data.objects["Cube"].location
- 大抵、ローカル座標系が返ってくるので軸方向に注意
何段階も階層化されたプロパティ
- データモデルを調べたい場合は、Python コンソールの自動コンプリートが便利
- データモデルとかクラス図とか無いのかと小一時間問い詰めたい
- 利用者インタフェースのプロパティを調べたい場合は、データパスをコピーや Python コマンドをコピー
- API ドキュメントのリファレンス Reference をたどる
データパスをコピー Copy Data Path
- データパスをコピーは、IDデータブロックより下のパスのみコピー
modifiers["細分化"].levels
- 利用者インタフェースのプロパティを調べたい場合、bpy.context.active_object. 以降にコピペ
- フルデータパスをコピーは、IDデータブロックを含む全てをコピー
bpy.data.objects["JeanCrawford"].modifiers["細分化"].levels
オペレータ Operator
- ホットキーやボタンなどはオペレータであり、bpy.ops から操作できる
- (オンにしてれば) Python ツールチップで名前を知ることができる
- ツールチップが表示されない場合、それはオペレータではないか、Python から処理することができない
情報コンテクスト Info Editor
- Python コンソールの下にある情報コンテクストに、利用者インタフェースで行った操作のオペレータが黙々と記録されており、コピペできる
- 選択したオブジェクトなど、オペレータではないものは記録されないので前述のとおり bpy.context.active_object などで調べる
次の Best Practice — Blender Python API はコーディング規約なので飛ばして、
Tips and Tricks — Blender Python API に行く。
勘コツ Tips and Tricks
ターミナルを利用する
ターミナル、つまり Windows コマンドプロンプトなどから Blender を起動すると
次の Tips and Tricks — Blender Python API はまとめぽいので飛ばして Gotchas — Blender Python API に行く。
ボーンを編集しまくる Edit Bones, Pose Bones, Bone… Bones
- アーマチュアのボーンのデータは、モードごとに別々に格納されており、相互には参照できないかもしれない
- ボーンの編集 bpy.context.object.data.edit_bones を使うにはまずアーマチュアを編集モードに切り替える。
- ボーン(オブジェクトモード)では bpy.context.object.data.bones に含まれ色々変更できるが、ヘッド head とテール tail のプロパティは読み取りのみ。
- ボーンのポーズ bpy.context.object.pose.bones には制約や IK 設定と同様にアニメーションのデータが反映される。
- 厳密にはポーズボーンはボーンではなく、アーマチュアの状態なのだが、bpy.types.PoseBone.bone からボーンを処理できる。
アーマチュアのモード変更 Armature Mode Switching
頻繁にアーマチュアのモードを切り替えると思うが、編集モードにおけるボーン編集やヘッド/テールの座標を参照しないように。Blender がクラッシュする。