Blender - Study Notes 33

What's the difference between bpy.ops.mesh and bmesh?

 

They are two quite different ways of manipulating mesh data in Blender's Python API.

The simplest way to think about them is:

bpy.ops.mesh = operate Blender's UI/operators
bmesh = directly manipulate mesh geometry/data

---

1. bpy.ops.mesh

bpy.ops.mesh contains Blender operators that correspond closely to things you can do through the Blender UI.

For example:

 

bpy.ops.mesh.subdivide()
bpy.ops.mesh.delete()
bpy.ops.mesh.extrude_region_move()
bpy.ops.mesh.normals_make_consistent()

 

These are similar to performing actions manually in Edit Mode:

 

Select vertices
      ↓
Edit Mode
      ↓
Subdivide
      ↓
Delete
      ↓
Recalculate Normals

 

For example:

 

import bpy

bpy.ops.object.mode_set(mode='EDIT')
bpy.ops.mesh.select_all(action='SELECT')
bpy.ops.mesh.subdivide(number_cuts=2)
bpy.ops.object.mode_set(mode='OBJECT')

 

The important characteristic

bpy.ops.mesh is context-dependent.

Blender needs to know things such as:

• Which object is active?
• Which objects are selected?
• Are we in Object Mode or Edit Mode?
• Which editor/area is active?
• Which mesh elements are selected?

For example:

 

bpy.ops.mesh.delete(type='VERT')

 

doesn't mean:

"Delete these vertices from this mesh data."

It means more like:

"Perform Blender's Delete operator in the current mesh editing context."

This is why scripts using bpy.ops can sometimes fail with errors such as:

 

RuntimeError: Operator bpy.ops.mesh.some_operator.poll() failed

 

---

2. bmesh

bmesh is Blender's mesh editing data structure/API.

Instead of telling Blender:

"Please perform the Subdivide operation as if I were using the UI."

you directly work with:

 

BMesh
 ├── BMVert
 ├── BMEdge
 └── BMFace

 

For example:

 

import bmesh

mesh = bpy.context.object.data

bm = bmesh.new()
bm.from_mesh(mesh)

# Work directly with the mesh
for vert in bm.verts:
    vert.co.z *= 2

bm.to_mesh(mesh)
bm.free()

 

Here you're directly modifying vertex coordinates.

Conceptually:

 

bpy.ops.mesh
     ↓
"Do this Blender operation"

bmesh
     ↓
"Give me the mesh geometry so I can manipulate it"

 

---

3. A very important difference

Consider this task:

Move every vertex 1 meter upward.

With bpy.ops.mesh, there isn't really a natural operator for this exact operation.

You might have to:

 

bpy.ops.object.mode_set(mode='EDIT')
bpy.ops.mesh.select_all(action='SELECT')
bpy.ops.transform.translate(value=(0, 0, 1))
bpy.ops.object.mode_set(mode='OBJECT')

 

With bmesh:

 

import bmesh

mesh = obj.data

bm = bmesh.new()
bm.from_mesh(mesh)

for v in bm.verts:
    v.co.z += 1.0

bm.to_mesh(mesh)
bm.free()

 

The second approach is much more direct.

---

4. bmesh gives you access to the actual topology

A mesh fundamentally consists of:

 

Vertices
    ↓
Edges
    ↓
Faces

 

bmesh exposes these directly:

 

bm.verts
bm.edges
bm.faces

 

For example:

 

for v in bm.verts:
    print(v.co)

for e in bm.edges:
    print(e.verts)

for f in bm.faces:
    print(f.verts)

 

You can therefore do things like:

 

for face in bm.faces:
    if face.calc_area() > 10:
        ...

 

or:

 

for vert in bm.verts:
    if vert.co.z > 5:
        vert.co.z += 1

 

This is particularly useful for procedural modeling.

---

5. bmesh is especially useful for creating geometry

For example, creating a cube:

 

import bmesh

mesh = bpy.data.meshes.new("MyMesh")
obj = bpy.data.objects.new("MyObject", mesh)

bpy.context.collection.objects.link(obj)

bm = bmesh.new()

bmesh.ops.create_cube(bm, size=2)

bm.to_mesh(mesh)
bm.free()

 

You can then directly modify the topology.

For example:

 

for v in bm.verts:
    v.co.z *= 2

 

This kind of workflow is very powerful for procedural modeling.

---

6. But bmesh doesn't replace bpy.ops

This is an important point.

There are many Blender operations that are not simply mesh-topology operations.

For example:

 

bpy.ops.object.modifier_apply(...)

 

That's not something you would normally replace with BMesh.

Likewise:

 

bpy.ops.object.shade_smooth()
bpy.ops.object.convert(target='MESH')
bpy.ops.object.join()

 

are object-level Blender operations.

So a good mental model is:

 

                    Blender Python
                         │
              ┌──────────┴──────────┐
              │                     │
          bpy.ops                bmesh
              │                     │
       Blender operations       Mesh geometry
              │                     │
       UI-like commands        vertices
       context dependent        edges
       mode dependent           faces

 

---

7. Performance is another major difference

Suppose you have:

 

100 objects
×
100,000 vertices

 

and you want to manipulate their vertices.

Calling operators repeatedly can be expensive because operators involve Blender's operator/context machinery.

For direct geometry processing, bmesh or even direct mesh.vertices access is usually much better.

For example, this:

 

for obj in objects:
    bpy.context.view_layer.objects.active = obj
    bpy.ops.object.mode_set(mode='EDIT')
    ...

 

can become slow and fragile.

Whereas:

 

for obj in objects:
    mesh = obj.data

    for v in mesh.vertices:
        v.co.z += 1

 

is much more direct.

---

8. bmesh vs mesh.vertices

There's another distinction worth knowing.

For simple vertex manipulation, you don't necessarily need BMesh.

You can directly access the regular Mesh data:

 

mesh = obj.data

for v in mesh.vertices:
    v.co.z += 1

 

So you can think of three levels:

 

bpy.ops
   │
   │  High-level operations
   ↓
bmesh
   │
   │  Editable topology
   ↓
Mesh datablock
   │
   │  Raw mesh data
   ↓
vertices / edges / polygons

 

For example:

Simple coordinate modification

Use:

 

obj.data.vertices

 

Topology manipulation

Use:

 

bmesh

 

Blender operation equivalent to a UI command

Use:

 

bpy.ops

 

---

9. One particularly important BMesh feature

BMesh supports edit-mode meshes very well.

For example:

 

bm = bmesh.from_edit_mesh(obj.data)

 

This gives you the BMesh corresponding to the mesh currently being edited.

Then:

 

bmesh.update_edit_mesh(obj.data)

 

updates the visible mesh.

Typical pattern:

 

import bmesh

obj = bpy.context.edit_object

bm = bmesh.from_edit_mesh(obj.data)

for v in bm.verts:
    if v.select:
        v.co.z += 1

bmesh.update_edit_mesh(obj.data)

 

This is much more powerful than trying to reproduce everything through operators.

---

10. For your Blender procedural modeling work

Since you're working with things like mountains, rocks, petals, plants, modifiers, and procedural geometry, I'd recommend learning them in roughly this order:

 

1. bpy.data
      ↓
2. bpy.ops
      ↓
3. Mesh data
      ↓
4. bmesh
      ↓
5. Geometry Nodes

 

And remember this rule:

If you're asking Blender to perform an operation, think bpy.ops. If you're asking Blender to let you manipulate the actual mesh topology, think bmesh.

For example:

 

# "Apply this modifier"
bpy.ops.object.modifier_apply(...)

# "Move these vertices"
bmesh

# "Create/delete/connect faces and edges"
bmesh

# "Add a modifier"
bpy.ops.object.modifier_add(...)

# "Change a vertex coordinate"
obj.data.vertices[i].co = ...

# "Join these objects"
bpy.ops.object.join()

 

That distinction will save you a lot of frustration when writing Blender Python scripts.