スクリプティング¶

PMEは、Blenderの Python API を使用した高度なカスタマイズと自動化を可能にします。この記事では、PMEのスクリプティング機能の概要と、組み込まれたグローバル変数と関数について説明します。

重要

通常の Command / Custom とメニューの Poll は 1行のコード を入力します。長い処理や再利用する処理は外部の Python ファイルへ分け、コード欄には短い呼び出しを書きます。 AI が生成するコードにも、この入力先ごとの形式が適用されます。

入力先ごとの仕様と書き方はコードの入力と実行を参照してください。このページは関数・変数と引数を調べる API リファレンスです。

チュートリアル¶

グローバル変数¶

PMEの各スロットエディタ内で利用できる変数です。

変数	説明
`menu`	アクティブなメニューの名前
`slot`	アクティブなスロットの名前
`C`	bpy.context
`D`	bpy.data
`O`	bpy.ops
`T`	bpy.types
`P`	bpy.props
`L`	現在の UILayout オブジェクト L.box().label(text="My Label")
`E`	現在の Event オブジェクト E.ctrl and E.shift and message_box("Ctrl+Shift Pressed")
`U`	ユーザーデータ保存用の pme.UserData インスタンス U.foo = "value" U.update(foo="value1", bar="value2") U.foo U.get("foo", "default_value")

グローバル関数¶

PMEのスロットエディタ内で利用できる関数です。コマンドタブとカスタムタブで利用できる関数が異なります。

共通関数¶

execute_script(path, **kwargs)¶

外部のPythonスクリプトを実行します。

パラメータ:

path (str) -- スクリプトファイルパス。相対パス（pie_menu_editor フォルダから、推奨）または絶対パス。
kwargs -- スクリプトに渡される追加のキーワード引数。

戻り値:

スクリプト内の return_value またはデフォルトで True。

警告

信頼できるソースのスクリプトのみ配置・実行してください
実行前に内容を確認し、必要に応じてバックアップやテスト環境で検証してください
ファイル操作や設定変更など、環境に影響する処理が含まれる場合があります

スクリプト内で利用可能な変数：kwargs、__file__、return_value、PMEのすべてのグローバル変数

使用例:

# 基本的な実行と戻り値
execute_script("scripts/hello_world.py", msg="Hello World!")
message_box(execute_script("scripts/get_message.py"))

# scripts/hello_world.py
message_box(kwargs["msg"])

# scripts/get_message.py
return_value = "Hi!"

# パラメータを使用した処理
# scripts/process_data.py
kwargs = locals().get("kwargs", {})
result = my_function(kwargs.get("param1"), kwargs.get("param2", "default"))
return_value = result

# 呼び出し
result = execute_script("scripts/process_data.py", param1=200, param2="Hello")

# カスタムタブでのUI描画
# scripts/custom_ui.py
msg = kwargs.get("msg", pme.context.text or "Default Message")
box = L.box()
box.label(text=msg, icon=pme.context.icon, icon_value=pme.context.icon_value)

# 呼び出し
execute_script("scripts/custom_ui.py", msg="カスタムメッセージ")

props(name=None, value=None)¶

PMEプロパティの値を取得または設定します。

パラメータ:

name (str) -- プロパティの名前。
value -- プロパティの新しい値。

戻り値:

name が None の場合はPMEプロパティコンテナ、name のみが指定された場合はプロパティ値、値を設定する場合は True。

例:

# 文字列記法を使用してプロパティ値を取得
value = props("MyProperty")

# 代替: 属性記法を使用してプロパティを取得
value = props().MyProperty  # props()はプロパティコンテナを返す

# 文字列記法を使用してプロパティ値を設定
props("MyProperty", value)

# 代替: 属性記法を使用してプロパティを設定
props().MyProperty = value  # props()はプロパティコンテナを返す

paint_settings()¶

コンテキストに応じたペイント設定を取得します。

戻り値:: 現在のペイント設定、またはペイントモードでない場合は None。

例:

ps = paint_settings(); ps and L.template_ID_preview(ps, 'brush')

find_by(collection, key, value)¶

collection 内で key が value と等しい最初のアイテムを検索します。

戻り値:: 見つかった場合はコレクションアイテム、そうでなければ None。

例:

m = find_by(C.active_object.modifiers, "type", 'SUBSURF')

setattr(object, name, value)¶

Pythonの組み込み setattr() と同じですが、設定後に True を返します。

戻り値:: True

コマンドタブ関数¶

open_menu(name, slot=None, **kwargs)¶

名前を指定してメニュー、パイメニュー、ポップアップダイアログを開くか、スタックキー、スティッキーキー、モーダルオペレーター、またはマクロオペレーターを実行します。

パラメータ:

name (str) -- メニューの名前。
slot -- スタックキー実行のためのスロットのインデックスまたは名前。
kwargs -- ローカル変数として使用されるモーダル/マクロオペレーターの引数。

戻り値:

対象メニューが存在し、現在のコンテキストで利用可能な場合は True。対象が存在しない、無効化されている、Poll によりブロックされている、または指定スロットが見つからない場合は False。

例:

# アクティブオブジェクトのタイプに応じてメニューを開く:
open_menu("Lamp Pie Menu" if C.active_object.type == 'LAMP' else "Object Pie Menu")

# Ctrl修飾キーに応じて"My Stack Key"スロットを呼び出す:
open_menu("My Stack Key", "Ctrl slot" if E.ctrl else "Shift slot")

toggle_menu(name, value=None)¶

メニューを有効または無効にします。

パラメータ:

name (str) -- メニューの名前。
value (bool) -- 有効にする場合は True、無効にする場合は False、トグルする場合は None。

戻り値:

メニューが存在する場合は True、そうでなければ False。

tag_redraw(area=None, region=None)¶

UIエリアまたはリージョンを再描画します。

パラメータ:

area (str) -- 再描画する Area.type。None の場合はすべてのエリアを再描画。
region (str) -- 再描画する Region.type。None の場合はすべてのリージョンを再描画。

戻り値:

True

close_popups()¶

すべてのポップアップダイアログを閉じます。

戻り値:: True

overlay(text, **kwargs)¶

オーバーレイメッセージを描画します。

パラメータ:

text (str) -- 表示するメッセージ。
kwargs --
- alignment: ['TOP', 'TOP_LEFT', 'TOP_RIGHT', 'BOTTOM', 'BOTTOM_LEFT', 'BOTTOM_RIGHT'] のいずれか。デフォルトは 'TOP'。
- duration: 表示時間（秒）。デフォルトは 2.0。
- offset_x: 水平オフセット。デフォルトは 10 ピクセル。
- offset_y: 垂直オフセット。デフォルトは 10 ピクセル。

戻り値:

True

例:

overlay('Hello PME!', offset_y=100, duration=1.0)

message_box(text, icon='INFO', title='Pie Menu Editor')¶

メッセージボックスを表示します。

パラメータ:

text (str) -- 表示するメッセージ。
icon (str) -- アイコン名（例: 'INFO', 'ERROR', 'QUESTION' など）。
title (str) -- ウィンドウタイトル。

戻り値:

True

confirm_box(message, func=None, icon='QUESTION', width=0)¶

コマンドスロットから確認ダイアログを表示します。

パラメータ:

message (str) -- 表示するメッセージ。
func -- 真偽値を1引数で受け取る任意のコールバック。OK時は True、キャンセル時は False が渡されます。
icon (str) -- Blenderのアイコン名。デフォルトは 'QUESTION'。
width (int) -- ダイアログの幅（ピクセル）。0 はBlenderのデフォルト幅を使用します。

戻り値:

None。ユーザーが確定・キャンセルする前に戻ります。

確認後の処理はコールバック内に記述してください。confirm_box() の後のコードは確認を待たずに進みます。戻り値はユーザーの回答ではありません。

用例1: 確認後に現在のエリアを閉じる:

confirm_box(
    "Close this area?",
    func=lambda ok: bpy.ops.screen.area_close() if ok else None,
)

用例2: 確認後にPMEのMacroを実行する:

confirm_box(
    "Run this macro?",
    func=lambda ok: open_menu("My Macro") if ok else None,
)

My Macro は、作成済みで有効なMacroの名前に置き換えてください。このCommandは対象Macroの外に置きます。確認ダイアログはMacroの後続ステップを一時停止せず、同じMacroを指定すると再びそのMacroを呼び出します。どちらの用例もキャンセル時には何も実行しません。処理はコールバック時に利用可能なコンテキストで実行され、通常のオペレーターやメニューのPoll条件に従います。コールバックはダイアログ間で共有されるため、確認ダイアログは同時に1つだけ開いてください。

input_box(func=None, prop=None)¶

入力ボックスを表示します。

パラメータ:

func -- 入力値で呼び出す関数。
prop (str) -- 編集するプロパティへのパス。

戻り値:

True

例:

# オブジェクトの名前を変更:
input_box(prop="C.active_object.name")

# 入力値を表示:
input_box(func=lambda value: overlay(value))

カスタムタブ関数¶

draw_menu(name, frame=True, dx=0, dy=0)¶

別のポップアップダイアログまたはパイメニュー内にポップアップダイアログを描画します。

パラメータ:

name (str) -- メニュー（ポップアップダイアログ）の名前。
frame (bool) -- フレームを描画するかどうか。
dx (int) -- 水平オフセット。
dy (int) -- 垂直オフセット。

戻り値:

対象メニューが存在し、現在のコンテキストで利用可能な場合は True。対象が存在しない、無効化されている、または Poll によりブロックされている場合は、何も描画せず False。

operator(layout, idname, text='', icon='NONE', emboss=True, icon_value=0, **kwargs)¶

UILayout.operator() と似ていますが、オペレータープロパティの設定が可能です。

パラメータ:

layout -- UILayout インスタンス。
idname (str) -- オペレーターの識別子。

戻り値:

OperatorProperties オブジェクト。

例:

operator(L, "wm.context_set_int", "Material Slot 1",
        data_path="active_object.active_material_index", value=0)

# 以下と同じ:
# op = L.operator("wm.context_set_int", text="Material Slot 1")
# op.data_path = "active_object.active_material_index"
# op.value = 0

custom_icon(filename)¶

カスタムアイコンに関連付けられた整数値を取得します。

パラメータ:: filename (str) -- pie_menu_editor/icons/ にある拡張子なしのアイコンファイル名。
戻り値:: カスタムアイコンの整数値。

例:

L.label(text="My Custom Icon", icon_value=custom_icon("p1"))

panel(pt, frame=True, header=True, expand=None, area=None, root=False, poll=True, layout=None)¶

IDによってパネルを描画します。

パラメータ:

pt (Union[str, Type]) -- パネルクラスまたはパネルクラス名の文字列。文字列の場合は、 bpy.types から対応するクラスを検索します。
frame (bool) -- パネルをフレームで囲むかどうかを制御。True の場合、layout.box() を使用。False の場合、layout.column() を使用。
header (bool) -- パネルヘッダーの表示スタイルを制御。
expand (Optional[bool]) -- パネルの初期展開状態を制御。True : 展開された状態で開始、False : 折りたたまれた状態で開始、None : 前回の状態を保持。
area (Optional[str]) -- パネルを描画する際に想定する Area.type (例: 'VIEW_3D', 'PROPERTIES' )。ポップアップダイアログや別エディタ上から VIEW3D_PT_* のようなエディタ固有パネルを描画したい場合に指定します。パネル側の poll / draw が期待する space_data を解決できるようになります。 None または 'CURRENT' を指定すると現在のコンテキストを維持します。
root (bool) -- True にすると、追加の box() / column() で包まず、現在の pme.context.layout に直接パネルを描画します。 True の場合、frame と layout の指定は無視されます。レイアウトのネストを減らしたいときに使用します。
poll (bool) -- パネルの poll メソッドを実行するかどうかを制御。True の場合、パネルの表示条件をチェック。
layout (Optional[Any]) -- カスタムレイアウトを指定。

戻り値:

True

戻り値の型:

bool

例:

panel("MATERIAL_PT_context_material", True, True, True)

# パネルサイズを変更
L.scale_x = 0.8; panel("USERPREF_PT_interface", layout=L.box())

# ポップアップダイアログから 3D ビューのパネルを描画
panel("VIEW3D_PT_tools_meshedit_options", area='VIEW_3D')

# 外側の box / column を付けずに描画
panel("MATERIAL_PT_context_material", root=True)

自動実行スクリプト¶

PME では、Blender 起動時に自動的に実行される Python スクリプトを作成できます。 autorun は通常の Python module import ではなく、PME の実行 namespace 上で exec(...) されます。探索先は次の 2 系統です。

システム側: bundled assets/scripts/autorun
ユーザー側: 保存先とフォルダ構成の scripts/autorun

起動時は システム側が先、ユーザー側が後 の順に走査されます。

ユーザー側には、以下の形でファイルを置けます。

直接 .py ファイル
スクリプトを含むフォルダ
シンボリックリンク

注釈

autorun script では pme と bpy は既にグローバル変数として注入されています。そのため、PME の autorun / execute_script() 用スクリプトでは、通常 import pme や import bpy は不要です。

ただし、そのファイルを Blender Text Editor から単独実行したり、通常の Python module として再利用したりする用途まで想定する場合は、必要に応じて通常の import を追加してください。

警告

信頼できるソースのスクリプトのみ配置・実行してください
実行前に内容を確認し、必要に応じてバックアップやテスト環境で検証してください
ファイル操作や設定変更など、環境に影響する処理が含まれる場合があります

カスタムグローバル関数の追加¶

autorun の代表的な使い方は、Command タブや Custom タブから再利用する補助関数を起動時に登録しておくことです。手順は次の 2 つです。

保存先とフォルダ構成の scripts/autorun に .py を置く
pme.context.add_global() を使用して関数を登録

最小例:

def hello_world():
    message_box("Hello World")

pme.context.add_global("hello", hello_world)

登録された関数 hello() は以下で利用可能になります：

コマンドタブ
カスタムタブ
execute_script() で実行される外部ファイル

もう少し実用的な例:

def active_object_name(default="No Active Object"):
    obj = C.active_object
    return obj.name if obj else default

def show_active_object_name():
    overlay(active_object_name())
    return True

pme.context.add_global("active_object_name", active_object_name)
pme.context.add_global("ao_name", active_object_name)  # 短い別名として登録
pme.context.add_global("show_active_object_name", show_active_object_name)

登録後は PME 内の各スクリプトから次のように呼べます。

# Command tab
show_active_object_name()

# Custom tab
L.label(text=ao_name(), icon='OBJECT_DATA')

参考

保存先とフォルダ構成
起動オプション - import pme が必要な外部スクリプト向け

PMEコンポーネント¶

PMEは、よく使用される関数、変数、およびユーザー定義の追加項目へのアクセスを提供するグローバルコンテキストを維持します。このコンテキストは、2つの主要なインターフェースからアクセス可能です：

class pme.context¶

globals: dict¶

PMEのグローバルコンテキスト辞書へのアクセス。以下を含みます：

組み込みショートカット（C, D, O, L など）
登録されたカスタム関数と値
ユーザーデータストレージ（U）

from pie_menu_editor import pme

# 外部スクリプトからグローバルにアクセス
g = pme.context.globals
props = g.get('props')
user_data = g.get('U')

add_global(key, value)¶

グローバルコンテキストにカスタム関数または値を登録します。

パラメータ:

key (str) -- アイテムにアクセスするための名前
value -- 登録する関数または値

戻り値の型:

None

# 関数を登録
def my_tool():
    bpy.ops.mesh.select_all(action='TOGGLE')

pme.context.add_global("toggle_select", my_tool)

# 定数を登録
pme.context.add_global("MAX_ITEMS", 10)

# コマンドタブ経由でPMEメニューからアクセス:
# toggle_select()
# MAX_ITEMS

class pme.UserData¶

Blenderセッション中に持続するユーザー定義データのための柔軟なストレージ。

get(name, default=None)¶

保存された値を取得します。

パラメータ:

name (str) -- データキー
default -- キーが存在しない場合に返す値

戻り値:

保存された値またはデフォルト値

update(**kwargs)¶

複数の値を一度に更新します。

U = pme.context.globals['U']  # UserDataインスタンスを取得
U.update(tool_state="active", count=5)
print(U.tool_state)  # "active"