MRが楽しい

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

Blenderのpythonテンプレートを読み解く その1(addon_add_object.py)

本日は Blender の小ネタ枠です。
Blenderpythonテンプレートを読み解いて、どんな機能を持つテンプレートなのか確認します。
今回は「addon_add_object」テンプレートです。
f:id:bluebirdofoz:20200618085842j:plain

pythonテンプレートの利用方法

[テキストエディタ]ビューを開き、メニューから テンプレート -> python を開きます。
様々な機能を持った python コードのテンプレートが利用できます。
f:id:bluebirdofoz:20200618085852j:plain

addon_add_object.py

スクリプトBlender アドオンのサンプルスクリプトです。
スクリプトを実行すると bpy.ops.mesh.add_object の Operator が追加されます。
Operator は[3Dビュー]の 追加 -> メッシュ 配下に登録されます。
f:id:bluebirdofoz:20200618085901j:plain

処理を実行すると、四角形の平面メッシュのオブジェクトが[New Object Mesh]の名前で追加されます。
調整パネルからパラメータの scale を変更することでメッシュの大きさを変更できます。

以下はテンプレートの内容にコメントを追加したものです。
・addon_add_object.py

# bl_infoでプラグインに関する情報の定義を行う
bl_info = {
    "name": "New Object",                            # プラグイン名
    "author": "Your Name Here",                      # 制作者名
    "version": (1, 0),                               # バージョン
    "blender": (2, 80, 0),                           # 動作可能なBlenderバージョン
    "location": "View3D > Add > Mesh > New Object",  # 機能の位置付け
    "description": "Adds a new Mesh Object",         # 説明文
    "warning": "",                                   # 注意点やバグ情報
    "doc_url": "",                                   # ドキュメントURL
    "category": "Add Mesh",                          # カテゴリ名
}

# 利用するタイプやメソッドのインポート
import bpy
from bpy.types import Operator
from bpy.props import FloatVectorProperty
from bpy_extras.object_utils import AddObjectHelper, object_data_add
from mathutils import Vector

# オブジェクト追加機能のメソッド
def add_object(self, context):
    # 引数の scale 情報を取得
    scale_x = self.scale.x
    scale_y = self.scale.y

    # scale に合わせて面の4つの頂点を作成する
    verts = [
        Vector((-1 * scale_x, 1 * scale_y, 0)),
        Vector((1 * scale_x, 1 * scale_y, 0)),
        Vector((1 * scale_x, -1 * scale_y, 0)),
        Vector((-1 * scale_x, -1 * scale_y, 0)),
    ]

    # 4つの頂点を繋ぐ面を1つ作成する
    edges = []
    faces = [[0, 1, 2, 3]]

    # 「New Object Mesh」の名前で新規メッシュを作成する
    mesh = bpy.data.meshes.new(name="New Object Mesh")
    # 作成した頂点と面をメッシュに反映する
    mesh.from_pydata(verts, edges, faces)
    
    # メッシュが無効である可能性がある場合は mesh.validate(verbose=True) を使います
    # 参考URL:https://docs.blender.org/api/current/bpy.types.Mesh.html#bpy.types.Mesh.from_pydata
    # useful for development when the mesh may be invalid.
    # mesh.validate(verbose=True)

    # 作成したメッシュのオブジェクトを追加する
    object_data_add(context, mesh, operator=self)

# Operatorクラスの作成
# 継承するクラスの命名規則は以下の通り
# [A-Z][A-Z0-9_]*_(継承クラスごとの識別子)_[A-Za-z0-9_]+
# クラスごとの識別子は以下の通り
#   bpy.types.Operator  OT
#   bpy.types.Panel     PT
#   bpy.types.Header    HT
#   bpy.types.MENU      MT
#   bpy.types.UIList    UL
class OBJECT_OT_add_object(Operator, AddObjectHelper):
    # クラスの説明文
    # (マウスオーバー時に表示)
    # bl_description = "***" の記法でも可能
    """Create a new Mesh Object"""
    # クラスのIDを定義する
    # (Blender内部で参照する際のIDに利用)
    bl_idname = "mesh.add_object"
    # クラスのラベルを定義する
    # (デフォルトのテキスト表示などに利用)
    bl_label = "Add Mesh Object"
    # クラスの属性
    # 以下の属性を設定できる
    #   REGISTER      : Operatorを情報ウィンドウに表示し、やり直しツールバーパネルをサポートする
    #   UNDO          : 元に戻すイベントをプッシュする(Operatorのやり直しに必要)
    #   UNDO_GROUPED  : Operatorの繰り返しインスタンスに対して単一の取り消しイベントをプッシュする
    #   BLOCKING      : 他の操作がマウスポインタ―を使用できないようにブロックする
    #   MACRO         : Operatorがマクロであるかどうかを確認するために使用する
    #   GRAB_CURSOR   : 継続的な操作が有効な場合にオペレーターがマウスポインターの動きを参照して、操作を有効にする
    #   GRAB_CURSOR_X : マウスポインターのX軸の動きのみを参照する
    #   GRAB_CURSOR_Y : マウスポインターのY軸の動きのみを参照する
    #   PRESET        : Operator設定を含むプリセットボタンを表示する
    #   INTERNAL      : 検索結果からOperatorを削除する
    # 参考URL:https://docs.blender.org/api/current/bpy.types.Operator.html#bpy.types.Operator.bl_options
    bl_options = {'REGISTER', 'UNDO'}

    # 自作プロパティの定義
    # 参考URL:https://docs.blender.org/api/current/bpy.props.html
    scale: FloatVectorProperty(
        name="scale",             # プロパティ名
        default=(1.0, 1.0, 1.0),  # デフォルト値
        subtype='TRANSLATION',    # サブタイプ
        description="scaling",    # 説明文
    )

    # Operator実行時の処理
    def execute(self, context):

        # オブジェクト追加機能のメソッドを呼び出す
        add_object(self, context)

        return {'FINISHED'}


# 登録に関する処理
# Registration
# ボタンのレイアウト(テキスト/アイコン)を定義する
def add_object_button(self, context):
    self.layout.operator(
        OBJECT_OT_add_object.bl_idname,
        text="Add Object",
        icon='PLUGIN')

# 右クリックで表示されるオンラインマニュアルとAPIリファレンスのリンクを定義する
# This allows you to right click on a button and link to documentation
def add_object_manual_map():
    # オンラインマニュアルURLのプレフィックス
    url_manual_prefix = "https://docs.blender.org/manual/en/latest/"
    # オンラインマニュアルのマッピング定義
    # (IDが存在しない場合はOperatorタイプのトップページを表示する)
    url_manual_mapping = (
        ("bpy.ops.mesh.add_object", "scene_layout/object/types.html"),
    )
    return url_manual_prefix, url_manual_mapping

# 作成クラスと定義の登録メソッド
def register():
    bpy.utils.register_class(OBJECT_OT_add_object)
    bpy.utils.register_manual_map(add_object_manual_map)
    bpy.types.VIEW3D_MT_mesh_add.append(add_object_button)

# 作成クラスと定義の登録解除メソッド
def unregister():
    bpy.utils.unregister_class(OBJECT_OT_add_object)
    bpy.utils.unregister_manual_map(add_object_manual_map)
    bpy.types.VIEW3D_MT_mesh_add.remove(add_object_button)

# 実行時の処理
if __name__ == "__main__":
    # 作成クラスと定義を登録する
    register()