Blender Python APIでカスタムアドオンを作成！独自の機能を追加しよう！

2023.03.30

こんにちは、管理人のウノケンです。

今回は、Blender Python APIを使ってアドオンを作成する方法について解説していきます。

Blenderは、3Dモデリングやアニメーション制作などに利用されるオープンソースの3Dアプリケーションです。Pythonとの親和性も高く、うまく使いこなすことができれば手作業による面倒な反復作業を自動化することが可能です。

この記事では、Pythonスクリプトを使ったBlenderの操作について、「アドオンの作成」にフォーカスして解説していきます。3Dモデリング初心者の方や、Pythonになじみのない方でもコピペで操作を実行することができるので、ぜひ自分でも操作して自動化の利便性を感じてみてください。

なお、Blender Python APIについての解説や、Pythonスクリプトを使ったBlenderの基本操作については以下の記事で解説しています。

今回はBlenderをPythonで簡単に操作する方法について、画像を豊富に用いて初心者向けに解説していきます。紹介しているスクリプトの例は、3Dモデリング初心者の方や、Pythonになじみのない方でもコピペで操作を実行することが可能です。ぜひ自分でも操作して自動化の利便性を感じてみてください。

それでは見ていきましょう！

Blenderの「アドオン」とは
アドオンの基本構造
1. アドオンのフォルダとファイル構成
2. 必須のメタデータと関数
オペレータとUIパネルの作成
【実践例】簡単なアドオンの作成（らせん形状を一瞬で追加！）
1. アドオンのテスト
2. アドオンのインストール
まとめ

Blenderの「アドオン」とは

Blenderのアドオンとは、Blenderの機能を拡張するプラグインです。アドオンを使用することで、新しいオブジェクトを生成したり、特定のタスクを自動化したり、Blenderのユーザーインターフェースをカスタマイズしたりできます。

Blenderには公式のアドオンや、ダウンロードして使用できるアドオンが存在します。下の画像のように「編集」→「プリファレンス…」からBlenderプリファレンスを表示し、「アドオン」の中から使いたい項目のチェックボックスをオン・オフすることで、有効化・無効化することができます。

アドオンはPythonスクリプトを使って作成されています。

「こんな機能があればいいのに。。。」

「毎回この作業するの面倒だな。。。」

「Pythonスクリプトをいちいち実行するのも面倒。。。」

Blenderユーザーなら一度は思ったことがあるのではないでしょうか？

Blender Python APIを活用すれば、そんな機能・作業をカスタムのアドオンとして実装することが可能です。

この記事を読めば、自分が使いたい機能をアドオンとして実装する方法について、ひと通り理解することができます。アドオンの基本構造から、オペレータやUIパネルの実装方法まで、順を追って理解していきましょう。

「細かい話はいいから実例とスクリプトが見たい！」という方は、後述する実践例までジャンプしてください。

アドオンの基本構造

アドオンのフォルダとファイル構成

アドオンのフォルダ・ファイル構成の実例を見てみましょう。

公式アドオンのスクリプトは、Blenderのインストールフォルダ内にあるscripts/addonsフォルダに格納されています。例えばmacOSの場合は、

/Applications/Blender.app/Contents/Resources/<version>/scripts/addons

のフォルダに移動すると、多数のアドオンが格納されていることを確認できます。

一例として、「インポート/エクスポート：STLフォーマット」アドオンの場合、以下のようなファイル構成になっています。

io_mesh_stl/
- __init__.py
- blender_utils.py
- utils.py

__init__.pyはアドオンのエントリポイントであり、アドオンのメタデータや必須の関数が定義されています。フォルダ形式で提供されるものであれば、基本的にどのアドオンにも存在しています。

他のファイルはアドオンのコンポーネントを実装する目的などに使用されます。

必須のメタデータと関数

アドオンの__init__.pyには、以下のメタデータと関数が定義されている必要があります。

bl_info: アドオンの情報を格納した辞書
register(): アドオンのコンポーネントを登録する関数
unregister(): アドオンのコンポーネントを解除する関数

オペレータとUIパネルの作成

オペレータは、Blenderで実行されるアクションです。例えば、オブジェクトの追加や変換、モディファイアの適用などがオペレータによって実行されます。

UIパネルは、Blenderのユーザーインターフェイスに表示されるパネルです。これにより、オペレータやプロパティをユーザーがGUI上で使用できるようになります。

オペレータとUIの作成方法について確認していきましょう。

「細かい話はいいから実例とスクリプトが見たい！」という方は、後述する実践例までジャンプしてください。

オペレータのクラス定義とメソッド

オペレータは、bpy.types.Operatorを継承したクラスで定義されます。このクラスでは、以下のようなメソッドを実装します。

poll(): オペレータが実行可能なコンテキストを判断する関数。この関数がTrueを返す場合、オペレータが実行可能。
execute(): オペレータが実行されたときに呼び出される関数。ここでアクションが実装される。
invoke(): オペレータが呼び出されたときに最初に実行される関数。例えば、ユーザー入力やポップアップウィンドウを表示する場合に使用します。
draw(): オペレータのインターフェイスを描画する関数。通常、UIパネルで使用されます。

オペレータを登録・解除する方法

オペレータは、

bpy.utils.register_class()関数を使って登録
bpy.utils.unregister_class()関数を使って解除

されます。

これらの関数は、アドオンのregister()およびunregister()関数内で呼び出されます。

UIパネルのクラス定義とメソッド

UIパネルは、bpy.types.Panelを継承したクラスで定義されます。このクラスでは、以下のような属性を設定します。

bl_label: パネルのタイトル
bl_idname: パネルの一意の識別子
bl_space_type: パネルが表示されるエリアのタイプ
bl_region_type: パネルが表示されるリージョンのタイプ

UIパネルにはdraw()メソッドを実装します。このメソッドは、パネルのインターフェイスを描画するために使用されます。

UIパネルを登録・解除する方法

UIパネルも、オペレータと同様に、bpy.utils.register_class()関数を使って登録され、bpy.utils.unregister_class()関数を使って解除されます。

【実践例】簡単なアドオンの作成（らせん形状を一瞬で追加！）

ここまで確認してきたアドオンの基礎をもとに、実際に簡単なアドオンを作成してみましょう。

以下のスクリプトは、3Dビューポートに表示されるUIパネルから、らせん形状（Helix）のメッシュを追加するアドオンになっています。

bl_info = {
    "name": "Add Helix",
    "author": "Name",
    "version": (1, 0),
    "blender": (3, 4, 1),
    "location": "View3D > Add > Mesh > Add Helix",
    "description": "Adds a new Helix object",
    "category": "Add Mesh",
}

import bpy
import math
from bpy.types import Operator
from bpy.props import FloatProperty, IntProperty
from bpy_extras.object_utils import AddObjectHelper, object_data_add

# create_helix：指定されたパラメータでヘリックスを生成し、シーンに追加
# context: オペレータ実行のコンテキスト
# turns: ヘリックスの回転数
# radius: ヘリックスの半径
# height: ヘリックスの高さ
def create_helix(context, turns, radius, height):
    vertices = []
    edges = []
    num_segments = 32 * turns

    for i in range(num_segments + 1):
        theta = 2 * math.pi * i / 32
        x = radius * math.cos(theta)
        y = radius * math.sin(theta)
        z = (height / num_segments) * i
        vertices.append((x, y, z))

        if i < num_segments:
            edges.append((i, i + 1))

    mesh = bpy.data.meshes.new(name="Helix")
    mesh.from_pydata(vertices, edges, [])
    mesh.update()
    object_data_add(context, mesh, operator=None)

# MESH_OT_add_helix：新しいヘリックスオブジェクトをシーンに追加するオペレータ
# turns: ヘリックスの回転数（プロパティ）
# radius: ヘリックスの半径（プロパティ）
# height: ヘリックスの高さ（プロパティ）
class MESH_OT_add_helix(Operator, AddObjectHelper):
    bl_idname = "mesh.add_helix"
    bl_label = "Add Helix"
    bl_options = {'REGISTER', 'UNDO'}

    turns: IntProperty(
        name="Turns",
        description="Number of turns",
        default=3,
        min=1,
        max=10
    )
    radius: FloatProperty(
        name="Radius",
        description="Radius of the helix",
        default=1.0,
        min=0.1,
        max=10.0
    )
    height: FloatProperty(
        name="Height",
        description="Height of the helix",
        default=2.0,
        min=0.1,
        max=10.0
    )

    # execute：オペレータが実行されたときに呼び出される
    # Helixの生成とシーンへの追加
    def execute(self, context):
        create_helix(context, self.turns, self.radius, self.height)
        return {'FINISHED'}

# menu_func：アドオンのオペレータを3Dビューの "Add Mesh" メニューに追加
def menu_func(self, context):
    self.layout.operator(MESH_OT_add_helix.bl_idname, text="Helix", icon='MESH_CUBE')

# register：アドオンのオペレータを登録し、メニューに追加
def register():
    bpy.utils.register_class(MESH_OT_add_helix)
    bpy.types.VIEW3D_MT_mesh_add.append(menu_func)

# unregister：アドオンのオペレータの登録を解除し、メニューから削除
def unregister():
    bpy.utils.unregister_class(MESH_OT_add_helix)
    bpy.types.VIEW3D_MT_mesh_add.remove(menu_func)

if __name__ == "__main__":
    register()