Merge branch 'blender2.7' of git.blender.org:blender
[blender.git] / doc / python_api / rst / include__bmesh.rst
1 ..
2    This document is appended to the auto generated bmesh api doc to avoid clogging up the C files with details.
3    to test this run:
4    ./blender.bin -b -noaudio -P doc/python_api/sphinx_doc_gen.py -- \
5                  --partial bmesh* ; cd doc/python_api ; sphinx-build sphinx-in sphinx-out ; cd ../../
6
7
8 Submodules:
9
10 .. toctree::
11    :maxdepth: 1
12
13    bmesh.ops.rst
14    bmesh.types.rst
15    bmesh.utils.rst
16    bmesh.geometry.rst
17
18
19 Introduction
20 ------------
21
22 This API gives access the blenders internal mesh editing api, featuring geometry connectivity data and
23 access to editing operations such as split, separate, collapse and dissolve.
24
25 The features exposed closely follow the C API,
26 giving python access to the functions used by blenders own mesh editing tools.
27
28 For an overview of BMesh data types and how they reference each other see:
29 `BMesh Design Document <https://wiki.blender.org/index.php/Dev:Source/Modeling/BMesh/Design>`_ .
30
31
32 .. note::
33
34    **Disk** and **Radial** data is not exposed by the python api since this is for internal use only.
35
36
37 .. warning:: TODO items are...
38
39    * add access to BMesh **walkers**
40    * add custom-data manipulation functions add/remove/rename.
41
42
43 Example Script
44 --------------
45
46 .. literalinclude:: __/__/__/release/scripts/templates_py/bmesh_simple.py
47
48
49 Stand-Alone Module
50 ^^^^^^^^^^^^^^^^^^
51
52 The bmesh module is written to be standalone except for :mod:`mathutils`
53 which is used for vertex locations and normals.
54
55 The only other exception to this are when converting mesh data to and from :class:`bpy.types.Mesh`.
56
57
58 Mesh Access
59 -----------
60
61 There are 2 ways to access BMesh data, you can create a new BMesh by converting a mesh from
62 :class:`bpy.types.BlendData.meshes` or by accessing the current edit mode mesh.
63 see: :class:`bmesh.types.BMesh.from_mesh` and :mod:`bmesh.from_edit_mesh` respectively.
64
65 When explicitly converting from mesh data python **owns** the data, that is to say -
66 that the mesh only exists while python holds a reference to it,
67 and the script is responsible for putting it back into a mesh data-block when the edits are done.
68
69 Note that unlike :mod:`bpy`, a BMesh does not necessarily correspond to data in the currently open blend file,
70 a BMesh can be created, edited and freed without the user ever seeing or having access to it.
71 Unlike edit mode, the bmesh module can use multiple BMesh instances at once.
72
73 Take care when dealing with multiple BMesh instances since the mesh data can use a lot of memory, while a mesh that
74 python owns will be freed in when the script holds no references to it,
75 its good practice to call :class:`bmesh.types.BMesh.free` which will remove all the mesh data immediately and disable
76 further access.
77
78
79 EditMode Tessellation
80 ^^^^^^^^^^^^^^^^^^^^^
81
82 When writing scripts that operate on editmode data you will normally want to re-calculate the tessellation after
83 running the  script, this needs to be called explicitly.
84
85 The BMesh its self does not store the triangulated faces, they are stored in the :class:`bpy.types.Mesh`,
86 to refresh tessellation triangles call :class:`bpy.types.Mesh.calc_loop_triangles`.
87
88
89 CustomData Access
90 -----------------
91
92 BMesh has a unified way to access mesh attributes such as UV's vertex colors, shape keys, edge crease etc.
93
94 This works by having a **layers** property on bmesh data sequences to access the custom data layers which can then be
95 used to access the actual data on each vert/edge/face/loop.
96
97 Here are some examples ...
98
99 .. code-block:: python
100
101    uv_lay = bm.loops.layers.uv.active
102
103    for face in bm.faces:
104        for loop in face.loops:
105            uv = loop[uv_lay].uv
106            print("Loop UV: %f, %f" % uv[:])
107            vert = loop.vert
108            print("Loop Vert: (%f,%f,%f)" % vert.co[:])
109
110
111 .. code-block:: python
112
113    shape_lay = bm.verts.layers.shape["Key.001"]
114
115    for vert in bm.verts:
116        shape = vert[shape_lay]
117        print("Vert Shape: %f, %f, %f" % (shape.x, shape.y, shape.z))
118
119
120 .. code-block:: python
121
122    # in this example the active vertex group index is used,
123    # this is stored in the object, not the BMesh
124    group_index = obj.vertex_groups.active_index
125
126    # only ever one deform weight layer
127    dvert_lay = bm.verts.layers.deform.active
128
129    for vert in bm.verts:
130        dvert = vert[dvert_lay]
131
132        if group_index in dvert:
133            print("Weight %f" % dvert[group_index])
134        else:
135            print("Setting Weight")
136            dvert[group_index] = 0.5
137
138
139 Keeping a Correct State
140 -----------------------
141
142 When modeling in blender there are certain assumptions made about the state of the mesh.
143
144 * hidden geometry isn't selected.
145 * when an edge is selected, its vertices are selected too.
146 * when a face is selected, its edges and vertices are selected.
147 * duplicate edges / faces don't exist.
148 * faces have at least 3 vertices.
149
150 To give developers flexibility these conventions are not enforced,
151 however tools must leave the mesh in a valid state else other tools may behave incorrectly.
152
153 Any errors that arise from not following these conventions is considered a bug in the script,
154 not a bug in blender.
155
156
157 Selection / Flushing
158 ^^^^^^^^^^^^^^^^^^^^
159
160 As mentioned above, it is possible to create an invalid selection state
161 (by selecting a state and then de-selecting one of its vertices's for example), mostly the best way to solve this is to
162 flush the selection after performing a series of edits. this validates the selection state.
163
164
165 Module Functions
166 ----------------