Bundled Utilities¶
PME loads these helpers from its bundled assets/scripts/autorun/ folder when
the add-on starts. Use their registered names directly in PME script fields;
you do not need to import or copy the bundled files. Do not edit those files to
customize them: updates can replace them. To register your own helpers, see
Auto-run Scripts.
These utilities complement the API Reference. They are not menu editing operations in the Public API. To manage script files, see Managing Scripts.
Examples below are one-line expressions or statements for PME fields. L is
available while drawing a Custom slot; E requires an input event. Pass C
explicitly to helpers that accept a context so they use the invoking editor.
Calls without a context use bpy.context, which can refer to another editor
while a popup or Preferences is active. The helpers do not create missing
editor context or make an unavailable Blender operator available.
Function index¶
Purpose |
Registered names |
|---|---|
Active tool |
|
Mesh selection and pointer |
|
Tool and DAT icons |
|
Paint settings |
|
Assignment and errors |
|
Event modifiers |
|
Existing name-based menu routing |
|
Active tool¶
get_active_tool(context=None)¶
Returns Blender’s active WorkSpaceTool-like object, or None when Blender’s
tool resolver finds no tool. It uses the editor and mode of the supplied context,
not a search for an arbitrary 3D View. Provide a context with a workspace and
space data. Blender decides which editors expose a tool; this is not limited
to mesh tools or the 3D View.
tool = get_active_tool(C); message_box(tool.idname if tool else "No active tool")
Use the returned object immediately; do not retain it across workspace, editor, or mode changes. This resolves the current tool; it does not activate a tool.
get_active_tool_id(context=None)¶
Returns the active tool’s idname as a string, such as "builtin.select_box".
Returns "" if the context has no workspace or space data, or no tool is found.
The ID is not the translated label or an icon name.
get_active_tool_id(C) == 'builtin.select_box'
Use that expression in a condition, or display the result in a Custom slot:
L.label(text=get_active_tool_id(C) or "No active tool")
Mesh selection and pointer¶
get_mesh_selection_kind(context, fallback=True)¶
Returns 1 for vertices, 2 for edges, 3 for faces, or 0 for no applicable
selection. Requires Mesh Edit Mode to inspect geometry; outside EDIT_MESH it
returns 0. It reads editable mesh data across objects with unique mesh data
and does not change selection.
get_mesh_selection_kind(C, fallback=False) == 3
With one selection mode enabled and
fallback=True, returns that mode even when nothing is selected.With
fallback=False, a single mode requires a selected, non-hidden element of that type; otherwise returns0.In mixed selection modes, selected vertices that do not belong to selected faces/edges in enabled modes take priority, then selected faces, then edges. Hidden elements are excluded.
If no eligible element is found and
fallback=True, uses the enabled modes in vertex → face → edge order. Withfallback=False, returns0instead.
This is an inference from selection flags, not a record of what was clicked
last. Blender can represent a selected face and its selected corner vertices
with the same flags. Use pick_mesh_view3d when the element under the pointer is the
information you need. This function does not inspect UV selection.
pick_mesh_view3d(context, mouse_xy, radius=12)¶
Reads the object or mesh component under a window-coordinate pointer position without selecting it. Requires a 3D View WINDOW region, in Object Mode or Mesh Edit Mode. Other contexts return a no-hit dictionary.
Example in an event-backed Command slot:
hit = pick_mesh_view3d(C, (E.mouse_x, E.mouse_y)); message_box(hit['kind'] or "No hit")
Pass window coordinates, not mouse_region_x / mouse_region_y. The helper
subtracts the target region’s origin. It uses the coordinates you supply at
call time; it does not capture the menu-opening position or track later motion.
If routing must use the opening position, retain that position in the caller.
Result key |
Value |
|---|---|
|
|
|
Hit Blender object, or |
|
Current BMesh iteration position for an Edit Mode component; otherwise |
|
Region-relative |
|
Present only for a vertex/edge hit: distance from the pointer in screen pixels |
In Object Mode this uses a scene ray cast and checks visibility of the returned object. It does not reproduce picking of non-surface objects such as lights or empties, and does not return a component index from the evaluated mesh.
In Mesh Edit Mode, vertices within radius win over edges within radius, then
the nearest surface face. Only enabled selection modes are considered. A negative
radius is treated as zero. Hidden elements are excluded; X-Ray allows vertex/edge
hits through editable faces.
Limits: this is an approximation, not Blender’s native selection-buffer picker. It uses the editable cage, not modifier output. Backfaces count as surfaces, and viewport clipping planes are not reproduced. In Edit Mode only non-hidden editable mesh faces occlude hits; objects outside Edit Mode do not. Indices are valid for the immediate observation only and must not be saved as stable element identifiers. Geometry is rebuilt for each call: avoid repeated calls in draw code or frequently evaluated conditions on dense meshes. No handlers, timers, selection writes, or persistent geometry caches are installed.
get_loc2d(context, coord)¶
Projects a world-space 3D coordinate into region-relative 2D coordinates.
Returns a mathutils.Vector with two components, or None if region/view data
is unavailable or Blender cannot project the point (for example, behind a
perspective view). context=None uses bpy.context.
point = get_loc2d(C, C.active_object.matrix_world.translation)
This example requires an active object and a 3D View drawing region. Convert a
mesh-local coordinate with obj.matrix_world @ coord first. A returned point
can be outside the viewport; it is not a visibility or occlusion test. The
helper uses space_data.region_3d, so do not assume it selects the correct
subview in every Quad View region. Unlike pick_mesh_view3d, its output is already
region-relative.
Icons¶
get_tool_icon_value(name)¶
Returns an integer icon ID for a Blender tool icon handle, not a tool ID or
an RNA icon enum. A typical handle is "ops.generic.select_box".
Returns 0 for an empty name. It first uses Blender’s tool icon loader; if that
raises, it falls back to get_dat_icon(name). Unavailable icons may resolve to
Blender’s fallback icon or 0, so a nonzero ID is not proof of an exact match.
L.label(text="Box Select", icon_value=get_tool_icon_value('ops.generic.select_box'))
Use in a Custom slot with a drawing layout. Prefer PME’s Auto Icon option for a normal tool-switching slot; this helper is for custom drawing.
get_dat_icon(icon_name)¶
Returns an integer icon ID loaded from a .dat triangle icon. Pass its name
without .dat, not a filesystem path. Search order is Blender’s
DATAFILES/icons, PME user icon directories, then bundled icons.
L.label(text="Box Select", icon_value=get_dat_icon('ops.generic.select_box'))
Returns 0 for an empty name, a missing/ambiguous/unloadable icon, or when an
old cached icon cannot be released before replacement. Missing/corrupt files
produce a warning; ambiguous user names are reported through resource discovery.
Loaded IDs are cached. Do not save these runtime IDs in a preset or reuse them
across restarts. This is not a PNG loader. Icon availability depends on the
installed Blender and configured resources, not the active modeling mode.
release_dat_icons()¶
Releases the DAT IDs owned by this helper and clears its Blender path lookup
cache. Returns None. IDs that cannot be released remain tracked for a later
retry. This does not release all Blender icons or icons owned by other loaders.
release_dat_icons()
This is a reload/development helper, not something to run on every draw. Stop using cached IDs before releasing them; request fresh IDs for subsequent UI.
Paint settings¶
ups()¶
Returns the raw Unified Paint Settings object for the current bpy.context.
On hosts with scene-wide unified settings it returns that owner. On hosts with
mode-specific settings it resolves the current paint mode independently of the
active tool. It raises RuntimeError if that context has no unified settings.
Example Custom slot in an applicable paint context:
L.prop(ups(), 'size', text='Unified Size')
It does not choose a brush or switch modes. Property availability follows the
host’s returned RNA object. In Blender 5.3, active use_unified_* flags live on
the Brush; do not assume those flags exist on the object returned by ups().
brush(use_ups=False)¶
Returns the active Brush from Blender’s current paint settings, or None when
no brush is available. With use_ups=True, returns ups() instead (including
its errors); that result is unified settings, not a Brush. Uses bpy.context
and Blender’s paint-settings resolver; mode and active tool can affect brush
availability.
b = brush(); L.prop(b, 'strength', text='Strength') if b else L.label(text='No active brush')
This example belongs in a Custom slot in a paint/sculpt context. Do not
dereference brush().size without ensuring a brush exists. The historical
expression brush(ups().use_unified_size).size assumes unified flags live on
Unified Paint Settings and is not suitable for hosts that put them on Brush.
Assignment, events, and errors¶
setattr(object, name, value)¶
Sets an attribute and returns True after a successful assignment. Unlike
Python’s built-in setattr, PME’s registered helper returns a boolean.
Assignment errors propagate. The target must exist and its property must be
writable in the current context.
setattr(C.tool_settings, 'use_proportional_edit', True)
Use in a Command, not a drawing callback or a condition that should only read
state. For a visible toggle, prefer a Custom slot widget such as
L.prop(C.tool_settings, 'use_proportional_edit', toggle=True). This helper
does not create its own Undo step.
try_setattr(object, name, value)¶
Attempts the same assignment, but catches assignment exceptions and always
returns True, including when nothing was changed. This is existing behavior;
do not use the result to verify success.
try_setattr(C.active_object, 'show_name', True)
No particular editor is required, but the target and property still determine
whether the assignment can work. Use setattr when a failure should be visible,
and read back the property when verifying a change. This helper neither reports
the failure nor creates its own Undo step.
event_mods(event)¶
Returns a string joining active modifiers in Ctrl, Shift, Alt, OSKey order,
for example "Ctrl+Shift". Returns the literal string "None" if none are set;
missing modifier attributes count as false. Requires an event-like value, not
a particular editor or mode. It does not report non-modifier keys.
message_box(event_mods(E))
Use from an event-backed Command. This reads the supplied event, not the keyboard’s current state at some later time.
raise_error(message)¶
Attempts to show PME’s error message box, then raises Exception(message).
It has no normal return value and aborts the current script. Requires a UI
context where the message-box operator can run; if that operator fails, its
error propagates instead.
raise_error('Select a mesh before running this command')
Use for an actual error in a Command, not an ordinary false condition or repeated draw-time notification.