ddg.blender.context module

ddg.blender.context.mode(bobj: Any, *, mode: Literal['OBJECT', 'EDIT', 'POSE', 'SCULPT', 'VERTEX_PAINT', 'WEIGHT_PAINT', 'TEXTURE_PAINT', 'PARTICLE_EDIT', 'EDIT_GPENCIL', 'SCULPT_GPENCIL', 'PAINT_GPENCIL', 'WEIGHT_GPENCIL', 'VERTEX_GPENCIL'] = 'OBJECT', mesh_select_mode: set[Literal['VERT', 'EDGE', 'FACE']] = {}, exit_mode: Optional[Literal['OBJECT', 'EDIT', 'POSE', 'SCULPT', 'VERTEX_PAINT', 'WEIGHT_PAINT', 'TEXTURE_PAINT', 'PARTICLE_EDIT', 'EDIT_GPENCIL', 'SCULPT_GPENCIL', 'PAINT_GPENCIL', 'WEIGHT_GPENCIL', 'VERTEX_GPENCIL']] = None, exit_mesh_select_mode: Optional[set[Literal['VERT', 'EDGE', 'FACE']]] = None) → Iterator[None][source]

Context manager to set the active object and its modes.

Sets mode mode with mesh select modes mesh_select_mode for an object bobj and upon exiting the context sets mode exit_mode and mesh select modes exit_mesh_select_mode.

This is useful for example to perform changes in EDIT mode that require a switch to a different mode to be written to the object’s data.

Parameters:

bobjbpy.types.Object: The object that is set to be the active object.
modestr, default=”OBJECT”: The mode of bobj within the context. Must be one of “OBJECT”, “EDIT”, “POSE”, “SCULPT”, “VERTEX_PAINT”, “WEIGHT_PAINT”, “TEXTURE_PAINT”, “PARTICLE_EDIT”, “EDIT_GPENCIL”, “SCULPT_GPENCIL”, “PAINT_GPENCIL”, “WEIGHT_GPENCIL”, “VERTEX_GPENCIL”.
mesh_select_modeset of { “VERT”, “EDGE”, “FACE” }, default=set(): The mesh select modes of bobj within the context. This argument is ignored unless mode == EDIT.
exit_modesame type as mode or None, default=None: The mode of bobj after exiting the context. If None, this will be the same as mode.
exit_mesh_select_modesame type as mesh_select_mode or None, default=None: The mesh select modes of bobj after exiting the context. If None, this will be the same as mesh_select_mode.

See also

bpy.ops.object.mode_set: Sets the object interaction mode.
bpy.ops.object.mode_set_with_submode: Sets the object interaction mode and optionally also the mesh select modes. Used internally by this context manager.
bpy.types.Context.temp_override: A context manager that temporarily changes the values of bpy.types.Context objects, e.g. bpy.context.

Examples

>>> import bpy
>>> from ddg.blender.context import mode
>>>
>>> bpy.ops.mesh.primitive_cube_add()
{'FINISHED'}
>>> cube = bpy.context.object
>>> with mode(cube, mode="EDIT", exit_mode="OBJECT"):
...     print(f"Mode within the context: {cube.mode}")
...
Mode within the context: EDIT
>>> print(f"Mode after exiting the context: {cube.mode}")
Mode after exiting the context: OBJECT

Note that Blender doesn’t write changes to edit meshes to the mesh until the object exits edit mode.

>>> import bmesh
>>> import numpy as np
>>>
>>> co_original = np.vstack([v.co for v in cube.data.vertices])
>>> with mode(cube, mode="EDIT", exit_mode="OBJECT"):
...     bm = bmesh.from_edit_mesh(cube.data)
...     for v in bm.verts:
...         v.co *= 3
...     bmesh.update_edit_mesh(cube.data)
...     co_in_context = np.vstack([v.co for v in cube.data.vertices])
...
...     # Note that even after calling bmesh.update_edit_mesh,
...     # cube.data.vertices coordinates haven't changed.
...     # The changes are visible in the UI however!
...     assert np.allclose(co_original, co_in_context)
...

Upon exiting the context, the mode is set to OBJECT mode. Since this is a different mode from EDIT mode, the changes made in EDIT mode are written to cube.data.

>>> co_after_exit = np.vstack([v.co for v in cube.data.vertices])
>>> assert np.allclose(3 * co_original, co_after_exit)