--- vocab: developer-facing --- (bundled-utilities)= # 同梱ユーティリティー PMEはアドオン起動時に、同梱の `assets/scripts/autorun/` から補助関数を読み込みます。 PMEのコード欄では、登録された関数名をそのまま使えます。ファイルのコピーやimportは不要です。 同梱ファイルはアップデートで置き換わるため、カスタマイズのために直接編集しないでください。 自分の関数を登録する方法は、{ref}`自動実行スクリプト `を参照してください。 このページは[APIリファレンス](scripting.rst)を補足するものです。 ここで扱う関数は、[Public API](public_api.md)のメニュー作成・編集操作とは別です。 ファイルの閲覧・編集・保存については、[スクリプトの管理](script_management.rst)を参照してください。 使用例はPMEのコード欄に入力できる1行の式または文です。 `L` はCustomスロットの描画時に使えます。`E` を使う例には入力イベントが必要です。 コンテキストを受け取る関数には、呼び出し元のエディターを使うために `C` を明示的に渡してください。 省略時は `bpy.context` を使いますが、ポップアップやPreferencesを開いている間は、 別のエディターを指すことがあります。これらの関数は、不足するエディターのコンテキストを 作成したり、実行できないBlenderオペレーターを実行可能にしたりするものではありません。 ## 関数一覧 | 用途 | 登録名 | | --- | --- | | アクティブツール | `get_active_tool`, `get_active_tool_id` | | メッシュの選択状態・ポインター | `get_mesh_selection_kind`, `pick_mesh_view3d`, `get_loc2d` | | ツール・DATアイコン | `get_tool_icon_value`, `get_dat_icon`, `release_dat_icons` | | ペイント設定 | `ups`, `brush` | | 値の代入・エラー | `setattr`, `try_setattr`, `raise_error` | | イベントの修飾キー | `event_mods` | | 既存の名前ベースのメニュー分岐 | `CSM`(末尾の折りたたみ内に掲載) | ## アクティブツール ### `get_active_tool(context=None)` Blenderのアクティブな `WorkSpaceTool` 相当のオブジェクトを返します。 Blenderのツール検索で見つからない場合は `None` を返します。 渡されたコンテキストのエディターとモードを使い、任意の3D Viewを探すことはしません。 ワークスペースとスペースデータを持つコンテキストを渡してください。 ツールを取得できるエディターはBlender側の仕様に従い、メッシュや3D Viewに限定されません。 ```python tool = get_active_tool(C); message_box(tool.idname if tool else "No active tool") ``` 戻り値はその場で使い、ワークスペース・エディター・モードの変更をまたいで保持しないでください。 現在のツールを取得する関数であり、ツールの切り替えは行いません。 ### `get_active_tool_id(context=None)` アクティブツールの `idname` を文字列で返します。例は `"builtin.select_box"` です。 コンテキストにワークスペースやスペースデータがない場合、またはツールが見つからない場合は 空文字列 `""` を返します。IDは翻訳された表示名やアイコン名とは異なります。 ```python get_active_tool_id(C) == 'builtin.select_box' ``` この式は条件判定に使えます。Customスロットで取得結果を表示する例は次のとおりです。 ```python L.label(text=get_active_tool_id(C) or "No active tool") ``` ## メッシュの選択状態・ポインター ### `get_mesh_selection_kind(context, fallback=True)` 頂点なら `1`、辺なら `2`、面なら `3`、該当する選択がなければ `0` を返します。 ジオメトリの調査にはメッシュの編集モードが必要です。`EDIT_MESH` 以外では `0` を返します。 編集対象のオブジェクトを調べ、同じメッシュデータは重複して調べません。選択状態は変更しません。 ```python get_mesh_selection_kind(C, fallback=False) == 3 ``` - 選択モードが1種類で `fallback=True` の場合、何も選択されていなくても、そのモードを返します。 - 選択モードが1種類で `fallback=False` の場合、その種類の非表示でない要素が選択されていれば モードを返し、なければ `0` を返します。 - 複数の選択モードが有効な場合、有効なモードの選択済みの面・辺に属さない選択済み頂点を 優先し、その次に選択済みの面、辺を調べます。非表示の要素は除外します。 - 該当要素がなく `fallback=True` の場合、有効な選択モードから頂点→面→辺の順で選びます。 `fallback=False` なら `0` を返します。 これは選択フラグからの推定で、最後にクリックしたものの記録ではありません。 Blenderでは、面を選択した状態と、その面を構成する頂点を選択した状態が同じフラグで表される 場合があります。ポインター下の要素を知りたい場合は `pick_mesh_view3d` を使ってください。 この関数はUVの選択状態を調べません。 ### `pick_mesh_view3d(context, mouse_xy, radius=12)` ウィンドウ座標で指定したポインター位置にあるオブジェクトやメッシュ要素を、選択せずに取得します。 3D Viewの **WINDOW領域**と、オブジェクトモードまたはメッシュの編集モードが必要です。 それ以外のコンテキストでは、ヒットなしの辞書を返します。 入力イベントを持つCommandスロットでの使用例です。 ```python hit = pick_mesh_view3d(C, (E.mouse_x, E.mouse_y)); message_box(hit['kind'] or "No hit") ``` `mouse_region_x` / `mouse_region_y` ではなく、**ウィンドウ座標**を渡してください。 関数内で対象領域の原点を差し引きます。使うのは呼び出し時に渡した座標です。 メニューを開いた位置の記録や、その後のマウス移動の追跡は行いません。 メニュー起動時の位置で分岐したい場合は、呼び出し側でその位置を保持してください。 | 戻り値のキー | 値 | | --- | --- | | `kind` | `'OBJECT'`, `'VERT'`, `'EDGE'`, `'FACE'`、または `None` | | `object` | ヒットしたBlenderオブジェクト、または `None` | | `index` | 編集モードの要素の、現在のBMesh走査順での位置。それ以外は `None` | | `mouse_xy` | 変換後の領域相対座標 `(x, y)`。エリア・領域が不適切なら `None` | | `distance_px` | 頂点・辺にヒットした場合のみ存在。ポインターからの画面上の距離(ピクセル) | オブジェクトモードでは、シーンのレイキャストを使い、返されたオブジェクトの可視性を確認します。 ライトやエンプティなど、表面を持たないオブジェクトの選択判定は再現しません。 評価済みメッシュの要素インデックスも返しません。 メッシュの編集モードでは、`radius` 内の頂点、`radius` 内の辺、最も手前の面の順で優先します。 有効な選択モードのみを対象とし、負の半径はゼロとして扱います。 非表示要素は除外します。X-Rayが有効な場合、編集対象の面の奥にある頂点・辺も判定対象になります。 **制約:** Blender標準の選択バッファを使う判定ではなく、近似処理です。 モディファイア適用後の形状ではなく、編集中の元の形状を使います。裏面も表面として扱い、 ビューポートのクリッピング平面は再現しません。編集モードで遮蔽物になるのは、編集対象の 非表示でないメッシュ面だけです。編集モード外のオブジェクトは遮蔽物になりません。 インデックスはその場の観測にのみ有効で、要素の恒久的な識別子として保存しないでください。 呼び出しごとにジオメトリを組み立てるため、高密度メッシュの描画処理や頻繁に評価される条件での 繰り返し呼び出しは避けてください。ハンドラー、タイマー、選択の書き換え、持続するジオメトリキャッシュは作成しません。 ### `get_loc2d(context, coord)` **ワールド座標**の3D位置を、領域相対の2D座標に投影します。 戻り値は2成分の `mathutils.Vector` です。領域・ビューの情報がない場合や、透視投影の背後に ある点などBlenderが投影できない場合は `None` を返します。`context=None` は `bpy.context` を使います。 ```python point = get_loc2d(C, C.active_object.matrix_world.translation) ``` この例には、アクティブオブジェクトと3D Viewの描画領域が必要です。 メッシュのローカル座標は、先に `obj.matrix_world @ coord` で変換してください。 返される座標はビューポートの外にある場合もあります。可視性や遮蔽の判定には使えません。 この関数は `space_data.region_3d` を使うため、四分割表示の各領域に対応するビューを 常に正しく選べるとは限りません。`pick_mesh_view3d` の入力とは異なり、出力はすでに領域相対座標です。 ## アイコン ### `get_tool_icon_value(name)` Blenderの**ツールアイコンハンドル**から、整数のアイコンIDを返します。 引数はツールIDやRNAアイコン列挙値ではありません。例は `"ops.generic.select_box"` です。 空の名前なら `0` を返します。まずBlenderのツールアイコン読み込みを使い、例外が発生すると `get_dat_icon(name)` に切り替えます。利用できないアイコンは代替アイコンや `0` になる場合があり、 ゼロ以外のIDが返っても、指定したアイコンそのものが見つかった証明にはなりません。 ```python L.label(text="Box Select", icon_value=get_tool_icon_value('ops.generic.select_box')) ``` 描画レイアウトを持つCustomスロットで使います。通常のツール切り替えスロットでは PMEのAuto Iconを優先してください。この関数は独自に描画する場合のためのものです。 ### `get_dat_icon(icon_name)` `.dat` 形式の三角形アイコンを読み込み、整数のアイコンIDを返します。 ファイルパスではなく、拡張子 `.dat` を除いた名前を渡してください。 Blenderの `DATAFILES/icons`、PMEのユーザーアイコンディレクトリー、同梱アイコンの順に探します。 ```python L.label(text="Box Select", icon_value=get_dat_icon('ops.generic.select_box')) ``` 名前が空、アイコンが見つからない・一意に決まらない・読み込めない、または置き換え前に 古いキャッシュのアイコンを解放できない場合は `0` を返します。ファイルの欠落・破損は警告され、 ユーザーアイコンの名前の重複はリソース探索側で報告されます。 読み込んだIDはキャッシュされます。実行時のIDをプリセットに保存したり、再起動をまたいで 再利用したりしないでください。PNGの読み込みには使えません。アイコンの利用可否は インストールされたBlenderとリソース設定に依存し、モデリングのモードには依存しません。 ### `release_dat_icons()` このヘルパーが所有するDATアイコンIDを解放し、Blenderのアイコンパスの検索キャッシュを消去します。 戻り値は `None` です。解放できなかったIDは、後で再試行できるように記録を保持します。 Blender全体のアイコンや、他の読み込み処理が所有するアイコンを解放するものではありません。 ```python release_dat_icons() ``` 再読み込み・開発用の関数です。描画のたびに実行しないでください。 解放前にキャッシュしたIDの利用を止め、それ以降のUIではIDを取得し直してください。 ## ペイント設定 ### `ups()` 現在の `bpy.context` に対応するUnified Paint Settingsオブジェクトをそのまま返します。 シーン共通の統合設定を持つBlenderではその設定を返します。モード別の設定を持つBlenderでは、 アクティブツールに依存せず現在のペイントモードから設定を取得します。 そのコンテキストに統合設定がない場合は `RuntimeError` を送出します。 該当するペイントコンテキストのCustomスロットでの例です。 ```python L.prop(ups(), 'size', text='Unified Size') ``` ブラシの選択やモードの切り替えは行いません。利用できるプロパティは、Blenderが返すRNAオブジェクトに従います。 Blender 5.3では、有効な `use_unified_*` フラグはBrush側にあります。 `ups()` の戻り値にこれらのフラグがあると仮定しないでください。 ### `brush(use_ups=False)` Blenderの現在のペイント設定からアクティブなBrushを返します。利用できるブラシがなければ `None` です。 `use_ups=True` の場合は、代わりに `ups()` の結果を返し、そのエラーも引き継ぎます。 この場合の戻り値はBrushではなく統合設定です。`bpy.context` とBlenderのペイント設定取得処理を使うため、 モードやアクティブツールによってブラシを取得できるかが変わります。 ```python b = brush(); L.prop(b, 'strength', text='Strength') if b else L.label(text='No active brush') ``` この例はペイント・スカルプトのコンテキストのCustomスロットで使います。 ブラシが存在することを確かめずに `brush().size` を参照しないでください。 従来の式 `brush(ups().use_unified_size).size` は、統合フラグがUnified Paint Settingsにあることを 前提としているため、Brush側にフラグを持つBlenderには適しません。 ## 値の代入・イベント・エラー ### `setattr(object, name, value)` 属性に値を代入し、成功すると `True` を返します。Python組み込みの `setattr` と異なり、 PMEに登録されたこの関数は真偽値を返します。代入時のエラーはそのまま送出されます。 対象が存在し、そのプロパティが現在のコンテキストで書き込み可能である必要があります。 ```python setattr(C.tool_settings, 'use_proportional_edit', True) ``` Commandで使ってください。描画処理や、状態を読むだけの条件判定には使わないでください。 状態を表示しながら切り替える場合は、Customスロットの `L.prop(C.tool_settings, 'use_proportional_edit', toggle=True)` のようなウィジェットを優先します。 この関数自体はUndoステップを追加しません。 ### `try_setattr(object, name, value)` 同じ代入を試みますが、代入時の例外を捕捉し、**何も変更できなかった場合も含めて常に `True` を返します**。 これは既存の挙動です。戻り値を成功確認に使わないでください。 ```python try_setattr(C.active_object, 'show_name', True) ``` 特定のエディターは必要ありませんが、代入できるかは対象とプロパティに依存します。 失敗を表に出したい場合は `setattr` を使い、変更を検証する場合はプロパティを読み戻してください。 この関数は失敗を報告せず、Undoステップも追加しません。 ### `event_mods(event)` 押されている修飾キーを **Ctrl、Shift、Alt、OSKey** の順でつないだ文字列を返します。 例は `"Ctrl+Shift"` です。何も押されていなければ文字列 `"None"` を返します。 修飾キーの属性が存在しない場合は偽として扱います。特定のエディターやモードは不要ですが、 イベント相当の値が必要です。修飾キー以外のキーは報告しません。 ```python message_box(event_mods(E)) ``` 入力イベントを持つCommandで使います。渡されたイベントを読むもので、後の時点での キーボードの押下状態を調べるものではありません。 ### `raise_error(message)` PMEのエラーメッセージボックスの表示を試みた後、`Exception(message)` を送出します。 正常な戻り値はなく、現在のスクリプトを中断します。メッセージボックスのオペレーターが 実行できるUIコンテキストが必要です。そのオペレーターが失敗すると、代わりにそのエラーが送出されます。 ```python raise_error('Select a mesh before running this command') ``` Commandで実際のエラーを報告するために使います。通常の条件不成立や、描画時に繰り返す通知には使わないでください。 ## ContextSensitiveMenu(`CSM`) 新しく作るメニューには、[Context Router](../editors/context_router_editor.md)を使ってください。 エディターごとの違いは可能な限りKeymapで分け、同じエディター内の条件の違いをContext Routerで分けると、 メニュー名の規則に依存せず分岐を明示できます。`CSM` は既存のカスタマイズ向けに引き続き利用できます。 ```{dropdown} ContextSensitiveMenuの互換用リファレンスと使用例 `CSM.from_context(context, prefix="", suffix="")` は、解決した `menu_name`(文字列または `None`)を持つ `ContextSensitiveMenu` インスタンスを返します。呼び出し元のコンテキストには `C` を渡してください。 判定に使うのは**アクティブオブジェクト**です。ポインター下の対象や、選択オブジェクト一覧が空かどうかだけで判定するものではありません。 `My Vertex Menu` や `My Mesh Menu` などのメニューを作成済みの場合のCommandの例です。 CSM.from_context(C, prefix='My ', suffix=' Menu').open_menu() `My Vertex Panel` などの描画可能なメニューを作成済みの場合のCustomの例です。 CSM.from_context(C, prefix='My ', suffix=' Panel').draw_menu(layout=L) 名前は、アンダースコアを空白に変え、各単語の先頭を大文字にしてからprefixとsuffixを付けて作ります。 存在し、かつ有効になっているメニューだけが候補になります。 - アクティブオブジェクトなし:`None Object` という名前を使います。この分岐では `Any Object` へフォールバックしません。 - メッシュの編集モード:有効な選択モードを **Vertex → Edge → Face** の順で調べ、 その後に `Edit Mesh`、`Mesh`、`Any Object` を調べます。選択要素ではなく有効な選択モードの判定であり、 `get_mesh_selection_kind()` は使いません。 - メッシュでObject以外の別モード:現在のモード、`Mesh`、`Any Object` の順です。 - メッシュのオブジェクトモード:`Mesh`、`Any Object` の順です。 - エンプティ:該当する場合に `Image`、または `Instance`、または力場の種類と `Field` を調べ、 その後に `Empty`、`Any Object` を調べます。 - その他のオブジェクト:Object以外なら現在のモード、続いてオブジェクトの種類、`Any Object` の順です。 `open_menu(**kwargs)` と `draw_menu(**kwargs)` の戻り値は `None` です。 キーワード引数はPMEの対応するメニュー関数に渡されます。描画には有効なレイアウト、 呼び出しには実行可能なコンテキストが必要です。メニューがない・無効な場合は警告を記録して何もしません。 呼び出し・描画の失敗はエラーとして報告されます。有効なメニューが存在しても、Pollにより利用できない場合があります。 確認用の `CSM.has_menu(name)` と `instance.check_menu_exists()` は真偽値を返します。 後者はメニューがない場合に警告も出します。`instance.format_name(name)` は整形後の名前を返します。 `instance.check_and_set_menu(name)` は有効なメニューならその名前、なければ `None` を返します (`menu_name` への代入は行いません)。`instance.gen_menu_name()` は名前を再判定し、`None` を返します。 編集をまたいで取得済みのアクティブオブジェクトを保持せず、コンテキストが変わったらインスタンスを作り直してください。 ```