BMesh Types (bmesh.types)

Base Mesh Type

class bmesh.types.BMesh

The BMesh data structure

calc_loop_triangles()

Calculate triangle tessellation from quads/ngons.

Returns

The triangulated faces.

Return type

list of BMLoop tuples

calc_volume(signed=False)

Calculate mesh volume based on face normals.

Parameters

signed (bool) – when signed is true, negative values may be returned.

Returns

The volume of the mesh.

Return type

float

clear()

Clear all mesh data.

copy()
Returns

A copy of this BMesh.

Return type

BMesh

free()

Explicitly free the BMesh data from memory, causing exceptions on further access.

Note

The BMesh is freed automatically, typically when the script finishes executing. However in some cases its hard to predict when this will be and its useful to explicitly free the data.

from_mesh(mesh, face_normals=True, use_shape_key=False, shape_key_index=0)

Initialize this bmesh from existing mesh datablock.

Parameters
  • mesh (Mesh) – The mesh data to load.

  • use_shape_key (boolean) – Use the locations from a shape key.

  • shape_key_index (int) – The shape key index to use.

Note

Multiple calls can be used to join multiple meshes.

Custom-data layers are only copied from mesh on initialization. Further calls will copy custom-data to matching layers, layers missing on the target mesh wont be added.

from_object(object, depsgraph, deform=True, cage=False, face_normals=True)

Initialize this bmesh from existing object datablock (currently only meshes are supported).

Parameters
  • object (Object) – The object data to load.

  • deform (boolean) – Apply deformation modifiers.

  • cage (boolean) – Get the mesh as a deformed cage.

  • face_normals (boolean) – Calculate face normals.

normal_update()

Update mesh normals.

select_flush(select)

Flush selection, independent of the current selection mode.

Parameters

select (boolean) – flush selection or de-selected elements.

select_flush_mode()

flush selection based on the current mode current BMesh.select_mode.

to_mesh(mesh)

Writes this BMesh data into an existing Mesh datablock.

Parameters

mesh (Mesh) – The mesh data to write into.

transform(matrix, filter=None)

Transform the mesh (optionally filtering flagged data only).

Parameters
  • matrix (4x4 mathutils.Matrix) – transform matrix.

  • filter (set) – set of values in (‘SELECT’, ‘HIDE’, ‘SEAM’, ‘SMOOTH’, ‘TAG’).

edges

This meshes edge sequence (read-only).

Type

BMEdgeSeq

faces

This meshes face sequence (read-only).

Type

BMFaceSeq

is_valid

True when this element is valid (hasn’t been removed).

Type

boolean

is_wrapped

True when this mesh is owned by blender (typically the editmode BMesh).

Type

boolean

loops

This meshes loops (read-only).

Type

BMLoopSeq

Note

Loops must be accessed via faces, this is only exposed for layer access.

select_history

Sequence of selected items (the last is displayed as active).

Type

BMEditSelSeq

select_mode

The selection mode, values can be {‘VERT’, ‘EDGE’, ‘FACE’}, can’t be assigned an empty set.

Type

set

verts

This meshes vert sequence (read-only).

Type

BMVertSeq

Mesh Elements

class bmesh.types.BMVert

The BMesh vertex type

calc_edge_angle(fallback=None)

Return the angle between this vert’s two connected edges.

Parameters

fallback (any) – return this when the vert doesn’t have 2 edges (instead of raising a ValueError).

Returns

Angle between edges in radians.

Return type

float

calc_shell_factor()

Return a multiplier calculated based on the sharpness of the vertex. Where a flat surface gives 1.0, and higher values sharper edges. This is used to maintain shell thickness when offsetting verts along their normals.

Returns

offset multiplier

Return type

float

copy_from(other)

Copy values from another element of matching type.

copy_from_face_interp(face)

Interpolate the customdata from a face onto this loop (the loops vert should overlap the face).

Parameters

face (BMFace) – The face to interpolate data from.

copy_from_vert_interp(vert_pair, fac)

Interpolate the customdata from a vert between 2 other verts.

Parameters

vert_pair (BMVert) – The vert to interpolate data from.

hide_set(hide)

Set the hide state. This is different from the hide attribute because it updates the selection and hide state of associated geometry.

Parameters

hide (boolean) – Hidden or visible.

normal_update()

Update vertex normal.

select_set(select)

Set the selection. This is different from the select attribute because it updates the selection state of associated geometry.

Parameters

select (boolean) – Select or de-select.

Note

Currently this only flushes down, so selecting a face will select all its vertices but de-selecting a vertex won’t de-select all the faces that use it, before finishing with a mesh typically flushing is still needed.

co

The coordinates for this vertex as a 3D, wrapped vector.

Type

mathutils.Vector

hide

Hidden state of this element.

Type

boolean

index

Index of this element.

Type

int

Note

This value is not necessarily valid, while editing the mesh it can become dirty.

It’s also possible to assign any number to this attribute for a scripts internal logic.

To ensure the value is up to date - see BMElemSeq.index_update.

is_boundary

True when this vertex is connected to boundary edges (read-only).

Type

boolean

is_manifold

True when this vertex is manifold (read-only).

Type

boolean

is_valid

True when this element is valid (hasn’t been removed).

Type

boolean

is_wire

True when this vertex is not connected to any faces (read-only).

Type

boolean

link_edges

Edges connected to this vertex (read-only).

Type

BMElemSeq of BMEdge

link_faces

Faces connected to this vertex (read-only).

Type

BMElemSeq of BMFace

link_loops

Loops that use this vertex (read-only).

Type

BMElemSeq of BMLoop

normal

The normal for this vertex as a 3D, wrapped vector.

Type

mathutils.Vector

select

Selected state of this element.

Type

boolean

tag

Generic attribute scripts can use for own logic

Type

boolean

class bmesh.types.BMEdge

The BMesh edge connecting 2 verts

calc_face_angle(fallback=None)
Parameters

fallback (any) – return this when the edge doesn’t have 2 faces (instead of raising a ValueError).

Returns

The angle between 2 connected faces in radians.

Return type

float

calc_face_angle_signed(fallback=None)
Parameters

fallback (any) – return this when the edge doesn’t have 2 faces (instead of raising a ValueError).

Returns

The angle between 2 connected faces in radians (negative for concave join).

Return type

float

calc_length()
Returns

The length between both verts.

Return type

float

calc_tangent(loop)

Return the tangent at this edge relative to a face (pointing inward into the face). This uses the face normal for calculation.

Parameters

loop (BMLoop) – The loop used for tangent calculation.

Returns

a normalized vector.

Return type

mathutils.Vector

copy_from(other)

Copy values from another element of matching type.

hide_set(hide)

Set the hide state. This is different from the hide attribute because it updates the selection and hide state of associated geometry.

Parameters

hide (boolean) – Hidden or visible.

normal_update()

Update edges vertex normals.

other_vert(vert)

Return the other vertex on this edge or None if the vertex is not used by this edge.

Parameters

vert (BMVert) – a vert in this edge.

Returns

The edges other vert.

Return type

BMVert or None

select_set(select)

Set the selection. This is different from the select attribute because it updates the selection state of associated geometry.

Parameters

select (boolean) – Select or de-select.

Note

Currently this only flushes down, so selecting a face will select all its vertices but de-selecting a vertex won’t de-select all the faces that use it, before finishing with a mesh typically flushing is still needed.

hide

Hidden state of this element.

Type

boolean

index

Index of this element.

Type

int

Note

This value is not necessarily valid, while editing the mesh it can become dirty.

It’s also possible to assign any number to this attribute for a scripts internal logic.

To ensure the value is up to date - see BMElemSeq.index_update.

is_boundary

True when this edge is at the boundary of a face (read-only).

Type

boolean

is_contiguous

True when this edge is manifold, between two faces with the same winding (read-only).

Type

boolean

is_convex

True when this edge joins two convex faces, depends on a valid face normal (read-only).

Type

boolean

is_manifold

True when this edge is manifold (read-only).

Type

boolean

is_valid

True when this element is valid (hasn’t been removed).

Type

boolean

is_wire

True when this edge is not connected to any faces (read-only).

Type

boolean

link_faces

Faces connected to this edge, (read-only).

Type

BMElemSeq of BMFace

link_loops

Loops connected to this edge, (read-only).

Type

BMElemSeq of BMLoop

seam

Seam for UV unwrapping.

Type

boolean

select

Selected state of this element.

Type

boolean

smooth

Smooth state of this element.

Type

boolean

tag

Generic attribute scripts can use for own logic

Type

boolean

verts

Verts this edge uses (always 2), (read-only).

Type

BMElemSeq of BMVert

class bmesh.types.BMFace

The BMesh face with 3 or more sides

calc_area()

Return the area of the face.

Returns

Return the area of the face.

Return type

float

calc_center_bounds()

Return bounds center of the face.

Returns

a 3D vector.

Return type

mathutils.Vector

calc_center_median()

Return median center of the face.

Returns

a 3D vector.

Return type

mathutils.Vector

calc_center_median_weighted()

Return median center of the face weighted by edge lengths.

Returns

a 3D vector.

Return type

mathutils.Vector

calc_perimeter()

Return the perimeter of the face.

Returns

Return the perimeter of the face.

Return type

float

calc_tangent_edge()

Return face tangent based on longest edge.

Returns

a normalized vector.

Return type

mathutils.Vector

calc_tangent_edge_diagonal()

Return face tangent based on the edge farthest from any vertex.

Returns

a normalized vector.

Return type

mathutils.Vector

calc_tangent_edge_pair()

Return face tangent based on the two longest disconnected edges.

  • Tris: Use the edge pair with the most similar lengths.

  • Quads: Use the longest edge pair.

  • NGons: Use the two longest disconnected edges.

Returns

a normalized vector.

Return type

mathutils.Vector

calc_tangent_vert_diagonal()

Return face tangent based on the two most distent vertices.

Returns

a normalized vector.

Return type

mathutils.Vector

copy(verts=True, edges=True)

Make a copy of this face.

Parameters
  • verts (boolean) – When set, the faces verts will be duplicated too.

  • edges (boolean) – When set, the faces edges will be duplicated too.

Returns

The newly created face.

Return type

BMFace

copy_from(other)

Copy values from another element of matching type.

copy_from_face_interp(face, vert=True)

Interpolate the customdata from another face onto this one (faces should overlap).

Parameters
  • face (BMFace) – The face to interpolate data from.

  • vert (boolean) – When True, also copy vertex data.

hide_set(hide)

Set the hide state. This is different from the hide attribute because it updates the selection and hide state of associated geometry.

Parameters

hide (boolean) – Hidden or visible.

normal_flip()

Reverses winding of a face, which flips its normal.

normal_update()

Update face’s normal.

select_set(select)

Set the selection. This is different from the select attribute because it updates the selection state of associated geometry.

Parameters

select (boolean) – Select or de-select.

Note

Currently this only flushes down, so selecting a face will select all its vertices but de-selecting a vertex won’t de-select all the faces that use it, before finishing with a mesh typically flushing is still needed.

edges

Edges of this face, (read-only).

Type

BMElemSeq of BMEdge

hide

Hidden state of this element.

Type

boolean

index

Index of this element.

Type

int

Note

This value is not necessarily valid, while editing the mesh it can become dirty.

It’s also possible to assign any number to this attribute for a scripts internal logic.

To ensure the value is up to date - see BMElemSeq.index_update.

is_valid

True when this element is valid (hasn’t been removed).

Type

boolean

loops

Loops of this face, (read-only).

Type

BMElemSeq of BMLoop

material_index

The face’s material index.

Type

int

normal

The normal for this face as a 3D, wrapped vector.

Type

mathutils.Vector

select

Selected state of this element.

Type

boolean

smooth

Smooth state of this element.

Type

boolean

tag

Generic attribute scripts can use for own logic

Type

boolean

verts

Verts of this face, (read-only).

Type

BMElemSeq of BMVert

class bmesh.types.BMLoop

This is normally accessed from BMFace.loops where each face loop represents a corner of the face.

calc_angle()

Return the angle at this loops corner of the face. This is calculated so sharper corners give lower angles.

Returns

The angle in radians.

Return type

float

calc_normal()

Return normal at this loops corner of the face. Falls back to the face normal for straight lines.

Returns

a normalized vector.

Return type

mathutils.Vector

calc_tangent()

Return the tangent at this loops corner of the face (pointing inward into the face). Falls back to the face normal for straight lines.

Returns

a normalized vector.

Return type

mathutils.Vector

copy_from(other)

Copy values from another element of matching type.

copy_from_face_interp(face, vert=True, multires=True)

Interpolate the customdata from a face onto this loop (the loops vert should overlap the face).

Parameters
  • face (BMFace) – The face to interpolate data from.

  • vert (boolean) – When enabled, interpolate the loops vertex data (optional).

  • multires (boolean) – When enabled, interpolate the loops multires data (optional).

edge

The loop’s edge (between this loop and the next), (read-only).

Type

BMEdge

face

The face this loop makes (read-only).

Type

BMFace

index

Index of this element.

Type

int

Note

This value is not necessarily valid, while editing the mesh it can become dirty.

It’s also possible to assign any number to this attribute for a scripts internal logic.

To ensure the value is up to date - see BMElemSeq.index_update.

is_convex

True when this loop is at the convex corner of a face, depends on a valid face normal (read-only).

Type

boolean

is_valid

True when this element is valid (hasn’t been removed).

Type

boolean

link_loop_next

The next face corner (read-only).

Type

BMLoop

link_loop_prev

The previous face corner (read-only).

Type

BMLoop

link_loop_radial_next

The next loop around the edge (read-only).

Type

BMLoop

link_loop_radial_prev

The previous loop around the edge (read-only).

Type

BMLoop

link_loops

Loops connected to this loop, (read-only).

Type

BMElemSeq of BMLoop

tag

Generic attribute scripts can use for own logic

Type

boolean

vert

The loop’s vertex (read-only).

Type

BMVert

Sequence Accessors

class bmesh.types.BMElemSeq

General sequence type used for accessing any sequence of BMVert, BMEdge, BMFace, BMLoop.

When accessed via BMesh.verts, BMesh.edges, BMesh.faces there are also functions to create/remomove items.

index_update()

Initialize the index values of this sequence.

This is the equivalent of looping over all elements and assigning the index values.

for index, ele in enumerate(sequence):
    ele.index = index

Note

Running this on sequences besides BMesh.verts, BMesh.edges, BMesh.faces works but wont result in each element having a valid index, instead its order in the sequence will be set.

class bmesh.types.BMVertSeq
ensure_lookup_table()

Ensure internal data needed for int subscription is initialized with verts/edges/faces, eg bm.verts[index].

This needs to be called again after adding/removing data in this sequence.

index_update()

Initialize the index values of this sequence.

This is the equivalent of looping over all elements and assigning the index values.

for index, ele in enumerate(sequence):
    ele.index = index

Note

Running this on sequences besides BMesh.verts, BMesh.edges, BMesh.faces works but wont result in each element having a valid index, instead its order in the sequence will be set.

new(co=(0.0, 0.0, 0.0), example=None)

Create a new vertex.

Parameters
  • co (float triplet) – The initial location of the vertex (optional argument).

  • example (BMVert) – Existing vert to initialize settings.

Returns

The newly created edge.

Return type

BMVert

remove(vert)

Remove a vert.

sort(key=None, reverse=False)

Sort the elements of this sequence, using an optional custom sort key. Indices of elements are not changed, BMElemeSeq.index_update() can be used for that.

Parameters
  • key – The key that sets the ordering of the elements.

  • reverse – Reverse the order of the elements

Note

When the ‘key’ argument is not provided, the elements are reordered following their current index value. In particular this can be used by setting indices manually before calling this method.

Warning

Existing references to the N’th element, will continue to point the data at that index.

layers

custom-data layers (read-only).

Type

BMLayerAccessVert

class bmesh.types.BMEdgeSeq
ensure_lookup_table()

Ensure internal data needed for int subscription is initialized with verts/edges/faces, eg bm.verts[index].

This needs to be called again after adding/removing data in this sequence.

get(verts, fallback=None)

Return an edge which uses the verts passed.

Parameters
  • verts (BMVert) – Sequence of verts.

  • fallback – Return this value if nothing is found.

Returns

The edge found or None

Return type

BMEdge

index_update()

Initialize the index values of this sequence.

This is the equivalent of looping over all elements and assigning the index values.

for index, ele in enumerate(sequence):
    ele.index = index

Note

Running this on sequences besides BMesh.verts, BMesh.edges, BMesh.faces works but wont result in each element having a valid index, instead its order in the sequence will be set.

new(verts, example=None)

Create a new edge from a given pair of verts.

Parameters
  • verts (pair of BMVert) – Vertex pair.

  • example (BMEdge) – Existing edge to initialize settings (optional argument).

Returns

The newly created edge.

Return type

BMEdge

remove(edge)

Remove an edge.

sort(key=None, reverse=False)

Sort the elements of this sequence, using an optional custom sort key. Indices of elements are not changed, BMElemeSeq.index_update() can be used for that.

Parameters
  • key – The key that sets the ordering of the elements.

  • reverse – Reverse the order of the elements

Note

When the ‘key’ argument is not provided, the elements are reordered following their current index value. In particular this can be used by setting indices manually before calling this method.

Warning

Existing references to the N’th element, will continue to point the data at that index.

layers

custom-data layers (read-only).

Type

BMLayerAccessEdge

class bmesh.types.BMFaceSeq
ensure_lookup_table()

Ensure internal data needed for int subscription is initialized with verts/edges/faces, eg bm.verts[index].

This needs to be called again after adding/removing data in this sequence.

get(verts, fallback=None)

Return a face which uses the verts passed.

Parameters
  • verts (BMVert) – Sequence of verts.

  • fallback – Return this value if nothing is found.

Returns

The face found or None

Return type

BMFace

index_update()

Initialize the index values of this sequence.

This is the equivalent of looping over all elements and assigning the index values.

for index, ele in enumerate(sequence):
    ele.index = index

Note

Running this on sequences besides BMesh.verts, BMesh.edges, BMesh.faces works but wont result in each element having a valid index, instead its order in the sequence will be set.

new(verts, example=None)

Create a new face from a given set of verts.

Parameters
  • verts (BMVert) – Sequence of 3 or more verts.

  • example (BMFace) – Existing face to initialize settings (optional argument).

Returns

The newly created face.

Return type

BMFace

remove(face)

Remove a face.

sort(key=None, reverse=False)

Sort the elements of this sequence, using an optional custom sort key. Indices of elements are not changed, BMElemeSeq.index_update() can be used for that.

Parameters
  • key – The key that sets the ordering of the elements.

  • reverse – Reverse the order of the elements

Note

When the ‘key’ argument is not provided, the elements are reordered following their current index value. In particular this can be used by setting indices manually before calling this method.

Warning

Existing references to the N’th element, will continue to point the data at that index.

active

active face.

Type

BMFace or None

layers

custom-data layers (read-only).

Type

BMLayerAccessFace

class bmesh.types.BMLoopSeq
layers

custom-data layers (read-only).

Type

BMLayerAccessLoop

class bmesh.types.BMIter

Internal BMesh type for looping over verts/faces/edges, used for iterating over BMElemSeq types.

Selection History

class bmesh.types.BMEditSelSeq
add(element)

Add an element to the selection history (no action taken if its already added).

clear()

Empties the selection history.

discard(element)

Discard an element from the selection history.

Like remove but doesn’t raise an error when the elements not in the selection list.

remove(element)

Remove an element from the selection history.

validate()

Ensures all elements in the selection history are selected.

active

The last selected element or None (read-only).

Type

BMVert, BMEdge or BMFace

class bmesh.types.BMEditSelIter

Custom-Data Layer Access

class bmesh.types.BMLayerAccessVert

Exposes custom-data layer attributes.

bevel_weight

Bevel weight float in [0 - 1].

Type

BMLayerCollection

deform

Vertex deform weight BMDeformVert (TODO).

type: BMLayerCollection

float

Generic float custom-data layer.

type: BMLayerCollection

int

Generic int custom-data layer.

type: BMLayerCollection

paint_mask

Accessor for paint mask layer.

type: BMLayerCollection

shape

Vertex shapekey absolute location (as a 3D Vector).

Type

BMLayerCollection

skin

Accessor for skin layer.

type: BMLayerCollection

string

Generic string custom-data layer (exposed as bytes, 255 max length).

type: BMLayerCollection

class bmesh.types.BMLayerAccessEdge

Exposes custom-data layer attributes.

bevel_weight

Bevel weight float in [0 - 1].

Type

BMLayerCollection

crease

Edge crease for subdivision surface - float in [0 - 1].

Type

BMLayerCollection

float

Generic float custom-data layer.

type: BMLayerCollection

freestyle

Accessor for Freestyle edge layer.

type: BMLayerCollection

int

Generic int custom-data layer.

type: BMLayerCollection

string

Generic string custom-data layer (exposed as bytes, 255 max length).

type: BMLayerCollection

class bmesh.types.BMLayerAccessFace

Exposes custom-data layer attributes.

face_map

FaceMap custom-data layer.

type: BMLayerCollection

float

Generic float custom-data layer.

type: BMLayerCollection

freestyle

Accessor for Freestyle face layer.

type: BMLayerCollection

int

Generic int custom-data layer.

type: BMLayerCollection

string

Generic string custom-data layer (exposed as bytes, 255 max length).

type: BMLayerCollection

class bmesh.types.BMLayerAccessLoop

Exposes custom-data layer attributes.

color

Accessor for vertex color layer.

type: BMLayerCollection

float

Generic float custom-data layer.

type: BMLayerCollection

int

Generic int custom-data layer.

type: BMLayerCollection

string

Generic string custom-data layer (exposed as bytes, 255 max length).

type: BMLayerCollection

uv

Accessor for BMLoopUV UV (as a 2D Vector).

type: BMLayerCollection

class bmesh.types.BMLayerCollection

Gives access to a collection of custom-data layers of the same type and behaves like python dictionaries, except for the ability to do list like index access.

get(key, default=None)

Returns the value of the layer matching the key or default when not found (matches pythons dictionary function of the same name).

Parameters
  • key (string) – The key associated with the layer.

  • default (Undefined) – Optional argument for the value to return if key is not found.

items()

Return the identifiers of collection members (matching pythons dict.items() functionality).

Returns

(key, value) pairs for each member of this collection.

Return type

list of tuples

keys()

Return the identifiers of collection members (matching pythons dict.keys() functionality).

Returns

the identifiers for each member of this collection.

Return type

list of strings

new(name)

Create a new layer

Parameters

name (string) – Optional name argument (will be made unique).

Returns

The newly created layer.

Return type

BMLayerItem

remove(layer)

Remove a layer

Parameters

layer (BMLayerItem) – The layer to remove.

values()

Return the values of collection (matching pythons dict.values() functionality).

Returns

the members of this collection.

Return type

list

verify()

Create a new layer or return an existing active layer

Returns

The newly verified layer.

Return type

BMLayerItem

active

The active layer of this type (read-only).

Type

BMLayerItem

is_singleton

True if there can exists only one layer of this type (read-only).

Type

boolean

class bmesh.types.BMLayerItem

Exposes a single custom data layer, their main purpose is for use as item accessors to custom-data when used with vert/edge/face/loop data.

copy_from(other)

Return a copy of the layer

Parameters
  • other – Another layer to copy from.

  • otherBMLayerItem

name

The layers unique name (read-only).

Type

string

Custom-Data Layer Types

class bmesh.types.BMLoopUV
pin_uv

UV pin state.

Type

boolean

select

UV select state.

Type

boolean

uv

Loops UV (as a 2D Vector).

Type

mathutils.Vector

class bmesh.types.BMDeformVert
clear()

Clears all weights.

get(key, default=None)

Returns the deform weight matching the key or default when not found (matches pythons dictionary function of the same name).

Parameters
  • key (int) – The key associated with deform weight.

  • default (Undefined) – Optional argument for the value to return if key is not found.

items()

Return (group, weight) pairs for this vertex (matching pythons dict.items() functionality).

Returns

(key, value) pairs for each deform weight of this vertex.

Return type

list of tuples

keys()

Return the group indices used by this vertex (matching pythons dict.keys() functionality).

Returns

the deform group this vertex uses

Return type

list of ints

values()

Return the weights of the deform vertex (matching pythons dict.values() functionality).

Returns

The weights that influence this vertex

Return type

list of floats