Mesh(ID)¶
Mesh Data¶
The mesh data is accessed in object mode and intended for compact storage,
for more flexible mesh editing from python see bmesh
.
Blender stores 4 main arrays to define mesh geometry.
Mesh.vertices
(3 points in space)Mesh.edges
(reference 2 vertices)Mesh.loops
(reference a single vertex and edge)Mesh.polygons
: (reference a range of loops)
Each polygon references a slice in the loop array, this way, polygons do not store vertices or corner data such as UVs directly, only a reference to loops that the polygon uses.
Mesh.loops
, Mesh.uv_layers
Mesh.vertex_colors
are all aligned so the same polygon loop
indices can be used to find the UVs and vertex colors as with as the vertices.
To compare mesh API options see: NGons and Tessellation Faces
This example script prints the vertices and UVs for each polygon, assumes the active object is a mesh with UVs.
import bpy
me = bpy.context.object.data
uv_layer = me.uv_layers.active.data
for poly in me.polygons:
print("Polygon index: {:d}, length: {:d}".format(poly.index, poly.loop_total))
# range is used here to show how the polygons reference loops,
# for convenience 'poly.loop_indices' can be used instead.
for loop_index in range(poly.loop_start, poly.loop_start + poly.loop_total):
print(" Vertex: {:d}".format(me.loops[loop_index].vertex_index))
print(" UV: {!r}".format(uv_layer[loop_index].uv))
base classes — bpy_struct
, ID
- class bpy.types.Mesh(ID)¶
Mesh data-block defining geometric surfaces
- attributes¶
Geometry attributes
- Type:
AttributeGroupMesh
bpy_prop_collection
ofAttribute
, (readonly)
- auto_texspace¶
Adjust active object’s texture space automatically when transforming object
- Type:
boolean, default True
- color_attributes¶
Geometry color attributes
- Type:
AttributeGroupMesh
bpy_prop_collection
ofAttribute
, (readonly)
- corner_normals¶
The “slit” normal direction of each face corner, influenced by vertex normals, sharp faces, sharp edges, and custom normals. May be empty.
- Type:
bpy_prop_collection
ofMeshNormalValue
, (readonly)
- edges¶
Edges of the mesh
- Type:
MeshEdges
bpy_prop_collection
ofMeshEdge
, (readonly)
- has_custom_normals¶
True if there are custom split normals data in this mesh
- Type:
boolean, default False, (readonly)
- is_editmode¶
True when used in editmode
- Type:
boolean, default False, (readonly)
- loop_triangle_polygons¶
The face index for each loop triangle
- Type:
bpy_prop_collection
ofReadOnlyInteger
, (readonly)
- loop_triangles¶
Tessellation of mesh polygons into triangles
- Type:
MeshLoopTriangles
bpy_prop_collection
ofMeshLoopTriangle
, (readonly)
- loops¶
Loops of the mesh (face corners)
- Type:
MeshLoops
bpy_prop_collection
ofMeshLoop
, (readonly)
- materials¶
- Type:
IDMaterials
bpy_prop_collection
ofMaterial
, (readonly)
- normals_domain¶
The attribute domain that gives enough information to represent the mesh’s normals
- Type:
enum in [‘POINT’, ‘FACE’, ‘CORNER’], default ‘FACE’, (readonly)
- polygon_normals¶
The normal direction of each face, defined by the winding order and position of its vertices
- Type:
bpy_prop_collection
ofMeshNormalValue
, (readonly)
- polygons¶
Polygons of the mesh
- Type:
MeshPolygons
bpy_prop_collection
ofMeshPolygon
, (readonly)
- remesh_mode¶
VOXEL
Voxel – Use the voxel remesher.QUAD
Quad – Use the quad remesher.
- Type:
enum in [‘VOXEL’, ‘QUAD’], default ‘VOXEL’
- remesh_voxel_adaptivity¶
Reduces the final face count by simplifying geometry where detail is not needed, generating triangles. A value greater than 0 disables Fix Poles.
- Type:
float in [0, 1], default 0.0
- remesh_voxel_size¶
Size of the voxel in object space used for volume evaluation. Lower values preserve finer details.
- Type:
float in [0.0001, inf], default 0.1
- skin_vertices¶
All skin vertices
- Type:
bpy_prop_collection
ofMeshSkinVertexLayer
, (readonly)
- texspace_location¶
Texture space location
- Type:
mathutils.Vector
of 3 items in [-inf, inf], default (0.0, 0.0, 0.0)
- texspace_size¶
Texture space size
- Type:
mathutils.Vector
of 3 items in [-inf, inf], default (1.0, 1.0, 1.0)
- total_edge_sel¶
Selected edge count in editmode
- Type:
int in [0, inf], default 0, (readonly)
- total_face_sel¶
Selected face count in editmode
- Type:
int in [0, inf], default 0, (readonly)
- total_vert_sel¶
Selected vertex count in editmode
- Type:
int in [0, inf], default 0, (readonly)
- use_auto_texspace¶
Adjust active object’s texture space automatically when transforming object
- Type:
boolean, default True
- use_mirror_topology¶
Use topology based mirroring (for when both sides of mesh have matching, unique topology)
- Type:
boolean, default False
- use_mirror_vertex_groups¶
Mirror the left/right vertex groups when painting. The symmetry axis is determined by the symmetry settings.
- Type:
boolean, default True
- use_mirror_x¶
Enable symmetry in the X axis
- Type:
boolean, default False
- use_mirror_y¶
Enable symmetry in the Y axis
- Type:
boolean, default False
- use_mirror_z¶
Enable symmetry in the Z axis
- Type:
boolean, default False
- use_paint_bone_selection¶
Bone selection during painting
- Type:
boolean, default False
- use_paint_mask¶
Face selection masking for painting
- Type:
boolean, default False
- use_paint_mask_vertex¶
Vertex selection masking for painting
- Type:
boolean, default False
- use_remesh_fix_poles¶
Produces fewer poles and a better topology flow
- Type:
boolean, default False
- use_remesh_preserve_attributes¶
Transfer all attributes to the new mesh
- Type:
boolean, default False
- use_remesh_preserve_volume¶
Projects the mesh to preserve the volume and details of the original mesh
- Type:
boolean, default False
- uv_layer_clone¶
UV loop layer to be used as cloning source
- Type:
- uv_layer_clone_index¶
Clone UV loop layer index
- Type:
int in [0, inf], default 0
- uv_layer_stencil¶
UV loop layer to mask the painted area
- Type:
- uv_layer_stencil_index¶
Mask UV loop layer index
- Type:
int in [0, inf], default 0
- uv_layers¶
All UV loop layers
- Type:
UVLoopLayers
bpy_prop_collection
ofMeshUVLoopLayer
, (readonly)
- vertex_colors¶
Legacy vertex color layers. Deprecated, use color attributes instead.
- Type:
LoopColors
bpy_prop_collection
ofMeshLoopColorLayer
, (readonly)
- vertex_normals¶
The normal direction of each vertex, defined as the average of the surrounding face normals
- Type:
bpy_prop_collection
ofMeshNormalValue
, (readonly)
- vertices¶
Vertices of the mesh
- Type:
MeshVertices
bpy_prop_collection
ofMeshVertex
, (readonly)
- edge_creases¶
Edge crease values for subdivision surface, corresponding to the “crease_edge” attribute.
(readonly)
- edge_keys¶
(readonly)
- vertex_creases¶
Vertex crease values for subdivision surface, corresponding to the “crease_vert” attribute.
(readonly)
- vertex_paint_mask¶
Mask values for sculpting and painting, corresponding to the “.sculpt_mask” attribute.
(readonly)
- transform(matrix, *, shape_keys=False)¶
Transform mesh vertices by a matrix (Warning: inverts normals if matrix is negative)
- Parameters:
matrix (
mathutils.Matrix
of 4 * 4 items in [-inf, inf]) – Matrixshape_keys (boolean, (optional)) – Transform Shape Keys
- flip_normals()¶
Invert winding of all polygons (clears tessellation, does not handle custom normals)
- set_sharp_from_angle(*, angle=3.14159)¶
Reset and fill the “sharp_edge” attribute based on the angle of faces neighboring manifold edges
- Parameters:
angle (float in [0, 3.14159], (optional)) – Angle, Angle between faces beyond which edges are marked sharp
- split_faces()¶
Split faces based on the edge angle
- calc_tangents(*, uvmap='')¶
Compute tangents and bitangent signs, to be used together with the split normals to get a complete tangent space for normal mapping (split normals are also computed if not yet present)
- Parameters:
uvmap (string, (optional, never None)) – Name of the UV map to use for tangent space computation
- free_tangents()¶
Free tangents
- calc_loop_triangles()¶
Calculate loop triangle tessellation (supports editmode too)
- calc_smooth_groups(*, use_bitflags=False)¶
Calculate smooth groups from sharp edges
- Parameters:
use_bitflags (boolean, (optional)) – Produce bitflags groups instead of simple numeric values
- Return (poly_groups, groups):
poly_groups, Smooth Groups, int array of 1 items in [-inf, inf]
groups, Total number of groups, int in [0, inf]
- normals_split_custom_set(normals)¶
Define custom split normals of this mesh (use zero-vectors to keep auto ones)
- Parameters:
normals (float multi-dimensional array of 1 * 3 items in [-1, 1]) – Normals
- normals_split_custom_set_from_vertices(normals)¶
Define custom split normals of this mesh, from vertices’ normals (use zero-vectors to keep auto ones)
- Parameters:
normals (float multi-dimensional array of 1 * 3 items in [-1, 1]) – Normals
- update(*, calc_edges=False, calc_edges_loose=False)¶
update
- Parameters:
calc_edges (boolean, (optional)) – Calculate Edges, Force recalculation of edges
calc_edges_loose (boolean, (optional)) – Calculate Loose Edges, Calculate the loose state of each edge
- update_gpu_tag()¶
update_gpu_tag
- unit_test_compare(*, mesh=None, threshold=7.1526e-06)¶
unit_test_compare
- Parameters:
mesh (
Mesh
, (optional)) – Mesh to compare tothreshold (float in [0, inf], (optional)) – Threshold, Comparison tolerance threshold
- Returns:
Return value, String description of result of comparison
- Return type:
string, (never None)
- clear_geometry()¶
Remove all geometry from the mesh. Note that this does not free shape keys or materials.
- validate(*, verbose=False, clean_customdata=True)¶
Validate geometry, return True when the mesh has had invalid geometry corrected/removed
- Parameters:
verbose (boolean, (optional)) – Verbose, Output information about the errors found
clean_customdata (boolean, (optional)) – Clean Custom Data, Remove temp/cached custom-data layers, like e.g. normals…
- Returns:
Result
- Return type:
boolean
- validate_material_indices()¶
Validate material indices of polygons, return True when the mesh has had invalid indices corrected (to default 0)
- Returns:
Result
- Return type:
boolean
- count_selected_items()¶
Return the number of selected items (vert, edge, face)
- Returns:
Result
- Return type:
int array of 3 items in [0, inf]
- edge_creases_ensure()¶
- edge_creases_remove()¶
- from_pydata(vertices, edges, faces, shade_flat=True)¶
Make a mesh from a list of vertices/edges/faces Until we have a nicer way to make geometry, use this.
- Parameters:
vertices (Iterable[Sequence[float]]) – float triplets each representing (X, Y, Z) eg: [(0.0, 1.0, 0.5), …].
edges (Iterable[Sequence[int]]) –
int pairs, each pair contains two indices to the vertices argument. eg: [(1, 2), …]
When an empty iterable is passed in, the edges are inferred from the polygons.
faces (Iterable[Sequence[int]]) – iterator of faces, each faces contains three or more indices to the vertices argument. eg: [(5, 6, 8, 9), (1, 2, 3), …]
Warning
Invalid mesh data (out of range indices, edges with matching indices, 2 sided faces… etc) are not prevented. If the data used for mesh creation isn’t known to be valid, run
Mesh.validate
after this function.
- shade_flat()¶
Render and display faces uniform, using face normals, setting the “sharp_face” attribute true for every face
- shade_smooth()¶
Render and display faces smooth, using interpolated vertex normals, removing the “sharp_face” attribute
- vertex_creases_ensure()¶
- vertex_creases_remove()¶
- vertex_paint_mask_ensure()¶
- vertex_paint_mask_remove()¶
- classmethod bl_rna_get_subclass(id, default=None)¶
- Parameters:
id (str) – The RNA type identifier.
- Returns:
The RNA type or default when not found.
- Return type:
bpy.types.Struct
subclass
- classmethod bl_rna_get_subclass_py(id, default=None)¶
- Parameters:
id (str) – The RNA type identifier.
- Returns:
The class or default when not found.
- Return type:
type