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