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.
- 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, vertex_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 won’t be added.
- from_object(object, depsgraph, cage=False, face_normals=True, vertex_normals=True)
Initialize this bmesh from existing object data-block (only meshes are currently supported).
- Parameters
object (
Object
) – The object data to load.cage (boolean) – Get the mesh as a deformed cage.
face_normals (boolean) – Calculate face normals.
vertex_normals – Calculate vertex 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’).
- 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
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
- select_mode
The selection mode, values can be {‘VERT’, ‘EDGE’, ‘FACE’}, can’t be assigned an empty set.
- Type
set
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
- 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
- normal
The normal for this vertex as a 3D, wrapped vector.
- Type
- 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
- 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.
- 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
- 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
- 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
- calc_center_median()
Return median center of the face.
- Returns
a 3D vector.
- Return type
- calc_center_median_weighted()
Return median center of the face weighted by edge lengths.
- Returns
a 3D vector.
- Return type
- 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
- calc_tangent_edge_diagonal()
Return face tangent based on the edge farthest from any vertex.
- Returns
a normalized vector.
- Return type
- 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
- calc_tangent_vert_diagonal()
Return face tangent based on the two most distant vertices.
- Returns
a normalized vector.
- Return type
- 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
- 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.
- 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
- material_index
The face’s material index.
- Type
int
- normal
The normal for this face as a 3D, wrapped vector.
- Type
- 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
- 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
- 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
- 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).
- 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
- tag
Generic attribute scripts can use for own logic
- Type
boolean
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/remove 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 won’t 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 won’t 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.
- 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
- 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.
- 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 won’t 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.
- 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
- 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.
- 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 won’t 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.
- 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.
- layers
custom-data layers (read-only).
- Type
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.
- 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
- color
Generic RGBA color with 8-bit precision custom-data layer.
type:
BMLayerCollection
- deform
Vertex deform weight
BMDeformVert
(TODO).type:
BMLayerCollection
- float
Generic float custom-data layer.
type:
BMLayerCollection
- float_color
Generic RGBA color with float precision custom-data layer.
type:
BMLayerCollection
- float_vector
Generic 3D vector with float precision 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
- 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
- color
Generic RGBA color with 8-bit precision custom-data layer.
type:
BMLayerCollection
- crease
Edge crease for subdivision surface - float in [0 - 1].
- Type
- float
Generic float custom-data layer.
type:
BMLayerCollection
- float_color
Generic RGBA color with float precision custom-data layer.
type:
BMLayerCollection
- float_vector
Generic 3D vector with float precision 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.
- color
Generic RGBA color with 8-bit precision custom-data layer.
type:
BMLayerCollection
- face_map
FaceMap custom-data layer.
type:
BMLayerCollection
- float
Generic float custom-data layer.
type:
BMLayerCollection
- float_color
Generic RGBA color with float precision custom-data layer.
type:
BMLayerCollection
- float_vector
Generic 3D vector with float precision 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
Generic RGBA color with 8-bit precision custom-data layer.
type:
BMLayerCollection
- float
Generic float custom-data layer.
type:
BMLayerCollection
- float_color
Generic RGBA color with float precision custom-data layer.
type:
BMLayerCollection
- float_vector
Generic 3D vector with float precision 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
- 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
- active
The active layer of this type (read-only).
- Type
- 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.
other –
BMLayerItem
- 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
- 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