作成するアドオンの仕様

[3Dビューポート] スペースのメニュー [オブジェクト] に [並進移動] を追加
[オブジェクト] > [並進移動] を実行すると、[3Dビューポート] スペースにオペレータプロパティが表示される。オペレータプロパティに指定された [移動軸] と [移動量] にしたがって、アクティブなオブジェクトが並進移動する

オペレータプロパティとは？

Blenderでは、オペレータを実行すると、オペレータに対するパラメータを設定するためのUI（オペレータプロパティ）が、Toolbarの下側に表示されます。オペレータプロパティは、直前に行った操作に対して、パラメータを調節して再度オペレータを実行するときに使用します。

本節のサンプルアドオンでは、並進移動時の移動量と移動軸を、オペレータプロパティから指定できるようにします。

アドオンを作成する

1-5節を参考に、次に示すソースコードを入力し、ファイル名 sample_2-3.py で保存します。

import bpy
from bpy.props import FloatProperty, EnumProperty


bl_info = {
    "name": "サンプル 2-3: オブジェクトを並進移動するアドオン②",
    "author": "ぬっち（Nutti）",
    "version": (3, 0),
    "blender": (2, 80, 0),
    "location": "3Dビューポート > オブジェクト",
    "description": "アクティブなオブジェクトを並進移動するサンプルアドオン（移動量、移動軸 任意指定版）",
    "warning": "",
    "support": "TESTING",
    "doc_url": "",
    "tracker_url": "",
    "category": "Object"
}


# オブジェクトを並進移動するオペレータ
class SAMPLE23_OT_TranslateObject(bpy.types.Operator):

    bl_idname = "object.sample23_translate_object"
    bl_label = "並進移動"
    bl_description = "アクティブなオブジェクトを並進移動します"
    bl_options = {'REGISTER', 'UNDO'}

    axis: EnumProperty(
        name="移動軸",
        description="移動軸を設定します",
        default='X',
        items=[
            ('X', "X軸", "X軸に沿って並進移動します"),
            ('Y', "Y軸", "Y軸に沿って並進移動します"),
            ('Z', "Z軸", "Z軸に沿って並進移動します"),
        ]
    )

    amount: FloatProperty(
        name="移動量",
        description="移動量を設定します",
        default=1.0,
    )

    # メニューを実行したときに呼ばれるメソッド
    def execute(self, context):
        active_obj = context.active_object
        if self.axis == 'X':
            active_obj.location[0] += self.amount
        elif self.axis == 'Y':
            active_obj.location[1] += self.amount
        elif self.axis == 'Z':
            active_obj.location[2] += self.amount
        self.report({'INFO'}, "サンプル 2-3: 『{}』を{}軸方向へ {} 並進移動しました。"
                              .format(active_obj.name, self.axis, self.amount))
        print("サンプル 2-3: オペレータ『{}』が実行されました。".format(self.bl_idname))

        return {'FINISHED'}


def menu_fn(self, context):
    self.layout.separator()
    self.layout.operator(SAMPLE23_OT_TranslateObject.bl_idname)


classes = [
    SAMPLE23_OT_TranslateObject,
]


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


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


if __name__ == "__main__":
    register()

アドオンを使用する

アドオンを有効化する

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

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

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

また、[3Dビューポート] スペースのメニューに [オブジェクト] > [並進移動] が追加されていることを確認します。

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

次の手順に従い、作成したアドオンの機能を使います。

1	Blender起動直後に生成されているオブジェクト [Cube] を選択します
2	[3Dビューポート] スペースのメニュー [オブジェクト] > [並進移動] を実行すると、選択したオブジェクト [Cube] が並進移動します。この状態でエリア左下を見てみましょう。[並進移動] のラベルの下に [移動軸] と [移動量] というオペレータプロパティが追加され、数値を入力できるようになっています。
3	[移動軸] や [移動量] の数値を変更してみましょう。指定した値に応じて、オブジェクトが並進移動する移動軸や移動量が変わります。また、オペレータプロパティを変更するたびにオペレータメッセージが表示されます。

アドオンを無効化する

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

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

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

ソースコードの解説

サンプルアドオンのソースコードを解説します。

オペレータプロパティの作成

オペレータプロパティを用いて、直前に実行したオペレータのパラメータを調整して再実行できるようにするためには、bpy.props に定義されている プロパティクラス を、オペレータクラスのクラス変数として定義します。

利用できるプロパティクラスを、次に示します。

クラス名	型
`IntProperty`	整数
`IntVectorProperty`	整数（グループ）
`FloatProperty`	浮動小数点
`FloatVectorProperty`	浮動小数点（グループ）
`StringProperty`	文字列
`BoolProperty`	ブーリアン（Blender上ではチェックボックスのUIとなる）
`BoolVectorProperty`	ブーリアン（グループ）
`EnumProperty`	列挙型（Blender上ではセレクトボックスのUIとなる）

プロパティクラス作成時に引数を指定することで、オペレータクラスの設定を変更できます。代表的な引数を次に示しますが、クラスによって指定可能な引数が異なるため注意が必要です。

引数	型	値の説明
`name`	`str`	名前
`description`	`str`	説明文
`default`	プロパティクラスによって異なる	デフォルト値
`items`	`list`	`EnumProperty`で表示する項目リスト

サンプルアドオンでは、EnumProperty クラスを用いて移動軸を、FloatPropery クラスを用いて移動量を指定できるようにします。

axis: EnumProperty(
    name="移動軸",
    description="移動軸を設定します",
    default='X',
    items=[
        ('X', "X軸", "X軸に沿って並進移動します"),
        ('Y', "Y軸", "Y軸に沿って並進移動します"),
        ('Z', "Z軸", "Z軸に沿って並進移動します"),
    ]
)

amount: FloatProperty(
    name="移動量",
    description="移動量を設定します",
    default=1.0,
)

引数 name はオペレータプロパティの名称で、サンプルアドオンではそれぞれ "移動軸" と "移動量" を指定しています。引数 description はオペレータプロパティの説明文で、マウスオーバーしたときに表示される文字列です。引数 default には、それぞれ 'X' と 1.0 が指定されているため、デフォルトではオペレータを実行したときに、X軸正方向に1.0だけ並進移動するようになっています。 EnumProperty の items には、選択項目のリストを渡します。選択項目のリストは、次の要素からなるタプルのリストです。

要素	型	要素の意味
第1要素	`str`	識別子（項目選択時に変数に設定される値）
第2要素	`str`	セレクトボックスに表示される項目名
第3要素	`str`	セレクトボックスに表示される項目の説明

オペレータプロパティの値を変更すると、オペレータクラスの execute メソッドが実行されます。 execute メソッドの中で指定されたオペレータプロパティの値は、通常のクラス変数と同様、self変数からアクセスできます。

if self.axis == 'X':
    active_obj.location[0] += self.amount
elif self.axis == 'Y':
    active_obj.location[1] += self.amount
elif self.axis == 'Z':
    active_obj.location[2] += self.amount

本節のサンプルのように、値を連続的に変更可能なオペレータプロパティを作成した場合、値が変更される度に execute メソッドが呼ばれます。 execute メソッドの処理が重い場合は、値を変更するだけで多くの処理時間がかかってしまいます。オペレータプロパティを変更できるようにする場合は、execute メソッドの処理が可能な限り軽くなるようにしましょう。

まとめ

事前に実行したオペレータに対して、ユーザがオペレータプロパティから細かい制御ができるようにするための方法を紹介しました。本節のサンプルアドオンで紹介したオペレータプロパティ以外に、整数やブーリアンなどのオペレータプロパティも利用できるため、ぜひ一度試してみましょう。

ポイント

ユーザが直前に実行したオペレータに対して、オペレータプロパティを変更してオペレータを再実行できる
オペレータクラスにプロパティクラスのクラス変数を追加することで、オペレータプロパティを作成できる
オペレータプロパティに指定した値を変更すると、値を変更するたびにオペレータクラスの execute メソッドが実行される