MRが楽しい

MRやVRについて学習したことを書き残す

Blender 2.8のPython APIドキュメントを少しずつ読み解く リファレンスAPIの使用法 その1

本日は Blender2.8 の調査枠です。
Blender 2.8 の Python API ドキュメントを少しずつ読みつつ試していきます。

Blender 2.8 Python API Documentation

以下のページを日本語訳しつつ実際に試して記事を進めていきます。
docs.blender.org
docs.blender.org

今日は「リファレンスAPIの使用法」のシンプルなデータアクセスまでです。
f:id:bluebirdofoz:20190923160814j:plain

リファレンスAPIの使用法

Blenderにはスクリプトを記述するために必要な情報を含む、自動生成されたReferenceAPIを備えた相互リンクデータ型があります。
このドキュメントはリファレンスAPIの使用方法を理解できるように設計されています。

リファレンスAPIスコープ

リファレンスAPIは bpy.types をカバーします。
bpy.types は bpy.context(ユーザコンテキスト) または bpy.data(Blenderデータ) にアクセスする型を保存します。

bmesh や aud などの他のモジュールはBlenderのデータAPIを使用していません。
このため、本ドキュメントはそれらのモジュールには適用されません。

データアクセス

リファレンスAPIを使用する最も一般的なケースは、Blender内のデータにアクセスする方法を見つけることです。
最初にBlenderのIDデータブロックに注意すべきです。何故なら、それらに関連するプロパティがよく見つかるためです。

IDデータ

IDデータブロックはBlenderでトップレベルのデータコンテナとして使用されます。
UIからはそれほど目立ちませんが、開発時にはIDデータブロックについて知る必要があります。

IDデータタイプは以下を含みます。
・シーン
・グループ
・オブジェクト
・メッシュ
・スクリーン
・ワールド
・アーマチュア
・画像
・テクスチャ

完全なリストについては bpy.types.ID を参照して下さい。
docs.blender.org
f:id:bluebirdofoz:20190923160843j:plain

IDデータブロックが共有する特性を以下に示します。

・IDは blend ファイルデータのため、新しい blend ファイルをロードすると、データブロックのセット全体がリロードされます。
・IDは、Pythonの bpy.data.* 以下からアクセスできます。
・各データブロックには .name、インターフェイスに表示される一意の属性があります。
・アニメーションデータは .animation_data に保存されます。
・IDは、blend ファイル間でリンクできる唯一のデータ型です。
・IDはPythonで追加/コピーおよび削除できます。
・IDには、保存時に未使用のIDを解放する独自のガベージコレクションシステムがあります。
・データブロックに外部データへの参照がある場合、これはIDデータブロックです。

シンプルなデータアクセス

シンプルなケースから始めます。
オブジェクトのポジションを調整するためのpythonスクリプトが必要だとします。

UIでこの設定を見つけることから始めます

Properties Window -> Object -> Transform -> Location

f:id:bluebirdofoz:20190926094136j:plain

右クリックして[Blender PythonAPI リファレンス]を選択すると、次のリンクが表示されます
docs.blender.org
f:id:bluebirdofoz:20190926093848j:plain

もし[Blender PythonAPI リファレンス]が表示されない場合は以下の手順に沿って表示設定を行います。
bluebirdofoz.hatenablog.com

リファレンスAPIのリンクは多くの場合、ツールヒントよりも多くの情報を提供します。
更に一部のページには使用例が含まれています。
f:id:bluebirdofoz:20190923161036j:plain

この時点で .location を使用する必要があり、3つのfloatの配列であることが分かります。
しかし、スクリプトでこれにアクセスする方法についてはまだ分かりません。

次のステップは、オブジェクトにアクセスする場所を見つけることです。
ページの一番下にある参照(References)セクションに移動します。
オブジェクトには多くの参照があります。
f:id:bluebirdofoz:20190923161046j:plain

モディファイヤ、関数、テクスチャ、および制約など、非常に多くの場所で参照されていることが分かります。
ただし、ユーザーが選択したデータにアクセスする場合、通常は bpy.context 参照を確認するだけです。

今回の場合、bpy.context だけでもかなりの数があります。
ただし、ほとんどはモード固有です。
例えば、ウェイトペイントモードでのみ実行するツールの場合は bpy.context.weight_paint_object を使用するのが適切です。

ユーザーが最後に選択したアイテムにアクセスするには、active メンバーを探します。
Blenderの規則として、ユーザーが選択する単一のアクティブなメンバーにアクセスできます。
active_bone、 active_pose_bone、active_node...などです。
今回のケースでは active_object を使用できます。
f:id:bluebirdofoz:20190923161056j:plain

これで、アクティブなオブジェクトのポジションを見つけるのに十分な情報が得られました。
以下のコードでアクセス可能です。

bpy.context.active_object.location

これをpythonコンソールに入力して、結果を確認できます。
f:id:bluebirdofoz:20190923161110j:plain

参照内のオブジェクトにアクセスするため、他には bpy.types.BlendData.objects を利用できます。
なお bpy.data.objects は参照のリストに含まれていません。
bpy.data は bpy.types.BlendData クラスのインスタンスであるためです。

bpy.data.objects はオブジェクトのコレクションであるため、そのメンバーの1つにアクセスする必要があります。

bpy.data.objects["Cube"].location

f:id:bluebirdofoz:20190923161119j:plain

bluebirdofoz.hatenablog.com