add mesh example with docs explaining polygon / loop relationship
[blender.git] / doc / python_api / examples / bpy.types.Mesh.py
1 """
2 Mesh Data
3 +++++++++
4
5 The mesh data is accessed in object mode and intended for compact storage,
6 for more flexible mesh editing from python see :mod:`bmesh`.
7
8 Blender stores 4 main arrays to define mesh geometry.
9
10 * :class:`Mesh.vertices` (3 points in space)
11 * :class:`Mesh.edges` (reference 2 vertices)
12 * :class:`Mesh.loops` (reference a single vertex and edge)
13 * :class:`Mesh.polygons`: (reference a range of loops)
14
15
16 Each polygon reference a slice in the loop array, this way, polygons do not store vertices or corner data such as UV's directly,
17 only a reference to loops that the polygon uses.
18
19 :class:`Mesh.loops`, :class:`Mesh.uv_layers` :class:`Mesh.vertex_colors` are all aligned so the same polygon loop
20 indicies can be used to find the UV's and vertex colors as with as the vertices.
21
22 To compare mesh API options see: :ref:`NGons and Tessellation Faces <info_gotcha_mesh_faces>`
23
24
25 This example script prints the vertices and UV's for each polygon, assumes the active object is a mesh with UVs.
26 """
27
28 import bpy
29
30 me = bpy.context.object.data
31 uv_layer = me.uv.layers.active.data
32
33 for poly in me.polygons:
34     print("Polygon index: %d, length: %d" % (poly.index, poly.loop_total))
35
36     # range is used here to show how the polygons reference loops,
37     # for convenience 'poly.loop_indices' can be used instead.
38     for loop_index in range(poly.loop_start, poly.loop_start + poly.loop_total):
39         print("    Vertex: %d" % me.loops[loop_index].vertex_index)
40         print("    UV: %r" % uv_layer[loop_index].uv)
41