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

animation_data

Animation data for this data-block

Type:AnimData, (readonly)

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 of MeshEdge, (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 of MeshLoop, (readonly)

materials

Type:IDMaterials bpy_prop_collection of Material, (readonly)

polygon_layers_float

Type:PolygonFloatProperties bpy_prop_collection of MeshPolygonFloatPropertyLayer, (readonly)

polygon_layers_int

Type:PolygonIntProperties bpy_prop_collection of MeshPolygonIntPropertyLayer, (readonly)

polygon_layers_string

Type:PolygonStringProperties bpy_prop_collection of MeshPolygonStringPropertyLayer, (readonly)

polygons

Polygons of the mesh

Type:MeshPolygons bpy_prop_collection of MeshPolygon, (readonly)

shape_keys

Type:Key, (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 Subdivision Surface modifier

Type:boolean, default False

show_edge_seams

Display UV unwrapping seams

Type:boolean, default False

show_edge_sharp

Display sharp edges, used with the Edge Split 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 of MeshSkinVertexLayer, (readonly)

tessface_uv_textures

All UV maps for tessellated faces (read-only, for use by renderers)

Type:TessfaceUVTextures bpy_prop_collection of MeshTextureFaceLayer, (readonly)

tessface_vertex_colors

All tessellated face colors (read-only, for use by renderers)

Type:VertexColors bpy_prop_collection of MeshColorLayer, (readonly)

tessfaces

Tessellated faces of the mesh (derived from polygons)

Type:MeshTessFaces bpy_prop_collection of MeshTessFace, (readonly)

texco_mesh

Derive texture coordinates from another mesh

Type:Mesh

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)

texture_mesh

Use another mesh for texture indices (vertex indices must be aligned)

Type:Mesh

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 of MeshUVLoopLayer, (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 of MeshTexturePolyLayer, (readonly)

vertex_colors

All vertex colors

Type:LoopColors bpy_prop_collection of MeshLoopColorLayer, (readonly)

vertex_layers_float

Type:VertexFloatProperties bpy_prop_collection of MeshVertexFloatPropertyLayer, (readonly)

vertex_layers_int

Type:VertexIntProperties bpy_prop_collection of MeshVertexIntPropertyLayer, (readonly)

vertex_layers_string

Type:VertexStringProperties bpy_prop_collection of MeshVertexStringPropertyLayer, (readonly)

vertex_paint_masks

Vertex paint mask

Type:bpy_prop_collection of MeshPaintMaskLayer, (readonly)

vertices

Vertices of the mesh

Type:MeshVertices bpy_prop_collection of MeshVertex, (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

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_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 to Returns: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

bpy_struct.id_data ID.name ID.users ID.use_fake_user ID.tag

ID.is_updated ID.is_updated_data ID.is_library_indirect ID.library ID.preview

Inherited Functions

bpy_struct.as_pointer bpy_struct.driver_add bpy_struct.driver_remove bpy_struct.get bpy_struct.is_property_hidden bpy_struct.is_property_readonly bpy_struct.is_property_set bpy_struct.items bpy_struct.keyframe_delete bpy_struct.keyframe_insert bpy_struct.keys bpy_struct.path_from_id

bpy_struct.path_resolve bpy_struct.property_unset bpy_struct.type_recast bpy_struct.values ID.copy ID.user_clear ID.user_remap ID.make_local ID.user_of_id ID.animation_data_create ID.animation_data_clear ID.update_tag

References

bpy.context.mesh BlendData.meshes BlendDataMeshes.new BlendDataMeshes.new_from_object BlendDataMeshes.remove

EditObjectActuator.mesh Mesh.texco_mesh Mesh.texture_mesh Mesh.unit_test_compare Object.to_mesh