【Blender 2.8 アドオン開発】002 Blender API を調べて使ってみよう
前回、Blender にスクリプトを実行されることができました。
今回はいよいよ、Blender API を触っていきます。
Blender では大体の動作は Blender API を通して実行可能です。そのため、量も多く、全てを覚えてから書き始めるというのは現実的ではありません。
そうなると、API を調べながらスクリプトを書いていく、ということになります。
今回は、Blender API の調べ方と調べた API を実行して Blender を操作してみましょう。
前置き
まず、プログラミングやスクリプティングなどを経験したことがある方なら API を調べるというとまっさきに思いつくのは Web 上にあるリファレンスを見ることだと思います。
Blendre API にもリファレンスは存在します。
Blender 2.8 Python API Documentation
ここや、一つ前のバージョンになりますが
Blender 2.79b API documentation
お世話になってます。
ただ、Blender 2.8 は現在 (2019.02.05) ベータなので API に仕様の変更がある場合や、すぐリファレンスに反映されない場合があることを留意する必要があります。
仕様変更で動作が変わるのは思った通りに動かない、エラーが出るので修正すればいいのですが、関数名やクラス名が変更された場合はリファレンスが更新されるまで待たなければいけないのでしょうか？
API を表示しよう
まず、ウィンドウメニューの「Edit」から「Preferences」を開きます。
Preferences の「Interface」タブの「Display」グループ内にある「Tooltips」と「Python Tooltips」にチェックを入れて保存してください。
前回、コンソールウィンドウを表示するのにウィンドウメニューの「Window」内の「Toggle System Console」をクリックしましたが、今回はクリックせずにマウスカーソルを乗せて待ってみてください。
すると、ツールチップが表示されたかと思います。
ここで注目してほしいのが２行目の「Python: bpy.ops.wm.console_toggle()」という文字です。
これ、API なんです。「Toggle System Console」という項目をクリックすると「bpy.ops.wm.console_toggle()」という API が動作してコンソールウィンドウが表示されるということです。
つまり、Blender を動かしている API を Blender 上である程度知ることができるということです。
例えば、API のアップデートで console_show() と名前が変わったとします。リファレンスもまだ更新されていない、でも大丈夫！マウスカーソルを乗せるだけです。
では、さっそくこの API を使ってみましょう。
API を使ってみる
では、Scripting レイアウトにてください。
今回は前回出番の無かった Python Console を使っていきます。
これは Blender が内蔵しているインタプリタで、ここからも API を実行できます。
では >>> に続いて
bpy.ops.wm.console_toggle()
と入力してエンターを押してください。
どうでしょうか？ toggle は切り替えという意味があるのでコンソールウィンドウが出てなかった人は出て、出ていた人は消えたとおもいます。
これは Python Console から「コンソールウィンドウの表示・非表示を切り替えて」という命令を出したということです。
それにしても、この API 長くないですか？
もちろん、意味があり理解すればある程度は覚えやすくはなります。この API でいえば、
bpy は blender python の略、
ops は operators の略、
wm は window manager の略です。
つまり、Blender pyton API 内のコンソール "ウィンドウ" にまつわる操作 (operation) なので「bpy.ops.wm」、そして実行するのはコンソールウィンドウの表示・非表示を切り替える console_toggle() となります。
ここでは詳しく説明しませんが
操作が詰まった bpy.ops の他に、Blender の情報へアクセスするための bpy.data や、現在の状態の情報へアクセスするための bpy.context、
bpy.ops 以下もオブジェクトに関する操作が詰まった bpy.ops.object や、3D Viewに関する操作が詰まった bpy.ops.view3d、などなど山ほど API があります。
ですので、全ての API を把握するのは厳しく、ある程度予測を立てて、目的の API を「探す」という行為が必要になってきます。
リファレンスから探すというのも、もちろんいいのですが、 Python Console の補完機能が超便利です。仲良くしておいて損はないです。
Python Console と仲良くなろう
まず、キーボードの上下キーで履歴をたどれます。モジュールの構成上どうしても１命令が長くなるので以前の命令を途中まで消して別の命令を実行するときなどに重宝します。
では、補完機能を使いましょう。
>>> に続いて
bpy.
と入力して「Ctrl + スペース」 を押してみてください。すると緑色の文字が何行か出たとおもいます。
この緑色の文字列が候補です。その中には ops もちゃんとあります。
では続いて、o と書いて「Ctrl + スペース」 を押してみてください。
すると
bpy.ops
と、なったとおもいます。これは候補の中で o から始まる候補が ops だけなので補完されました。この状態で「Ctrl + スペース」 を押すと . (ピリオド) が追加されます。これでこの後にも候補があることがわかります。
では、
bpy.ops.
この状態で「Ctrl + スペース」 を押してみてください。
ゴッソリ候補が出てきたとおもいます。
ですが、慌てる必要はありません。先ほど軽く説明したとおり、ops は操作が詰まっている、ということはこの候補たちは「どこの操作」かということです。もちろん wm もあります。
では、コンソールウィンドウの出し入ればかりではアレなので、console を選択しましょう。
bpy.ops.console.
ちなみに c と書いて「Ctrl + スペース」 を押すと、c から始まる候補へと絞込みが行われます。
では、「Ctrl + スペース」 を押してください。
今までの候補と違い、最後が ( で終わっています。
ためしに
bpy.ops.console.clear(
として、「Ctrl + スペース」 を押してみてください。
すると、候補はでてこず、この命令の説明がでてきました。
説明は引数と短い説明文だけですが、この状態で基本的に１命令です。
では実行してみましょう。
bpy.ops.console.clear()
命令の実行はエンターです。
どうでしょう？そう、ここでいう console は Python Console という罠です。
まとめ
おつかれさまでした。これで Blender 上で API を調べる方法がわかりました。
Blender 2.8 アドオン開発と銘打っておきながら全然開発していませんが、次も開発はしません。
と、いうのも開発するにあたり、Blender のデータ構造や仕組みなどの理解が必要になるからです。
ためしに
bpy.ops.info.report_delete()
を実行してみてください。エラーが出るとおもいます。
これは context が違うから実行できません。というエラーです。では context とは？
次からこのへんの context や Blender のデータ構造、レイアウト構造のお話ができたらなとおもいます。
ここで記載されているソースコードを使用する場合は自己責任でお願いします。
