BMesh Module (bmesh)¶
This module provides access to blenders bmesh data structures.
Submodules:
Introduction¶
This API gives access the blenders internal mesh editing api, featuring geometry connectivity data and access to editing operations such as split, separate, collapse and dissolve.
The features exposed closely follow the C API, giving python access to the functions used by blenders own mesh editing tools.
For an overview of BMesh data types and how they reference each other see: BMesh Design Document .
Note
Disk and Radial data is not exposed by the python api since this is for internal use only.
Warning
TODO items are…
add access to BMesh walkers
add custom-data manipulation functions add/remove/rename.
Example Script¶
# This example assumes we have a mesh object selected
import bpy
import bmesh
# Get the active mesh
me = bpy.context.object.data
# Get a BMesh representation
bm = bmesh.new() # create an empty BMesh
bm.from_mesh(me) # fill it in from a Mesh
# Modify the BMesh, can do anything here...
for v in bm.verts:
v.co.x += 1.0
# Finish up, write the bmesh back to the mesh
bm.to_mesh(me)
bm.free() # free and prevent further access
Stand-Alone Module¶
The bmesh module is written to be standalone except for mathutils
which is used for vertex locations and normals.
The only other exception to this are when converting mesh data to and from bpy.types.Mesh
.
Mesh Access¶
There are 2 ways to access BMesh data, you can create a new BMesh by converting a mesh from
bpy.types.BlendData.meshes
or by accessing the current edit mode mesh.
see: bmesh.types.BMesh.from_mesh
and bmesh.from_edit_mesh
respectively.
When explicitly converting from mesh data python owns the data, that is to say - that the mesh only exists while python holds a reference to it, and the script is responsible for putting it back into a mesh data-block when the edits are done.
Note that unlike bpy
, a BMesh does not necessarily correspond to data in the currently open blend file,
a BMesh can be created, edited and freed without the user ever seeing or having access to it.
Unlike edit mode, the bmesh module can use multiple BMesh instances at once.
Take care when dealing with multiple BMesh instances since the mesh data can use a lot of memory, while a mesh that
python owns will be freed in when the script holds no references to it,
its good practice to call bmesh.types.BMesh.free
which will remove all the mesh data immediately and disable
further access.
EditMode Tessellation¶
When writing scripts that operate on editmode data you will normally want to re-calculate the tessellation after running the script, this needs to be called explicitly.
The BMesh its self does not store the triangulated faces, they are stored in the bpy.types.Mesh
,
to refresh tessellation triangles call bpy.types.Mesh.calc_loop_triangles
.
CustomData Access¶
BMesh has a unified way to access mesh attributes such as UV’s vertex colors, shape keys, edge crease etc.
This works by having a layers property on bmesh data sequences to access the custom data layers which can then be used to access the actual data on each vert/edge/face/loop.
Here are some examples …
uv_lay = bm.loops.layers.uv.active
for face in bm.faces:
for loop in face.loops:
uv = loop[uv_lay].uv
print("Loop UV: %f, %f" % uv[:])
vert = loop.vert
print("Loop Vert: (%f,%f,%f)" % vert.co[:])
shape_lay = bm.verts.layers.shape["Key.001"]
for vert in bm.verts:
shape = vert[shape_lay]
print("Vert Shape: %f, %f, %f" % (shape.x, shape.y, shape.z))
# in this example the active vertex group index is used,
# this is stored in the object, not the BMesh
group_index = obj.vertex_groups.active_index
# only ever one deform weight layer
dvert_lay = bm.verts.layers.deform.active
for vert in bm.verts:
dvert = vert[dvert_lay]
if group_index in dvert:
print("Weight %f" % dvert[group_index])
else:
print("Setting Weight")
dvert[group_index] = 0.5
Keeping a Correct State¶
When modeling in blender there are certain assumptions made about the state of the mesh.
hidden geometry isn’t selected.
when an edge is selected, its vertices are selected too.
when a face is selected, its edges and vertices are selected.
duplicate edges / faces don’t exist.
faces have at least 3 vertices.
To give developers flexibility these conventions are not enforced, however tools must leave the mesh in a valid state else other tools may behave incorrectly.
Any errors that arise from not following these conventions is considered a bug in the script, not a bug in blender.
Selection / Flushing¶
As mentioned above, it is possible to create an invalid selection state (by selecting a state and then de-selecting one of its vertices’s for example), mostly the best way to solve this is to flush the selection after performing a series of edits. this validates the selection state.
Module Functions¶
-
bmesh.
from_edit_mesh
(mesh)¶ Return a BMesh from this mesh, currently the mesh must already be in editmode.
- Parameters
mesh (
bpy.types.Mesh
) – The editmode mesh.- Returns
the BMesh associated with this mesh.
- Return type
-
bmesh.
new
(use_operators=True)¶ - Parameters
use_operators (bool) – Support calling operators in
bmesh.ops
(uses some extra memory per vert/edge/face).- Returns
Return a new, empty BMesh.
- Return type
-
bmesh.
update_edit_mesh
(mesh, loop_triangles=True, destructive=True)¶ Update the mesh after changes to the BMesh in editmode, optionally recalculating n-gon tessellation.
- Parameters
mesh (
bpy.types.Mesh
) – The editmode mesh.loop_triangles (boolean) – Option to recalculate n-gon tessellation.
destructive (boolean) – Use when geometry has been added or removed.