2-1. アドオン開発の基礎を身につける

1-5節 ではアドオンを作成しましたが、ソースコードの解説を行いませんでした。 本節では、1-5節 よりも実用的なアドオンのサンプルを紹介し、そのソースコードを解説します。

作成するアドオンの仕様

1-5節 で紹介したアドオンは、アドオンを有効化または無効化したときにコンソールウィンドウへメッセージを出力する機能のみを持つアドオンでした。 これをアドオンと呼ぶのには寂しいので、本節ではより実用的な機能を備えたアドオンを作ります。

最初に、本節で作成するアドオンの仕様を決めます。 ソースコードを初めて解説するためのアドオンとなるので、本節のサンプルの仕様は次のように単純なものにしました。

• [3Dビューポート] スペースのメニューに [追加] > [メッシュ] > [球] を追加する
• 追加したメニューを実行すると、[3Dビューポート] スペースのメニュー [追加] > [メッシュ] > [ICO球] を実行したときと同等の効果を得る

Blender標準機能によるICO球作成

[3Dビューポート] スペースのメニュー [追加] > [メッシュ] > [ICO球] を実行したときの動作を確認します。

1	[3Dビューポート] スペースのメニューから、[追加] > [メッシュ] > [ICO球] を実行します。
2	3Dカーソルを中心としたICO球が作成されます。

アドオンを作成する

仕様を満たすように、アドオンを作成します。 ここでは、1-5節 を参考にして次のソースコードを入力し、ファイル名を sample_2-1.py として保存してください。

import bpy   # アドオン開発者に対して用意しているAPIを利用する


# アドオンに関する情報を保持する、bl_info変数
bl_info = {
    "name": "サンプル 2-1: オブジェクトを生成するアドオン",
    "author": "ぬっち（Nutti）",
    "version": (3, 0),
    "blender": (2, 80, 0),
    "location": "3Dビューポート > 追加 > メッシュ",
    "description": "オブジェクトを生成するサンプルアドオン",
    "warning": "",
    "support": "TESTING",
    "doc_url": "",
    "tracker_url": "",
    "category": "Object"
}


# オブジェクト（ICO球）を生成するオペレータ
class SAMPLE21_OT_CreateObject(bpy.types.Operator):

    bl_idname = "object.sample21_create_object"
    bl_label = "球"
    bl_description = "ICO球を追加します"
    bl_options = {'REGISTER', 'UNDO'}

    # メニューを実行したときに呼ばれる関数
    def execute(self, context):
        bpy.ops.mesh.primitive_ico_sphere_add()
        print("サンプル 2-1: ICO球を生成しました。")

        return {'FINISHED'}


# メニューを構築する関数
def menu_fn(self, context):
    self.layout.separator()
    self.layout.operator(SAMPLE21_OT_CreateObject.bl_idname)

# Blenderに登録するクラス
classes = [
    SAMPLE21_OT_CreateObject,
]

# アドオン有効化時の処理
def register():
    for c in classes:
        bpy.utils.register_class(c)
    bpy.types.VIEW3D_MT_mesh_add.append(menu_fn)
    print("サンプル 2-1: アドオン『サンプル 2-1』が有効化されました。")


# アドオン無効化時の処理
def unregister():
    bpy.types.VIEW3D_MT_mesh_add.remove(menu_fn)
    for c in classes:
        bpy.utils.unregister_class(c)
    print("サンプル 2-1: アドオン『サンプル 2-1』が無効化されました。")


# メイン処理
if __name__ == "__main__":
    register()

アドオンを使用する

作成したアドオンを使ってみましょう。

アドオンを有効化する

1-5節 を参考にして、作成したアドオンを有効化します。

アドオンを有効化すると、コンソールウィンドウに次の文字列が出力されます。

サンプル 2-1: アドオン『サンプル 2-1』が有効化されました。

アドオン有効化後、[3Dビューポート] スペースのメニューに [追加] > [メッシュ] > [球] が追加されていることを確認します。

アドオンの機能を使用する

次の手順に従って、アドオンの機能を使ってみます。

1	追加されたメニュー [追加] > [メッシュ] > [球] を実行すると、3Dカーソルを中心としたICO球が作成されます。 さらに、コンソールウィンドウには次の文字列が出力されます。 サンプル 2-1: ICO球を生成しました。

アドオンを無効化する

1-5節 を参考に、アドオンを無効化します。

アドオンを無効化すると、コンソールウィンドウに次の文字列が出力されます。

サンプル 2-1: アドオン『サンプル 2-1』が無効化されました。

ソースコードの解説

アドオンの動作を確認できたところで、作成したアドオンのソースコードを解説します。

bpyモジュールのインポート

Blenderのアドオンを開発するためには、bpyモジュールと呼ばれる、Blenderが提供するAPIをまとめたモジュールをインポートし、APIを利用できるようにする必要があります。

次のコードにより、bpyモジュールをインポートできます。

import bpy   # アドオン開発者に対して用意しているAPIを利用する

bl_info変数の定義

作成したソースコードが、BlenderのアドオンであることをBlender本体に認識させるためには、変数 bl_info を定義する必要があります。

# アドオンに関する情報を保持する、bl_info変数
bl_info = {
    "name": "サンプル 2-1: オブジェクトを生成するアドオン",
    "author": "ぬっち（Nutti）",
    "version": (3, 0),
    "blender": (2, 80, 0),
    "location": "3Dビューポート > 追加 > メッシュ",
    "description": "オブジェクトを生成するサンプルアドオン",
    "warning": "",
    "support": "TESTING",
    "doc_url": "",
    "tracker_url": "",
    "category": "Object"
}

bl_info はディクショナリ型の変数で、次のようなキーと値を定義します。

各キーに設定した値について、Blenderにどのように反映されるかを説明します。

プリファレンスに表示される情報

アドオンを有効化/無効化するときに利用する [プリファレンス] に表示される情報は、次に示す bl_info 変数のキーに指定された値に基づいています。

• name
• author
• version
• location
• description
• warning
• doc_url (wiki_url)
• tracker_url

本節で作成したアドオンについて、上記のキーに設定した値がどのようにBlenderに反映されるかを見てみましょう。

次の図では、bl_info 変数に指定された値と表示内容の対応関係を示しています。 warning, doc_url (wiki_url), tracker_url については、本節のサンプルアドオンでは未設定のため表示されていません。

本節で作成したサンプルアドオンは、warning, doc_url (wiki_url), tracker_url を設定していませんが、もしこれらのキーについて値を設定した場合に [プリファレンス] へどのように反映されるかを確認するため、ソースコードの bl_info を次のように書き換えます。

# アドオンに関する情報を保持する、bl_info変数
bl_info = {
    "name": "サンプル 2-1: オブジェクトを生成するアドオン",
    "author": "ぬっち（Nutti）",
    "version": (3, 0),
    "blender": (2, 80, 0),
    "location": "3Dビューポート > 追加 > メッシュ",
    "description": "オブジェクトを生成するサンプルアドオン",
    "warning": "本アドオンはサンプルです",
    "support": "TESTING",
    "doc_url": "https://github.com/nutti/Introduction-to-Addon-Development-in-Blender-Web/wiki",
    "tracker_url": "https://github.com/nutti/Introduction-to-Addon-Development-in-Blender-Web",
    "category": "Object"
}

ソースコードを書き換えてファイルを保存し、アドオンを有効化すると、[プリファレンス] のアドオン情報にボタンと警告マークが表示されます。

[ドキュメント編集] ボタンをクリックすると、doc_url (wiki_url) に指定したURLが開きます。 アドオンのドキュメントやアドオンの最新情報が得られるサイトのURLを、doc_url (wiki_url) に設定します。 本節のサンプルアドオンでは、本書を構築するファイルを保存しているGitHubプロジェクトのWikiページを設定しました。

[バグを報告] ボタンをクリックすると、tracker_url に指定したURLが開きます。 ユーザがアドオンのバグを報告するためのサイトを持っている人が、ユーザからのフィードバックを得たい場合に設定しておくとよいと思います。 今回は、本書のGitHubプロジェクトのURLを設定しました。

ここからは、bl_info のキーに設定する値についてより詳しく説明していきます。

name

アドオンの名前を指定します。

基本的にアドオン名は自由に決めてよいですが、アドオンの機能に関連した名前をつけるようにします。 また、ユーザがアドオン名とアドオンのソースコードを対応付けやすくするため、アドオン名とユーザに提供するソースコードのファイル名は互いに連想できるものにしましょう。

author

アドオンの開発者を指定します。

アドオンの開発が複数人で行われている場合、開発への貢献度順に名前を指定します。 例えば Hoge がアドオンのメイン部を作成し、そのあとで Piyo がアドオンのバグを修正した場合は、次のように指定します。

"author": "Hoge, Piyo"

version

アドオンのバージョンを、次のフォーマットで指定します。

(メジャーバージョン, マイナーバージョン)

正式リリース前はメジャーバージョンを 0 とし、アップデートのたびにマイナーバージョンを増やします。 メジャーバージョンは正式リリース時に 1 とし、以降はアドオンのUIなどに影響する大きな修正を行うときに増やします。 機能追加などの軽微な修正の場合は、マイナーバージョンを増やしていきます。 なお、メジャーバージョンを増やしたときは、マイナーバージョンを 0 に戻します。

例えば、正式リリース直後に初めて細かい修正を加えたときの version に指定する値は (1, 1) となります。

blender

アドオンが動作する最古のBlenderのバージョンを、次の形式で指定します。

(メジャーバージョン, マイナーバージョン, 0)

Blenderのバージョンが2.80のとき、(2, 80, 0) を指定します。

基本的に、アドオン開発時に利用したBlenderのバージョンを指定しておけばよいと思います。 アドオンを更新したとき、修正時に使用したBlenderと開発時に使用したBlenderのバージョンが異なる場合は、blender に指定する値も修正することを忘れないようにしましょう。

なお、指定したバージョンよりも古いバージョンのBlenderでアドオンを有効化すると、警告メッセージが表示されます。

実際、どのような警告メッセージが表示されるか確認してみましょう。 blender に (2, 90, 0) を指定してアドオンを有効化すると、次のように警告メッセージが表示されます。

location

アドオンの機能を使うためのUIが存在する場所を指定します。 例えば、[3Dビューポート] スペースの [追加] > [メッシュ] に追加する場合は、3Dビューポート > 追加 > メッシュ のように指定します。

description

アドオンが持つ機能を記載します。

表示できるスペースが非常に少ないことから、簡潔に記載することを目指すべきですが、もしアドオンが多くの機能を備える場合などで記載内容が多くなる場合は、location と同様 "See Add-ons Preferences" などと記載し、プリファレンスのアドオン設定情報に記載するとよいと思います。

warning

本項目を指定すると、警告アイコンと warning に指定した文字列が、[プリファレンス] のアドオン情報に表示されるようになります。 本項目は、アドオンが正式リリース前のテスト中であることを示す場合や、機能の一部に不具合があることがわかっている場合に指定します。

support

アドオンの サポートレベル を、次の3つから選択します。

1-2節 で説明したアドオンのリリースレベルとは異なることに注意してください。 リリースレベルがアドオンのメンテナンス状況などを示すのに対し、こちらはアドオンをサポートする人やアドオンの状態を示すために使われます。

[プリファレンス] では、インストールされたアドオンについて、サポートレベルでフィルタリングして表示できます。 例えば、[プリファレンス] にて [テスト中] ボタンのみを選択状態にすることで、'TESTING' が設定されたアドオンのみを表示できます。

本書で紹介する全てのサンプルアドオンは、support のキーに対して TESTING が設定されています。 このため、[テスト中] ボタンのみを選択することで、サンプルアドオンをすぐに見つけることができます。

doc_url (wiki_url)

アドオンのチュートリアルなど、アドオンに関するドキュメントが存在するWebページのURLを指定します。 Blender公式のWikiページにアドオンのドキュメントを公開している場合は、Blender公式のWikiページ（https://wiki.blender.org/wiki/Extensions:2.6/Py/Scripts）を指定できます。

tracker_url

アドオンに不具合があることが発覚したとき、ユーザが開発者へ不具合の報告をするためのWebページのURLを指定します。 リリースレベルがOfficialまたはContribであれば、D.B.Oのバグ報告ページ（https://developer.blender.org/maniphest/task/edit/form/1/）を指定することになりますが、個別にアドオンのサポートページを持つ場合は、そのページを指定しても問題ありません。

category

機能の種類によって、アドオンをカテゴリとして分類できます。 category には、アドオンが属するカテゴリを指定します。

カテゴリ一覧は、[プリファレンス] から確認できます。 アドオンのカテゴリは英語で指定する必要があるため、Blenderを日本語化している人は一度英語に戻し、カテゴリの正式名称を確認しましょう。

既存のカテゴリに分類できない場合は、新たなカテゴリを作ることもできます。 category に "Sample" を指定すると、次のように新たなカテゴリとして「Sample」が追加されていることがわかります。

オペレータクラスの作成

アドオンからBlenderに対して何かしらの操作を行うためには、オペレータ の具体的な処理を定義する必要があります。 オペレータの具体的な処理は、オペレータクラス を作成して定義します。 オペレータクラスは、bpyモジュールが提供するクラスである、bpy.types.Operator を継承して作成します。 なお、オペレータクラスのクラス名は、フォーマットXXX_OT_YYY に従う必要があります。 XXX は英大文字から始まる英字/数字/アンダースコア（_）から構成される文字列、YYY は英字/数字/アンダースコア（_）から構成される文字列です。

ここでは、オペレータクラスの作成方法を説明します。 最初に、オペレータクラスのクラス変数の宣言例を次に示します。

# オブジェクト（ICO球）を生成するオペレータ
class SAMPLE21_OT_CreateObject(bpy.types.Operator):

    bl_idname = "object.sample21_create_object"
    bl_label = "球"
    bl_description = "ICO球を追加します"
    bl_options = {'REGISTER', 'UNDO'}

オペレータクラスには、次のようなクラス変数を含める必要があります。

bl_idname には、Blender内部で使用するIDを設定します。 bl_idname は自由に決めてもよいですが、<アドオンのカテゴリ>.<任意の文字列> のように指定し、Blender内で唯一の文字列である必要があります。 本節のサンプルアドオンでは、作成するアドオンのカテゴリが OBJECT であることから、IDを "object.sample21_create_object" としました。

bl_options には、オペレータクラスの処理の属性を、set 型で指定します。 本節のサンプルアドオンでは、オペレータをメニューに登録するための 'REGISTER' と、エラー発生時にオペレータの処理実行前の状態へ戻すことを可能にするための 'UNDO' を指定しました。

bl_idname 、bl_label 、bl_description に指定した値は、次の図のように追加したメニューの項目から確認できます。

続いて、メニューを実行したときに呼ばれる execute メソッドを作成します。

# メニューを実行したときに呼ばれる関数
def execute(self, context):
    bpy.ops.mesh.primitive_ico_sphere_add()
    print("サンプル 2-1: ICO球を生成しました。")

    return {'FINISHED'}

execute メソッドには、メニューを実行したときの処理を定義します。

execute メソッドが呼ばれると、次に示す引数がBlender本体から渡されてきます。 なお、本節のサンプルアドオンではこれらの引数を利用しないため、特に意識する必要はありません。

execute メソッドの処理を解説します。

最初に、bpy.ops.mesh.primitive_ico_sphere_add 関数を呼んでいます。 これは、Blenderが提供しているAPIの1つで、[3Dビューポート] スペースにICO球を生成します。 この関数には複数の引数を渡すことができますが、本節のサンプルアドオンでは引数を指定していないため、3Dカーソルの位置にICO球が生成されます。

bpy.ops.mesh.primitive_ico_sphere_add 関数には、例えば次の引数を渡すことができます。

ソースコードを改造し、bpy.ops.mesh.primitive_ico_sphere_add 関数に引数を指定して実行してみましょう。

ICO球のサイズが2.0倍、ICO球生成時の座標が(x, y, z) = (5.0, -5.0, 0.0)、回転角（ラジアン）が(x, y, z) = (0.79, 0.0, 1.57)となるようにICO球を作成するため、execute メソッドを次のように書き換えます。

# メニューを実行したときに呼ばれる関数
def execute(self, context):
    bpy.ops.mesh.primitive_ico_sphere_add(radius=2.0, location=(5.0, -5.0, 0.0), rotation=(0.79, 0.0, 1.57))
    print("サンプル 2-1: ICO球を生成しました。")

    return {'FINISHED'}

アドオンを有効化し、[3Dビューポート] スペースのメニューから [追加] > [メッシュ] > [球] を実行すると、図のように指定した引数によって、ICO球の生成方法が変わったことが確認できます。

bpy.ops.mesh.primitive_ico_sphere_add 関数がICO球を作成する関数であると書きましたが、この関数がICO球を作成する関数であることを、どのようにして知ることができたのでしょうか？
Blender公式のAPIリファレンスから探すこともできますが、本APIについてはより簡単に調べる方法があります。
Blenderでは、メニューやボタンをマウスオーバーすることで、メニューを実行したときに呼び出される関数を表示できます。 このため、[3Dビューポート] スペースのメニュー [追加] > [メッシュ] > [ICO球] にマウスカーソルを置くことで、ICO球を生成する関数を確認できます。
さらに、この状態で [Ctrl] + [C] を押すことで、表示されているAPIの関数をクリップボードにコピーできます。

これら方法で確認できるのは、メニューなどで提供される機能に限りますが、手軽にAPIを確認できるため、覚えておいて損はないでしょう。

続いて print 関数を呼んでいますが、print 関数は引数に指定した文字列をコンソールウィンドウに表示する関数です。

最後に return で値を返しますが、execute メソッドで返す値は次のいずれかになります。 本節のサンプルアドオンでは、処理が正常に終了したことを示す {'FINISHED'} を返しています。

本節の時点では、{'FINISHED'} と {'CANCELLED'} を覚えておけばよいと思います。

メニューを構築する関数

オペレータクラスを作成しただけでは、オペレータがメニューなどのUIには登録されません。 メニューへ登録するためには、メニューへ登録するための処理を記述する必要があります。

最初に、メニューを構築するための関数 menu_fn を作成します。 menu_fn 関数は、あとで解説するアドオン有効化・無効化時に呼ばれる関数の中で利用します。

# メニューを構築する関数
def menu_fn(self, context):
    self.layout.separator()
    self.layout.operator(SAMPLE21_OT_CreateObject.bl_idname)

メニューの編集は、メンバ変数 self.layout を用いて行います。

self.layout.operator メソッドの引数に SAMPLE21_OT_CreateObject.bl_idnameを指定することで、作成したオペレータクラスの処理をメニューに登録できます。

さらに本節のサンプルアドオンでは、新たに作成するメニュー項目と既存のメニュー項目とを分けるためのセパレータ（メニュー項目を区切る横線）を追加しています。 セパレータの追加は、self.layout.separator メソッドで行うことができます。

アドオン有効化時に呼ばれる関数の作成

アドオン有効化時には、register 関数が呼ばれます。

# アドオン有効化時の処理
def register():
    for c in classes:
        bpy.utils.register_class(c)
    bpy.types.VIEW3D_MT_mesh_add.append(menu_fn)
    print("サンプル 2-1: アドオン『サンプル 2-1』が有効化されました。")

bpy.utils.register_class 関数は、引数に指定したクラスを登録し、Blender内で使えるようにするための関数です。 サンプルアドオンでは、登録するオペレータクラス一式を変数 classes にまとめ、register 関数の中で bpy.utils.register_class 関数を使って1つずつオペレータクラスを登録しています。

bpy.types.VIEW3D_MT_mesh_add.append メソッドに、先ほど定義したメニューを構築する関数である menu_fn 関数を指定することで、[3Dビューポート] スペースのメニュー [追加] > [メッシュ] に項目を追加できます。

最後に print 関数で、アドオンが有効化されたことをコンソールウィンドウへ出力します。

アドオン無効化時に呼ばれる関数の作成

アドオン無効化時には、unregister 関数が呼ばれます。

# アドオン無効化時の処理
def unregister():
    bpy.types.VIEW3D_MT_mesh_add.remove(menu_fn)
    for c in classes:
        bpy.utils.unregister_class(c)
    print("サンプル 2-1: アドオン『サンプル 2-1』が無効化されました。")

bpy.types.VIEW3D_MT_mesh_add.remove メソッドに、menu_fn 関数を指定することで、[3Dビューポート] スペースのメニュー [追加] > [メッシュ] から、アドオン有効化時に追加した項目を削除できます。

bpy.utils.unregister_class 関数は、引数に指定したクラスをBlenderから登録解除し、利用を禁止する関数です。 unregister 関数の中で、bpy.utils.unregister_class 関数を使って1つずつオペレータクラスを登録解除しています。

最後に print 関数で、アドオンが無効化されたことをコンソールウィンドウへ出力します。

メイン処理

最後に、メイン処理について説明します。

[テキストエディター] スペースのメニュー [テキスト] > [スクリプト実行] を実行したときに呼ばれる処理が、メイン処理です。

|

メイン処理では、アドオンの登録処理のみ行っています。

アドオンの場合、メイン処理は必要な処理ではありませんが、慣習として書くことが多いです。

# メイン処理
if __name__ == "__main__":
    register()

まとめ

ICO球を [3Dビューポート] スペース上に生成するアドオンを作成し、アドオンのソースコードを解説しました。

本節で紹介したサンプルアドオンは、シンプルな機能しか持たないアドオンでしたが、覚えることが多くて混乱された人も多いと思います。 しかし、アドオン開発に必要な知識をここでしっかりと理解しておくことで、次節以降の内容をスムーズに理解できると思います。 本節で説明したことを理解してから、次節に進むようにしてください。 なお、この時点で完全に理解できていない状態で先に進めてしまっても、わからなくなったときに本節に戻ってきて復習すれば問題ありません。

ポイント

• Blenderが提供するAPIを使うためには、bpyモジュールをインポートする必要がある
• bl_info 変数は、アドオンに関する情報をBlenderに伝えるために指定する変数である
• オペレータの処理は、bpy.types.Operator クラスを継承したオペレータクラスの execute メソッドに記述する
• register 関数は、アドオン有効化時に呼ばれる関数であり、オペレータクラスなどの登録やメニューの構築を行う処理を記述する
• unregister 関数は、アドオン無効化時に呼ばれる関数であり、オペレータクラスなどの登録解除や構築したメニューの破棄を行う処理を記述する
• [テキストエディター] スペースからスクリプトを実行したときに呼ばれるメイン処理は、アドオンでは不要であるが、慣習として書くことが多い