コードの入力と実行¶
PME のコード欄へ Python を書くときの前提と、入力・実行の仕様をまとめています。対象は PME 2.1 です。
重要
コード欄の編集方法を選ぶ
Blender 5.2 以上では Multi-line Command Editor を有効にすると、Command / Custom と Context Router の Target を複数行で編集できます。Shift+Enter で改行し、Enter で欄の編集を終えてからスロットを保存します。PME の popup editor は1行欄のままなので、複数行の編集には Preferences を使います。
設定がオフ、または以前の Blender では従来の1行欄を使います。メニューの Poll、Property、description 式の欄は変わりません。
長い処理や再利用する処理には外部の Python ファイルも使えます。
execute_script("scripts/my_action.py")で呼び出します。
Command / Custom の保存と Blender 標準 UI 経由の実行には、PME 独自の文字数上限はありません。Context Router の Target も同じです。編集設定が変えるのは欄の表示であり、保存する本文や実行経路は変わりません。
GPU メニュー(Floating Panel / Vector Menu)に描く通常の Command スロットと Context Router の Command Target は、共通の operator 引数運搬により、文字列1つにつき4,096文字までです。本文や文字列引数がこの運搬上限を超えると実行されず、operator_property_string_too_long 診断が出ます。通常の Command を Blender operator へ直接変換できる場合は引数を個別に運ぶため、各文字列引数が上限内なら本文全体が4,096文字を超えても通ることがあります。Blender 標準 UI のメニューを使うか、この経路には外部スクリプトの短い呼び出しを置いてください。
関数・変数と引数の仕様は API リファレンス、メニューの利用条件は Poll Method を参照してください。
コード欄には貼り付け用の1行を用意する¶
1行欄で Command / Custom を編集する場合やメニューの Poll では、短い処理を1行にして入力します。複数行の Command / Custom には、上記の編集設定を使います。
書きたい処理 |
1行の形 |
注意点 |
|---|---|---|
単純な文を順番に実行 |
|
|
条件によって値を選ぶ |
|
各名前を実際の式に置き換える |
条件を満たすときだけ実行 |
|
左側が真のときだけ右側を評価する |
Poll の結果を返す |
|
メニューの Poll 用。Command では使わない |
if / for / def のブロックを、改行から ; への置換だけで変換することはできません。Command / Custom のブロックには複数行エディターを使い、再利用する処理は 外部ファイルへ分けられます。
複数行の操作履歴を取り込む場合
操作記録の取り込みには、オペレーター呼び出しや代入を抽出して1行にまとめる経路があります。任意の Python スクリプトをそのまま保存する機能ではありません。取り込み後の内容も確認してください。
設定先と実行タイミング¶
設定先 |
評価されるとき |
書く内容 |
|---|---|---|
Command |
項目を実行したとき |
オペレーターの呼び出し、値の変更 |
Custom |
UI を描画するとき。再描画で繰り返す |
|
メニューの Poll |
メニューが利用できるかを調べるとき |
条件を読み、 |
Property の Getter / Setter / Update |
値の取得・書き込み・更新時 |
役割ごとの処理。コールバックの仕様を参照 |
|
呼び出し元が評価されたとき |
呼び出し元の役割に応じた処理。Custom から呼べば描画時に実行される |
たとえば Custom に bpy.ops.mesh.primitive_cube_add() と書くと、描画時に追加処理を実行してしまいます。ボタンを置くなら L.operator("mesh.primitive_cube_add") を使います。
PME が用意する名前と、自分で用意する名前¶
PME のコード欄には便利な名前が用意されています。ただし、すべての設定先で
同じ値が揃うわけではありません。次の表は、Command / Custom と、そこから
execute_script() で呼ぶファイルを読むための入口です。
名前 |
用途 |
前提・注意点 |
|---|---|---|
|
その実行・描画で PME が提供するコンテキストを読む |
|
|
Blender の API を使う |
描画経路によって |
|
Blender のデータへのアクセス |
|
|
Blender のオペレーターを呼ぶ |
|
|
Blender の型へのアクセス |
|
|
現在のレイアウトに UI 部品を描く |
Custom など、レイアウトを受け取る描画時に使う。Command 用の操作対象ではない |
|
その処理に渡された入力イベントを調べる |
イベントのない評価では名前自体が提供されない場合がある |
|
PME のセッション内で一時的な値を共有する |
保存先ではない。PME の再登録や Blender の再起動をまたぐ値に使わない |
pm、pmi、menu などの名前は、設定先ごとの意味を確認してください。
たとえば Property のコールバックでの menu は Property ID です。
別のスロットの例をそのまま流用せず、Property のコールバック
の説明を使います。
外部ファイルで独自の関数、mathutils.Vector、他のモジュールを使う場合は、
そのファイル自身で定義・インポートします。PME が現在提供する名前と、
以前 Python Console に入力した変数を混同しないでください。
外部ファイルを実行する¶
長い処理は通常の Python ファイルへ書き、PME から execute_script() で呼びます。
ファイルブラウザーから選ぶ¶
スロットを Edit Slot で開き、タブ右端のメニューから Call External Script を選びます。
Quick Locations の登録名を押すと、そのリソースフォルダーの scripts/ へ移動します。
.py ファイルを選び、Use Script As で用途を指定して Open Script を押します。
My Studio の scripts/ を開いた例。Script Examples からは PME 同梱のスクリプト例を開けます。¶
Command Tab — メニューの項目を実行したときにスクリプトを呼びます。
Custom Tab — メニューの描画時にスクリプトを呼びます。
Lで UI を配置するスクリプトに使います。
選んだファイルを呼ぶコードがスロットへ入り、OK で確定します。
登録先の中にあるファイルは、scripts/modeling/bevel_selected.py や tools/bevel_selected.py のような、登録フォルダーからの相対参照で保存します。
登録先の外にあるファイルは絶対パスを保持します。場所の登録と同名ファイルの扱いは、保存先とフォルダ構成を参照してください。
バージョン 2.2.0 で変更: Quick Locations から各登録先の scripts/ を開けるようになり、そこから選んだファイルは登録フォルダーからの相対パスで保存されます。
引数を渡して実行する¶
次は、選択中のオブジェクト数を表示する例です。ファイルの呼び出しはコード欄へ直接入力することもできます。
1. ファイルを置く — 保存先とフォルダ構成にあるユーザースクリプトのフォルダへ、selection_report.py を保存します。
ファイル本文(複数行):
return_value = False
def build_report(context, prefix):
objects = getattr(context, "selected_objects", ()) or ()
return f"{prefix}: {len(objects)}"
report = build_report(C, str(kwargs.get("prefix", "Selection")))
message_box(report)
return_value = report
2. 呼び出しを設定する — パイメニューのスロット → Command に、次の1行を貼り付けます。
execute_script("scripts/selection_report.py", prefix="Selected objects")
3. 確認する — 3D Viewport の Object Mode でオブジェクトを選び、この項目を実行します。選択数のメッセージが出ます。選択を外して実行すると 0 と表示されます。
ファイルの場所と引数¶
項目 |
意味 |
|---|---|
|
登録したリソースフォルダーが基準。全登録先を検索し、一意に見つかったファイルを実行。重複した場合は実行せず、候補がなければアドオン本体の中を検索 |
|
どの相対パスも同じ規則。 |
絶対パス |
そのファイルを直接実行 |
|
呼び出しで渡した引数の辞書。 |
|
実際に読み込んだファイルのパス |
|
|
戻り値を使う場合は呼び出し側で変数へ代入します。戻り値は自動表示されないため、上の例では message_box() を呼んでいます。PME 2.1 ではファイル先頭のインポートや定義を、同じ実行で定義した関数からも参照できます。
外部ファイルに移しても、呼び出し元のコンテキストや評価タイミングは変わりません。設定をほかの環境へ渡す場合は、ファイルも一緒に用意します。
戻り値を成功判定に使うとき
return_value の既定値は True です。例外を捕捉した経路でもその値が返る場合があり、戻り値だけを汎用的な成功判定にはできません。例では冒頭に False、処理の最後に結果を設定しています。エラー出力と実際の結果も確認してください。この代入は、途中まで行ったデータ変更を取り消す仕組みではありません。
オペレーターの実行場所とタイミング¶
bpy.ops の呼び出しには、引数だけでなく実行場所の条件があります。
同じ文字列でも、3D Viewport からの実行と Preferences 上のボタンでは結果が異なり得ます。
必要なエディターとリージョンにいるか。
必要なモードか。アクティブな対象と選択対象は揃っているか。
引数名と値が、使っている Blender のバージョンに存在するか。
操作をその場で確定するのか、マウスで調整する操作を始めるのか。
EXEC_DEFAULT は指定した値で実行する経路、INVOKE_DEFAULT はオペレーターの
開始処理を呼ぶ経路です。後者はダイアログやマウス操作に進む場合がありますが、
すべてのオペレーターが両方の使い方を提供するわけではありません。
詳しくは Blender の Operator APIを参照してください。
オペレーターが RUNNING_MODAL を返すと、ユーザーによる操作がまだ続いています。
その呼び出しの後ろに ; で書いた Python が、操作の確定まで待つとは考えないでください。
ユーザーの調整を挟む手順には Macro Operatorも検討します。
コンテキストエラーのたびに、見つかった最初のエリアへ切り替えるコードを足すと、 意図しないビューで動く原因になります。まず本来のエディターから呼び出し、 ホットキーの範囲を確認します。別エリアを対象にする必要がある場合だけ、 対象の選び方と、見つからないときの動作を決めます。
別のエリアを対象にする¶
たとえば、UV Editor に置いたボタンから 3D Viewport のオーバーレイを切り替えたいとします。
C.space_data はボタンのあるエリア、つまり UV Editor の設定です。そのまま書くと
UV Editor 側が切り替わります。
override_context() で対象のエリアを指定してから、コードを書き、最後に exit() を呼びます。
oc = override_context('VIEW_3D'); C.space_data.overlay.show_overlays ^= True; oc.exit()
override_context()からoc.exit()までの間、Cは指定したエリアを指します。bpy.opsの呼び出しも、そのエリアで実行されます。この1行の例では
;でつなぎます。Blender 標準のbpy.context.temp_override(...)をwithブロックで使う場合は、複数行の Command 欄か外部スクリプトを使います。exit()は必ず呼びます。呼び忘れた override は元に戻りません。第1引数は Space Type Items の文字列(
'VIEW_3D'など)か、bpy.types.Areaです。文字列のときは、同じ種類の エリアが複数あれば最初に見つかったエリアが対象です。特定のエリアを指したい場合は、bpy.types.Areaをそのまま渡します。指定したエリアが見つからない場合は、現在のエリアのままです。
引数の詳細は API リファレンス の override_context() を参照してください。
Python Console で同じことをする場合は、
Context Browser の Area Picker が
with C.temp_override(...): の形で入力を包みます。PME のコード欄では、この節の
override_context() を使います。
エラーを切り分ける¶
Blender の Python Console に入力したコードの結果と、PME の print() の出力先は
同じとは限りません。print() や Python の例外は、Blender の標準出力・エラー出力を
確認します。macOS では Blender を起動したターミナルなどが出力先になります。
症状 |
最初に確認すること |
|---|---|
|
必要な名前を、そのファイル内でインポート・定義しているか。 |
|
依存モジュールが Blender の Python に存在するか。システムの Python に入れただけではないか |
|
対象なしの状態、オブジェクト型、プロパティ名、Blender のバージョン |
|
Blender オペレーターが要求するエディター、リージョン、モード、選択状態 |
コード末尾の構文エラー |
貼り付けたコードが元の内容と一致しているか |
Text Editor では動くが PME では動かない |
不足しているインポート、別の実行で残った変数、実行場所の違い |
処理は進むが期待した結果にならない |
|
対象の状態だけを出力する短い Command を、本来使うエディターから呼ぶと、 エラーの起きる状態を絞れます。
print("PME context:", getattr(C.area, "type", None), C.mode, C.active_object)
まず一つの処理で結果を確かめてから、分岐や連続操作を追加します。
データ変更を伴う場合は、対象がある場合・ない場合の両方と、Undo / Redo を確認します。
; で連続させたことや EXEC_DEFAULT を使ったことだけでは、
一つの Undo にまとまるとは限りません。履歴を見ずに bpy.ops.ed.undo_push() を
機械的に追加しないでください。
関連するリファレンス¶
コード例:設定先と貼り付けるコードから選ぶ。
API リファレンス:関数・変数の仕様を調べる。
Public API:外部アドオンなどから PME を利用する。
一時的な値の共有:
Uと永続保存の使い分け。