はじめてのBlenderアドオン開発

Last Update: 2023.3.1

Blender 2.7

はじめてのBlenderアドオン開発

Blender 2.7

Last Update: 2023.3.1
問題を報告する
本を修正する

4-1. Blenderが提供するAPIを調べる

これまで紹介したサンプルを作るために、Blenderが提供するさまざまなAPIを使いました。 ところで、サンプルで利用したAPIはどのようにして使い方を理解すればよいのでしょうか？ 本節ではこの疑問に答えるため、Blenderが提供するAPIについて調べる方法を紹介します。

Blenderが提供するAPIの情報源

Blenderが提供するAPIの情報を収集する主な方法としては、次の6つの方法があります。

ここで挙げたそれぞれの方法について、詳しく見ていきます。

Blender公式のAPIドキュメントを読む

Blenderの情報を収集するのであれば、やはり公式のドキュメント(https://docs.blender.org/api/)が一番です。 間違いや記述不足などのドキュメントとして不足しているところはありますが、公式として提供されるドキュメントであることから、他の情報源と比較して情報の信頼性が高いです。 Blenderが提供するAPIについても、Blenderの公式のドキュメントから確認することができます。

Blenderは、過去のBlenderのバージョン含めたすべてのバージョンのAPIについて、ドキュメント化しています。 Blenderのバージョンに応じて提供されるAPIが変わるため、アドオン開発者は、利用しているBlenderのバージョンのドキュメントを参照する必要があります。

本書のサンプルは2.75aのBlenderを対象としているため、以降はBlenderのバージョンが2.75aであるドキュメント(https://docs.blender.org/api/blender_python_api_2_75a_release/)を参照することを前提として説明します。

APIドキュメントの右側のページには、提供されているAPIがモジュールごとにメニュー化されて表示されています。 APIは大きく分けて次の3つのモジュールのグループに分けられています。

項目 内容
Application Modules 基本モジュール(bpyモジュール)。
Blender本体のデータにアクセスするために最低限必要なモジュール
Standalone Modules 拡張モジュール。
Application Modulesを簡単に利用できるようにするためのAPIなど、アドオン開発の際に便利なAPIが提供されているモジュール
Game Engine Modules Blender Game Engine向けのAPIが提供されているモジュール

Game Engine Modulesは、Blenderに備わっているゲームエンジン『Blender Game Engine（BGE）』を利用するためのモジュールであるため、アドオン開発時には使用しません。 このため、アドオン開発に限ってAPIを利用するのであれば、Application ModulesとStandalone Modulesのみを確認すれば問題ありません。

Application Modules

Application Modulesである bpy モジュールは、非常に大きなモジュールであるため、次に示す複数のサブモジュールから構成されています。 アドオン開発時に必ず必要となるモジュールであるため、一度目を通しておき、どのようなモジュールが提供されているかを確認しておきましょう。

サブモジュール名 概要
bpy.context 現在のBlenderの実行状態（コンテキスト）を取得するためのAPI群
bpy.data メッシュや画像データなど、Blenderの内部情報へアクセスするためのAPI群
bpy.ops Blenderの内部情報に対して操作を行うAPI群や、アドオンで登録した操作
bpy.types Blenderの内部情報で使用するデータを表す型
bpy.utils アドオンで作成したクラスの登録など、Blenderの内部情報へ影響を与えない便利API群
bpy.path ファイルのパスを簡単に扱うためのAPI群
bpy.app Blenderのバージョンなど、Blender本体の情報を取得するためのAPI群
bpy.props プロパティクラス

Standalone Modules

Standalone Modulesは、bpy モジュールを拡張するモジュールです。 Application Modulesを使っただけでは実装が大変な処理を、簡単かつ効率的に実現できるAPIが提供されています。

Standalone Modulesに含まれるモジュールを次に示します。 bgl モジュールや blf モジュールなどの独自にUIを構築できるモジュールや、aud モジュールのようにオーディオファイルを扱うことのできるモジュールも、Standalone Modulesに含まれています。

モジュール名 概要
mathutils 行列やベクトルなどのクラスや、行列演算やベクトル演算を簡単に行うことができる関数群
geometry や kdtree サブモジュールを利用することで、図形の交差判定や3D空間内のオブジェクト探索を高速に行うことも可能
bgl PythonからOpenGLへアクセスするためのラッパー関数群
blf テキスト描画を簡単に行うための関数群
gpu GLSLを扱うための関数群
aud オーディオファイルの読み込みや再生などを行うための関数群
bpy_extras bpy モジュールのみでは実装が大変な処理について、アドオン開発者が簡単に実現できるようにした便利関数群
bmesh メッシュデータを容易に扱うための関数群

APIドキュメントの使い方を理解するために、[3Dビュー] エリアでアクティブ状態のオブジェクトを取得するためのAPI bpy.props.EnumProperty を調べてみましょう。

APIドキュメントのWebページを開いた後、Application Modules > [Property Definitions (bpy.props)] をクリックし、bpy.props.EnumProperty を探します。 すると、APIの説明に加えて引数や各引数の説明を見ることができます。

PythonコンソールでAPIを検索・実行する

2-2節 で紹介しましたが、[Pythonコンソール] を活用し、Blenderが提供するAPIを検索・実行することができます。 ここでは、[Pythonコンソール] を使って [3Dビュー] エリア上のオブジェクトを操作するAPIを調べてみます。

1 [3Dビュー] エリア上にあるオブジェクトの一覧を参照できるAPI、bpy.data.objects を [Pythonコンソール] に入力します。
2 [ctrl] + [space] キーを押すと、[3Dビュー] エリア上のオブジェクトの一覧が入力候補として表示されます。
3 [3Dビュー] エリア上にあるオブジェクト名が候補として表示されるため、適当なオブジェクト名を入力します。ここでは、Cube を入力しました。入力したあと、再度 [ctrl] + [space] キーを押して次の入力候補を表示します。
4 入力候補の中にある select を入力し、実行します。すると、選んだオブジェクトが選択状態である場合には True が、選択状態でない場合は False が表示されます。
5 手順4で入力した変数に対して True を代入すると、オブジェクトを選択状態にすることができます。一方、False を代入するとオブジェクトを非選択状態にします。

これらの一連の動作から、select はオブジェクトが選択状態か非選択状態かを調べるためのAPIであると予想できます。

ここで、Blender公式のAPIドキュメント（https://docs.blender.org/api/blender_python_api_2_75a_release/bpy.types.Object.html#bpy.types.Object.select）を調べてみると、次のように記載されています。

Object selection state

[Pythonコンソール] における調査から予想した機能と一致しています。 このように [Pythonコンソール] を利用することで、APIの動作を確認することができます。 APIのドキュメントを確認することも重要ですが、実際に [Pythonコンソール] でAPIを使ってその効果を確認することも重要です。 APIを使った時に、ドキュメントで期待した動作と異なることはよくあることですし、時にはドキュメントが間違っていることや、そもそもドキュメントが存在しない場合もあります。 [Pythonコンソール] を活用することでよりAPIへの理解が深まると思いますので、積極的に活用していきましょう。

スクリプトのテンプレートを読む

BlenderでPythonスクリプトを書く人向けに、Blenderはスクリプトのテンプレートを用意しています。 テンプレートはBlender本体が提供しているため、正常に動作することが保証されています。 実現したい処理のテンプレートが存在する場合は、一度確認してみるとよいでしょう。 また、Blenderが提供するAPIの概要をひととおり学んでおきたい場合にも、本サンプルは参考になると思います。 テンプレートは、[テキストエディター] エリアのメニュー [テンプレート] > [Python] から参照することができます。

提供されているテンプレートの中で最も簡単なテンプレートは、右図に示す [Operator Simple] です。 [Operator Simple] は、[3Dビュー] エリアにあるオブジェクトの一覧をコンソールウィンドウに表示するスクリプトです。

Blenderアドオン開発の参考サイトを読む

Blenderが提供するAPIを調べる手段として、Blenderアドオン開発の参考サイトを読む方法もあります。 しかし、この方法はあまり効率がよいとは言えません。 Blender本体の使い方を解説しているサイトはそれなりに存在するものの、アドオン開発の解説サイトは非常に少ないからです（アドオン開発の解説サイトが少なかったことがきっかけで、本書を執筆しました）。 特に日本語の解説サイトは、数を数えられるくらい少ないです。

ここでは、アドオン開発で筆者がよく参考にするサイトをピックアップしてみました。

Blender Wiki

https://wiki.blender.org/index.php/Dev:Py/Scripts

Blenderの公式Wikiページです。 アドオン開発のチュートリアルやベストプラクティスなど、アドオンの開発に必要な知識を得ることができます。 特にテーマに応じて簡単なサンプルを紹介しているCode Snippetsは、特定の処理を実現する時に役立つでしょう。

また、アドオンの公開手順についても書かれていますので、初心者だけでなく、ある程度アドオン開発に慣れた方もよくお世話になるサイトです。

blugjpまとめサイト

https://sites.google.com/site/blugjp/blenderpython

Blenderを使っている方はおそらくご存知であろう、BLUG.jpさんによるまとめサイトです。 BlenderPythonのページにアドオン開発の情報があります。 BlenderPythonのページは現在も更新され続けていますので、アドオン開発者はブックマークしてときどき見に行くとよいでしょう。 Blenderのアドオン開発に慣れてきて、ぜひ他のアドオン開発者のために情報を共有したい、ということであれば、BlenderPythonページの更新を依頼してみてください。 BLUG.jpさん（Twitter：@blug_jp）に連絡すれば、編集権限を与えてもらえるかもしれません。

Qiita

https://qiita.com

Qiitaはプログラマのための情報共有サイトです。 数は多くないですが、Blenderに関係する投稿がいくつかあります。 Blenderに関する投稿の一覧は、Blenderタグ（http://qiita.com/tags/blender）で確認できます。

他者が作成したアドオンのソースコードを読む

Blenderのアドオンは、Pythonのソースコードとして配布されていますので、他者が作成したアドオンのソースコードを読むことでも、Blenderが提供するAPIを調べることができます。 もしアドオンを作っている時に、実現しようとしている処理が他のアドオンで使われていれば、そのアドオンのソースコードを参照することで、実装方法や使われているAPIを知ることができます。 なお、ソースコードを参照して処理を流用する場合は、4-4節 で説明するアドオンのソースコードに適用されているライセンスに気をつけてください。 ライセンスによっては流用できない場合もありますし、流用に必要な条件が決められている場合もあります。

インストール済みのアドオンのソースコードが置かれている場所は、[ファイル] > [ユーザ設定...] で開くユーザー・プリファレンスの [アドオン] タブから確認することができます。 Web上に公開されているアドオンなど、非公式にインストールするアドオンの場合はソースコードとして提供されていることが多いため、直接ソースコードを読むことができます。

Blender内でソースコードを確認する方法

2-8節 で説明したように、UIをはじめとしたBlenderが標準で提供している機能については、一部Blender内でソースコードを確認することができます。 ここでは、[3Dビュー] エリアのメニュー [オブジェクト] のソースコードを確認する方法を説明します。

1 [3Dビュー] エリアのメニュー [オブジェクト] にマウスカーソルを置いて右クリックし、表示されたメニューから [ソース編集] をクリックします。
2 [テキストエディター] エリアにソースコードが表示されます。

APIドキュメントへ移動する方法

Blenderが標準で提供している機能のソースコードを確認することに加え、APIドキュメントへ移動することもできます。 ここでは、[3Dビュー] エリアのメニュー [メッシュ] > [ミラー] > [ローカルX軸] のAPIドキュメントを表示する方法を説明します。

1 [3Dビュー] エリアのメニュー [メッシュ] > [ミラー] > [ローカルX軸] を右クリックして表示されるメニューから、[Blender PythonAPI リファレンス] をクリックします。
2 クリックした機能に関するAPIドキュメントが存在する場合、該当するAPIのドキュメントページが表示されます。

Googleで検索する

実現したいことや発生した問題が明らかにわかっている場合は、Google検索が問題解決のために役立ちます。 例えば、検索ワードとして [bpy] や [blender] 、[python] を指定すると、BlenderのAPIに関して調べることができます。 また、もし問題が生じたときに、コンソールウィンドウやスクリプト実行ログにエラーメッセージが出力されているのであれば、エラーメッセージをそのまま検索ワードに指定することで、発生した問題に対する解決方法が見つかるかもしれません。

Googleの検索はとても強力ですので、アドオン作成時に生じたほとんどの問題は、この方法で解決することができます。 しかし、発生した問題があまり一般的ではなかったり、提供され始めたばかりのAPIに関する問題であったりした場合は、Google検索を利用しても解決できないことがあります。

Blenderのコミュニティサイトで質問する

APIドキュメントを調べたり、他のアドオンを参考にしたりしても問題が解決しない場合もあります。 このときは最終手段になりますが、コミュニティサイトで質問してみましょう。

幸いなことに、Blenderアドオンの開発に関して質問できるサイトはいくつかあります。 ただし、執筆時点でアドオン開発に関して質問できる国内のサイトは存在しません。 このため、アドオン開発について質問できるのは海外サイトしかなく、英語で質問を投稿する必要があります。 海外サイトで投稿することに抵抗がある方も多いと思いますが、高等学校の英語レベルがあれば十分通用しますので、ぜひチャレンジしてみてください。

ここでは、Blenderのアドオン開発について質問できるコミュニティサイトを紹介します。

Blender Artists Community

http://blenderartists.org/forum/

海外最大のBlenderコミュニティサイトで、略してBAと呼ばれることもあります。 Blenderで制作した作品を投稿するのが主な目的であるサイトですが、アドオン開発についても活発な議論が行われています。 作ったアドオンを投稿してフィードバックをもらうこともできますし、既存のアドオンに対して意見や要望を出すこともできます。 また、アドオン開発に関して質問することもできます。

非常に有名なサイトであるため、Blenderを使っている方は1度は見たり聞いたりしたことがあるのではないでしょうか。 まだ一度も閲覧したことがない方は、海外のBlenderのコミュニティの雰囲気を知るよい機会でもあるため、ぜひ訪れてみてください。 なお海外サイトですので、英語で投稿する必要がありますが、高等学校レベルの英語力があれば困ることはないと思います。

アドオンに関して質問したい場合は、アカウントを登録した後に [CODING] > [Python Support] の [POST NEW THREAD] ボタンからスレッドを立てます。

Blender Stack Exchange

http://blender.stackexchange.com

Stack Overflow（http://stackoverflow.com）と呼ばれる、プログラマ間では非常に有名な情報共有サイトがあります。 本サイトはその派生サイトで、Blenderに特化した情報共有サイトです。 Blender Artists Communityに負けず、本サイトでもアドオン開発に関して活発な議論が行われています。 情報共有に特化したサイトであることから、アドオン開発に関してはBlender Artists Communityよりも得られる情報が多く、質問に対して回答が得られやすいように思えます。 また、アドオン開発だけでなくBlenderの使い方に関して質問することもできます。

Blender Stack Exchangeで質問するためには、Blender Artists Communityと同様にアカウントを登録し、英語で投稿する必要があります。 質問の投稿は、[Ask Question] ボタンから行うことができます。 アドオン開発に関する質問の場合、[Python] や [add-on] 、[scripting] のタグに加えて、質問内容に応じて関連するタグ（[mathematics] や [opengl] など）を設定すると回答が得られやすくなります。

本サイトでは、質問したり他人の質問に回答したり誤字や脱字などを編集したりすることで、ユーザがポイントを得られる仕組みがあり、それぞれのユーザの貢献度を見ることができます。 さらにポイントを獲得していくことで、PS4のトロフィーやXBoxの実績のようなバッジを獲得することができ、登録直後の段階で制限されていた機能が使えるようになる仕組みもあります。

Blender.jp

https://blender.jp

国内では最大と思われる、Blenderのコミュニティサイトです。 本コミュニティサイトには、Blenderについて議論できるフォーラムがあり、かつてフォーラム内の質問板でアドオン開発について質問することができました。 なお、現時点でフォーラムはリードオンリーになっており、投稿することができなくなっています。

reddit

https://www.reddit.com/

ニュース記事などのトピックを立てて、コメントをもらうためのWebサービスです。 電子掲示板のようなものと考えるとわかりやすいかもしれません。 redditではプログラミングに関する質問を投稿することができ、数は多くないですが、BlenderにおけるPythonスクリプトに関する投稿もされています（もちろんBlender本体に関する質問も投稿されています）。

redditにはsubredditと呼ばれる、特定のジャンルに特化した投稿を見ることができる機能（他のWebサービスでのタグのようなもの）があります。 BlenderのPythonに関する投稿を見る場合は、次に示すsubredditを確認するとよいと思います。

コミュニティサイトで質問する前に

アドオンの情報を得られるコミュニティサイトについて紹介してきましたが、コミュニティサイトで質問する時には、相手が理解しやすい投稿を心がけましょう。 投稿内容をわかりやすく書くのはもちろんのこと、ソースコードや実行結果を一緒に投稿すると問題点が相手に伝わりやすくなります。 そして忘れてはならないのが、回答に対するお礼です。 回答者も時間を費やして回答してくれていますので、回答により問題が解決したか否かに関わらず、回答に対するお礼をすることを忘れてはいけません。

なお、コミュニティサイトで質問すれば、欲しい情報をストレートに得られる可能性がありますが、回答する側も回答の記事を作成するのに時間を費やすため、何でもかんでも質問するのは控えるべきです。 コミュニティサイトで質問する前に、まず次のことを全て行ったかを確認してから質問することを心がけてください。 余談ですが、Blender Stack Exchangeで質問を投稿する際に質問のタイトルを入力すると、タイトルに入力された単語と関連性の高い質問が表示されます。

まとめ

本節では、Blenderが提供するAPIを調べる方法について紹介しました。 筆者がAPIを調べる時はGoogle検索を利用し、まず最初に似たような処理を行っているアドオンのソースコードを参考にします。 そしてソースコードの中でわからない部分は、公式のAPIドキュメントで仕様を確認したあと、[Pythonコンソール] を使って動作確認します。 ここまで行っても欲しい情報が得られない場合は、コミュニティサイトで質問します。

アドオン開発に限ったことではなくプログラミング全般に言えることですが、他者が作成したプログラムのソースコードはアドオン開発において最も参考になります。 他者が作ったソースコードを読んで真似して改造しつつ、わからないところを調べるという流れを繰り返すことで、独自のアドオンが作れるようになっているはずです。 ただし、他者のソースコードを扱う場合、4-4節 で説明するソースコードのライセンスには注意しましょう。

ポイント