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 reference a slice in the loop array, this way, polygons do not store vertices or corner data such as UV’s 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 UV’s 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 UV’s 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" % (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" % me.loops[loop_index].vertex_index)
print(" UV: %r" % uv_layer[loop_index].uv)
base classes — bpy_struct
, ID
-
class
bpy.types.
Mesh
(ID)¶ Mesh data-block defining geometric surfaces
-
auto_smooth_angle
¶ Maximum angle between face normals that will be considered as smooth (unused if custom split normals data are available)
Type: float in [0, 3.14159], default 3.14159
-
auto_texspace
¶ Adjust active object’s texture space automatically when transforming object
Type: boolean, default False
-
cycles
¶ Cycles mesh settings
Type: CyclesMeshSettings
, (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)
-
loops
¶ Loops of the mesh (polygon corners)
Type: MeshLoops
bpy_prop_collection
ofMeshLoop
, (readonly)
-
materials
¶ Type: IDMaterials
bpy_prop_collection
ofMaterial
, (readonly)
-
polygon_layers_float
¶ Type: PolygonFloatProperties
bpy_prop_collection
ofMeshPolygonFloatPropertyLayer
, (readonly)
-
polygon_layers_int
¶ Type: PolygonIntProperties
bpy_prop_collection
ofMeshPolygonIntPropertyLayer
, (readonly)
-
polygon_layers_string
¶ Type: PolygonStringProperties
bpy_prop_collection
ofMeshPolygonStringPropertyLayer
, (readonly)
-
polygons
¶ Polygons of the mesh
Type: MeshPolygons
bpy_prop_collection
ofMeshPolygon
, (readonly)
-
show_double_sided
¶ Display the mesh with double or single sided lighting (OpenGL only)
Type: boolean, default False
-
show_edge_bevel_weight
¶ Display weights created for the Bevel modifier
Type: boolean, default False
-
show_edge_crease
¶ Display creases created for subsurf weighting
Type: boolean, default False
-
show_edge_seams
¶ Display UV unwrapping seams
Type: boolean, default False
-
show_edge_sharp
¶ Display sharp edges, used with the EdgeSplit modifier
Type: boolean, default False
-
show_edges
¶ Display selected edges using highlights in the 3D view and UV editor
Type: boolean, default False
-
show_extra_edge_angle
¶ Display selected edge angle, using global values when set in the transform panel
Type: boolean, default False
-
show_extra_edge_length
¶ Display selected edge lengths, using global values when set in the transform panel
Type: boolean, default False
-
show_extra_face_angle
¶ Display the angles in the selected edges, using global values when set in the transform panel
Type: boolean, default False
-
show_extra_face_area
¶ Display the area of selected faces, using global values when set in the transform panel
Type: boolean, default False
-
show_extra_indices
¶ Display the index numbers of selected vertices, edges, and faces
Type: boolean, default False
-
show_faces
¶ Display all faces as shades in the 3D view and UV editor
Type: boolean, default False
-
show_freestyle_edge_marks
¶ Display Freestyle edge marks, used with the Freestyle renderer
Type: boolean, default False
-
show_freestyle_face_marks
¶ Display Freestyle face marks, used with the Freestyle renderer
Type: boolean, default False
-
show_normal_face
¶ Display face normals as lines
Type: boolean, default False
-
show_normal_loop
¶ Display vertex-per-face normals as lines
Type: boolean, default False
-
show_normal_vertex
¶ Display vertex normals as lines
Type: boolean, default False
-
show_statvis
¶ Display statistical information about the mesh
Type: boolean, default False
-
show_weight
¶ Draw weights in editmode
Type: boolean, default False
-
skin_vertices
¶ All skin vertices
Type: bpy_prop_collection
ofMeshSkinVertexLayer
, (readonly)
-
tessface_uv_textures
¶ All UV maps for tessellated faces (read-only, for use by renderers)
Type: TessfaceUVTextures
bpy_prop_collection
ofMeshTextureFaceLayer
, (readonly)
-
tessface_vertex_colors
¶ All tessellated face colors (read-only, for use by renderers)
Type: VertexColors
bpy_prop_collection
ofMeshColorLayer
, (readonly)
-
tessfaces
¶ Tessellated faces of the mesh (derived from polygons)
Type: MeshTessFaces
bpy_prop_collection
ofMeshTessFace
, (readonly)
-
texspace_location
¶ Texture space location
Type: float array of 3 items in [-inf, inf], default (0.0, 0.0, 0.0)
-
texspace_size
¶ Texture space size
Type: float array of 3 items in [-inf, inf], default (0.0, 0.0, 0.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_smooth
¶ Auto smooth (based on smooth/sharp faces/edges and angle between faces), or use custom split normals data if available
Type: boolean, default False
-
use_auto_texspace
¶ Adjust active object’s texture space automatically when transforming object
Type: boolean, default False
-
use_customdata_edge_bevel
¶ Type: boolean, default False
-
use_customdata_edge_crease
¶ Type: boolean, default False
-
use_customdata_vertex_bevel
¶ Type: boolean, default False
-
use_mirror_topology
¶ Use topology based mirroring (for when both sides of mesh have matching, unique topology)
Type: boolean, default False
-
use_mirror_x
¶ X Axis mirror editing
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 (weight paint only)
Type: boolean, default False
-
uv_layer_clone
¶ UV loop layer to be used as cloning source
Type: MeshUVLoopLayer
-
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: MeshUVLoopLayer
-
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)
-
uv_texture_clone
¶ UV map to be used as cloning source
Type: MeshTexturePolyLayer
-
uv_texture_clone_index
¶ Clone UV map index
Type: int in [0, inf], default 0
-
uv_texture_stencil
¶ UV map to mask the painted area
Type: MeshTexturePolyLayer
-
uv_texture_stencil_index
¶ Mask UV map index
Type: int in [0, inf], default 0
-
uv_textures
¶ All UV maps
Type: UVTextures
bpy_prop_collection
ofMeshTexturePolyLayer
, (readonly)
-
vertex_colors
¶ All vertex colors
Type: LoopColors
bpy_prop_collection
ofMeshLoopColorLayer
, (readonly)
-
vertex_layers_float
¶ Type: VertexFloatProperties
bpy_prop_collection
ofMeshVertexFloatPropertyLayer
, (readonly)
-
vertex_layers_int
¶ Type: VertexIntProperties
bpy_prop_collection
ofMeshVertexIntPropertyLayer
, (readonly)
-
vertex_layers_string
¶ Type: VertexStringProperties
bpy_prop_collection
ofMeshVertexStringPropertyLayer
, (readonly)
-
vertex_paint_masks
¶ Vertex paint mask
Type: bpy_prop_collection
ofMeshPaintMaskLayer
, (readonly)
-
vertices
¶ Vertices of the mesh
Type: MeshVertices
bpy_prop_collection
ofMeshVertex
, (readonly)
-
edge_keys
¶ (readonly)
-
transform
(matrix, shape_keys=False)¶ Transform mesh vertices by a matrix (Warning: inverts normals if matrix is negative)
Parameters: - matrix (float array of 16 items in [-inf, inf]) – Matrix
- shape_keys (boolean, (optional)) – Transform Shape Keys
-
flip_normals
()¶ Invert winding of all polygons (clears tessellation, does not handle custom normals)
-
calc_normals
()¶ Calculate vertex normals
-
create_normals_split
()¶ Empty split vertex normals
-
calc_normals_split
()¶ Calculate split vertex normals, which preserve sharp edges
-
free_normals_split
()¶ Free split vertex normals
-
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_tessface
(free_mpoly=False)¶ Calculate face tessellation (supports editmode too)
Parameters: free_mpoly (boolean, (optional)) – Free MPoly, Free data used by polygons and loops. WARNING: This destructive operation removes regular faces, only used on temporary mesh data-blocks to reduce memory footprint of render engines and export scripts
-
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 array of 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 array of 3 items in [-1, 1]) – Normals
-
update
(calc_edges=False, calc_tessface=False)¶ update
Parameters: - calc_edges (boolean, (optional)) – Calculate Edges, Force recalculation of edges
- calc_tessface (boolean, (optional)) – Calculate Tessellation, Force recalculation of tessellation faces
-
unit_test_compare
(mesh=None)¶ unit_test_compare
Parameters: mesh ( Mesh
, (optional)) – Mesh to compare toReturns: Return value, String description of result of comparison Return type: string, (never None)
-
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
-
from_pydata
(vertices, edges, faces)¶ Make a mesh from a list of vertices/edges/faces Until we have a nicer way to make geometry, use this.
Parameters: - vertices (iterable object) – float triplets each representing (X, Y, Z) eg: [(0.0, 1.0, 0.5), ...].
- edges (iterable object) – int pairs, each pair contains two indices to the vertices argument. eg: [(1, 2), ...]
- faces (iterable object) – 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.
-
Inherited Properties
Inherited Functions
References