==Python API==
[blender.git] / source / blender / python / api2_2x / doc / Mesh.py
1 # Blender.Mesh module and the Mesh PyType object
2
3 """
4 The Blender.Mesh submodule.
5
6 B{New}:
7  - L{transform()<Mesh.transform>}: apply transform matrix to mesh vertices
8  - L{getFromObject()<Mesh.getFromObject>}: get mesh data from other
9    geometry objects
10  - L{findEdges()<Mesh.findEdges>}: determine if and where edges exist in the
11    mesh's edge list
12  - delete methods for L{verts<MVertSeq.delete>}, L{edges<MEdgeSeq.delete>}
13    and L{faces<MFaceSeq.delete>}
14  - new experimental mesh tools:
15    L{mesh.fill()<Mesh.Mesh.fill>},
16    L{mesh.flipNormals()<Mesh.Mesh.flipNormals>},
17    L{mesh.recalcNormals()<Mesh.Mesh.recalcNormals>},
18    L{mesh.remDoubles()<Mesh.Mesh.remDoubles>},
19    L{mesh.smooth()<Mesh.Mesh.smooth>},
20    L{mesh.subdivide()<Mesh.Mesh.subdivide>},
21    L{mesh.toSphere()<Mesh.Mesh.toSphere>},
22    L{mesh.quadToTriangle()<Mesh.Mesh.quadToTriangle>},
23    L{mesh.triangleToQuad()<Mesh.Mesh.triangleToQuad>}
24  - methods for accessing and modifying vertex groups
25  - and if you're never used Mesh before, everything!
26
27 Mesh Data
28 =========
29
30 This module provides access to B{Mesh Data} objects in Blender.  It differs
31 from the NMesh module by allowing direct access to the actual Blender data, 
32 so that changes are done immediately without need to update or put the data
33 back into the original mesh.  The result is faster operations with less memory
34 usage.
35
36 Example::
37
38   import Blender
39   from Blender import Mesh, Material, Window
40
41   editmode = Window.EditMode()    # are we in edit mode?  If so ...
42   if editmode: Window.EditMode(0) # leave edit mode before getting the mesh
43
44   me = Mesh.Get("Plane")          # get the mesh data called "Plane"
45
46   if not me.materials:             # if there are no materials ...
47     newmat = Material.New()        # create one ...
48     me.materials=[newmat]          # and set the mesh's list of mats
49
50   print me.materials               # print the list of materials
51   mat = me.materials[0]            # grab the first material in the list
52   mat.R = 1.0                      # redefine its red component
53   for v in me.verts:               # loop the list of vertices
54     v.co[0] *= 2.5                 # multiply the coordinates
55     v.co[1] *= 5.0
56     v.co[2] *= 2.5
57
58   if editmode: Window.EditMode(1)  # optional, just being nice
59
60 @type Modes: readonly dictionary
61 @type FaceFlags: readonly dictionary
62 @type FaceModes: readonly dictionary
63 @type FaceTranspModes: readonly dictionary
64 @var Modes: The available mesh modes.
65     - NOVNORMALSFLIP - no flipping of vertex normals during render.
66     - TWOSIDED - double sided mesh.
67     - AUTOSMOOTH - turn auto smoothing of faces "on".
68     - SUBSURF - turn Catmull-Clark subdivision of surfaces "on".
69     - OPTIMAL - optimal drawing of edges when "SubSurf" is "on".
70 @var FaceFlags: The available *texture face* (uv face select mode) selection
71   flags.  Note: these refer to TexFace faces, available if nmesh.hasFaceUV()
72   returns true.
73     - SELECT - selected.
74     - HIDE - hidden.
75     - ACTIVE - the active face.
76 @var FaceModes: The available *texture face* modes. Note: these are only
77   meaningful if nmesh.hasFaceUV() returns true, since in Blender this info is
78   stored at the TexFace (TexFace button in Edit Mesh buttons) structure.
79     - ALL - set all modes at once.
80     - BILLBOARD - always orient after camera.
81     - HALO - halo face, always point to camera.
82     - DYNAMIC - respond to collisions.
83     - INVISIBLE - invisible face.
84     - LIGHT - dynamic lighting.
85     - OBCOL - use object color instead of vertex colors.
86     - SHADOW - shadow type.
87     - SHAREDVERT - apparently unused in Blender.
88     - SHAREDCOL - shared vertex colors (per vertex).
89     - TEX - has texture image.
90     - TILES - uses tiled image.
91     - TWOSIDE - two-sided face.
92 @var FaceTranspModes: The available face transparency modes. Note: these are
93   enumerated values (enums), they can't be combined (and'ed, or'ed, etc) like a bit vector.
94     - SOLID - draw solid.
95     - ADD - add to background (halo).
96     - ALPHA - draw with transparency.
97     - SUB - subtract from background.
98 @var EdgeFlags: The available edge flags.
99     - SELECT - selected.
100     - EDGEDRAW - edge is drawn out of edition mode.
101     - SEAM - edge is a seam for LSCM UV unwrapping
102     - FGON - edge is part of a F-Gon.
103 @type AssignModes: readonly dictionary.
104 @var AssignModes: The available vertex group assignment modes, used by 
105   L{mesh.assignVertsToGroup()<Mesh.Mesh.assignVertsToGroup>}.
106         - ADD: if the vertex in the list is not assigned to the group
107         already, this creates a new association between this vertex and the
108         group with the weight specified, otherwise the weight given is added to
109         the current weight of an existing association between the vertex and
110         group.
111         - SUBTRACT: will attempt to subtract the weight passed from a vertex
112         already associated with a group, else it does nothing.\n
113         - REPLACE: attempts to replace a weight with the new weight value
114         for an already associated vertex/group, else it does nothing. 
115 @type SelectModes: readonly dictionary.
116 @var SelectModes: The available edit select modes.
117         - VERTEX: vertex select mode.
118         - EDGE: edge select mode.
119         - FACE: face select mode.
120 """
121
122 AssignModes = {'REPLACE':1}
123
124 def Get(name=None):
125   """
126   Get the mesh data object called I{name} from Blender.
127   @type name: string
128   @param name: The name of the mesh data object.
129   @rtype: Mesh
130   @return: If a name is given, it returns either the requested mesh or None.
131     If no parameter is given, it returns all the meshs in the current scene.
132   """
133
134 def New(name='Mesh'):
135   """
136   Create a new mesh data object called I{name}.
137   @type name: string
138   @param name: The name of the mesh data object.
139   @rtype: Mesh
140   @return: a new Blender mesh.
141   """
142
143 def Mode(mode=0):
144   """
145   Get and/or set the selection modes for mesh editing.  These are the modes
146   visible in the 3D window when a mesh is in Edit Mode.
147   @type mode: int
148   @param mode: The name of the mesh data object.  See L{SelectModes} for values.
149   Modes can be combined.  If omitted, the selection mode is not changed.
150   @rtype: int
151   @return: the current selection mode.
152   @note: The selection mode is an attribute of the current scene.  If the
153   scene is changed, the selection mode may not be the same.
154   """
155
156 class MCol:
157   """
158   The MCol object
159   ===============
160     This object is four ints representing an RGBA color.
161   @ivar r: The Red component in [0, 255].
162   @type r: int
163   @ivar g: The Green component in [0, 255].
164   @type g: int
165   @ivar b: The Blue component in [0, 255].
166   @type b: int
167   @ivar a: The Alpha (transparency) component in [0, 255].
168   @type a: int
169   """
170
171 class MVert:
172   """
173   The MVert object
174   ================
175     This object holds mesh vertex data.
176   @ivar co: The vertex coordinates (x, y, z).
177   @type co: vector (WRAPPED DATA)
178   @ivar no: The vertex's unit normal vector (x, y, z).  Read-only.  B{Note}:
179     if vertex coordinates are changed, it may be necessary to use
180     L{Mesh.calcNormals()} to update the vertex normals.
181   @type no: vector
182   @ivar uvco: (MVerts only). The vertex texture "sticky" coordinates (x, y),
183     if present. 
184     Use L{Mesh.vertexUV} to test for presence before trying to access;
185     otherwise an exception will may be thrown.
186     (Sticky coordinates can be set when the object is in the Edit mode;
187     from the Editing Panel (F9), look under the "Mesh" properties for the 
188     "Sticky" button).  
189   @type uvco: vector (WRAPPED DATA)
190   @ivar index: (MVerts only). The vertex's index within the mesh.  Read-only.
191   @type index: int
192   @ivar sel: The vertex's selection state (selected=1).
193    B{Note}: a Mesh will return the selection state of the mesh when EditMode 
194    was last exited. A Python script operating in EditMode must exit EditMode 
195    before getting the current selection state of the mesh.
196   @type sel: int
197   @warn:  There are two kinds of UV texture coordinates in Blender: per vertex
198      ("sticky") and per face vertex (UV in L{MFace}).  In the first, there's
199      only one UV pair of coordinates for each vertex in the mesh.  In the
200      second, for each face it belongs to, a vertex can have different UV
201      coordinates.  This makes the per face option more flexible, since two
202      adjacent faces won't have to be mapped to a continuous region in an image:
203      each face can be independently mapped to any part of its texture.
204   """
205
206   def __init__(coord):
207     """
208     Create a new PVert object.  
209
210     @note: PVert-type objects are designed to be used for creating and
211     modifying a mesh's vertex list, but since they do not "wrap" any Blender
212     data there are some differences.  The B{index} and B{uvco} attributes 
213     are not defined for PVerts, and the B{no} attribute contains valid
214     data only if the PVert was created from an MVert (using a slice
215     operation on the mesh's vertex list.)  PVerts also cannot be used as an
216     argument to any method which expects data wrapping a Blender mesh, such
217     as L{MVertSeq.delete()}.
218
219     Example::
220       v = Blender.Mesh.MVert(1,0,0)
221       v = Blender.Mesh.MVert(Blender.Mathutils.Vector([1,0,0]))
222
223       m = Blender.Mesh.Get('Mesh')
224       vlist = m.verts[:]   # slice operation also returns PVerts
225
226     @type coord: three floats or a Vector object
227     @param coord: the coordinate values for the new vertex
228     @rtype: PVert
229     @return: a new PVert object
230
231     """
232
233 class MVertSeq:
234   """
235   The MVertSeq object
236   ===================
237     This object provides sequence and iterator access to the mesh's vertices.
238     Access and assignment of single items and slices are also supported.
239     When a single item in the vertex list is accessed, the operator[] returns
240     a MVert object which "wraps" the actual vertex in the mesh; changing any
241     of the vertex's attributes will immediately change the data in the mesh.
242     When a slice of the vertex list is accessed, however, the operator[]
243     returns a list of PVert objects which are copies of the mesh's vertex
244     data.  Changes to these objects have no effect on the mesh; they must be
245     assigned back to the mesh's vertex list.
246
247     Slice assignments cannot change the vertex list size.  The size of the
248     list being assigned must be the same as the specified slice; otherwise an
249     exception is thrown.
250
251     Example::
252       import Blender
253       from Blender import Mesh
254
255       me = Mesh.Get("Plane")          # get the mesh data called "Plane"
256       vert = me.verts[0]              # vert accesses actual mesh data
257       vert.co[0] += 2                 # change the vertex's X location
258       pvert = me.verts[-2:]           # pvert is COPY of mesh's last two verts
259       pvert[0].co[0] += 2             # change the vertex's X location
260       pvert[1].co[0] += 2             # change the vertex's X location
261       me.verts[-1] = pvert[1]         # put change to second vertex into mesh
262
263     @note: The mesh can be "cleared" by assigning B{None} to the mesh's vertex
264     list.  This does not delete the Blender mesh object, it only deletes all
265     the memory allocated to the mesh.  The result is equivalent to calling 
266     Mesh.New().  The intent is to allow users writing exporters to free memory
267     after it is used in a quick and simple way.
268
269     Example::
270       import Blender
271       from Blender import Mesh
272
273       me = Mesh.Get("Plane")          # get the mesh data called "Plane"
274       me.verts = None                 # delete all the mesh's attributes
275
276   """
277
278   def extend(coords):
279     """
280     Append one or more vertices to the mesh.  Unlike L{MEdgeSeq.extend()} and
281     L{MFaceSeq.extend()} no attempt is made to check for duplicate vertices in
282     the parameter list, or for vertices already in the mesh.
283
284     Example::
285       import Blender
286       from Blender import Mesh
287       from Blender.Mathutils import Vector
288
289       me = Mesh.Get("Plane")          # get the mesh data called "Plane"
290       me.verts.extend(1,1,1)          # add one vertex
291       l=[(.1,.1,.1),Vector([2,2,.5])]
292       me.verts.extend(l)              # add multiple vertices
293
294     @type coords: sequences(s) of floats or vectors
295     @param coords: coords can be
296        - a sequence of three floats,
297        - a 3D vector, or
298        - a sequence (list or tuple) of either of the above.
299     """
300
301   def delete(verts):
302     """
303     Deletes one or more vertices from the mesh.  Any edge or face which
304     uses the specified vertices are also deleted.
305
306     @type verts: multiple ints or MVerts
307     @param verts: can be
308        - a single MVert belonging to the mesh (B{note:} will not work with
309          PVerts)
310        - a single integer, specifying an index into the mesh's vertex list
311        - a sequence (list or tuple) containing two or more of either of
312          the above.
313     """
314
315   def selected():
316     """
317     Get selected vertices.
318     @return: a list of the indices for all vertices selected in edit mode.
319     @rtype: list of ints
320     """
321
322 class MEdge:
323   """
324   The MEdge object
325   ================
326     This object holds mesh edge data.
327   @ivar v1: The first vertex of the edge.
328   @type v1: MVert
329   @ivar v2: The second vertex of the edge.
330   @type v2: MVert
331   @ivar crease: The crease value of the edge. It is in the range [0,255].
332   @type crease: int
333   @ivar flag: The bitfield describing edge properties. See L{EdgeFlags}.
334   @type flag: int
335   @ivar index: The edge's index within the mesh.  Read-only.
336   @type index: int
337   """
338
339   def __iter__():
340     """
341     Iterator for MEdge.  It iterates over the MVerts of the edge, returning
342     v1 then v2.
343     @return: one of the edge's vertices
344     @rtype: MVert
345     """
346
347 class MEdgeSeq:
348   """
349   The MEdgeSeq object
350   ===================
351     This object provides sequence and iterator access to the mesh's edges.
352   """
353
354   def extend(vertseq):
355     """
356     Add one or more edges to the mesh.  Edges which already exist in the 
357     mesh are ignored.  If three or four verts are specified in any tuple,
358     an edge is also created between the first and last vertices (this is
359     useful when adding faces).
360
361     Example::
362       import Blender
363       from Blender import Mesh
364
365       me = Mesh.Get("Plane")          # get the mesh data called "Plane"
366       v = me.verts                    # get vertices
367       if len(v) >= 6:                 # if there are enough vertices...
368         me.edges.extend(v[0],v[1])    #   add a single edge
369         l=[(v[1],v[2],v[3]),[v[0],v[2],v[4],v[5]]]
370         me.edges.extend(l)            #   add multiple edges
371
372     @type vertseq: sequence(s) of MVerts
373     @param vertseq: either two to four MVerts, or sequence (list or tuple) 
374     of sequences each containing two to four MVerts.
375     """
376
377   def delete(edges):
378     """
379     Deletes one or more edges from the mesh.  In addition, also delete:
380       - any faces which uses the specified edge(s)
381       - any "orphan" vertices (belonging only to specified edge(s))
382
383     @type edges: multiple ints or MEdges
384     @param edges: can be
385        - a single MEdge belonging to the mesh
386        - a single integer, specifying an index into the mesh's edge list
387        - a sequence (list or tuple) containing two or more of either of
388          the above.
389     """
390
391   def selected():
392     """
393     Get selected edges.
394     Selected edges are those for which both vertices are selected.
395     @return: a list of the indices for all edges selected in edit mode.
396     @rtype: list of ints
397     """
398
399 class MFace:
400   """
401   The MFace object
402   ================
403   This object holds mesh face data.
404
405   Example::
406    import Blender
407    from Blender import Mesh, Window
408
409    in_emode = Window.EditMode()
410    if in_emode: Window.EditMode(0)
411
412    me = Mesh.Get("Mesh")
413    faces = me.faces
414
415    ## Example for editmode faces selection:
416    selected_faces = []
417    for f in faces:
418      if f.sel:
419        selected_faces.append(f)
420    # ... unselect selected and select all the others:
421    for f in faces:
422      f.sel = 1 - f.sel # 1 becomes 0, 0 becomes 1
423
424    ## Example for UV textured faces selection:
425    selected_faces = []
426    SEL = Mesh.FaceFlags['SELECT']
427    # get selected faces:
428    for f in faces:
429      if f.flag & SEL:
430        selected_faces.append(f)
431    # ... unselect selected and select all the others:
432    for f in faces:
433      if f.flag & SEL:
434        f.flag &= ~SEL # unselect these
435      else:
436        f.flag |= SEL # and select these
437
438    if in_emode: Window.EditMode(1)
439    Blender.Redraw()
440
441   @ivar verts: The face's vertices.  Each face has 3 or 4 vertices.
442   @type verts: list of MVerts
443   @ivar v: Same as L{verts}.  This attribute is only for compatibility with
444       NMesh scripts and will probably be deprecated in the future.
445   @ivar sel: The face's B{edit mode} selection state (selected=1).
446       This is not the same as the selection state of
447       the textured faces (see L{flag}).
448   @type sel: int
449   @ivar hide: The face's B{edit mode} visibility state (hidden=1).
450       This is not the same as the visibility state of
451       the textured faces (see L{flag}).
452   @type hide: int
453   @ivar smooth: If set, the vertex normals are averaged to make this
454      face look smooth.  (This is the same as choosing "Set Smooth" in the 
455      Editing Panel (F9) under "Link and Material" properties).
456   @type smooth: int
457   @ivar col: The face's vertex colors, if defined.  Each vertex has its own
458      color.
459      Will throw an exception if the mesh does not have UV faces or vertex
460      colors; use L{Mesh.faceUV} and L{Mesh.vertexColors} to test.  B{Note}:
461      if a mesh has i{both} UV faces and vertex colors, the colors stored in
462      the UV faces will be used here. 
463   @type col: sequence of MCols
464   @ivar mat: The face's index into the mesh's materials
465       list.  It is in the range [0,15].
466   @type mat: int
467   @ivar image: The Image used as a texture for this face.
468       Will throw an exception if the mesh does not have UV faces; use
469       L{Mesh.faceUV} to test.
470   @type image: Image
471   @ivar mode: The texture mode bitfield (see L{FaceModes}).
472       Will throw an exception if the mesh does not have UV faces; use
473       L{Mesh.faceUV} to test.
474   @type mode: int
475   @ivar index: The face's index within the mesh.  Read-only.
476   @type index: int
477
478   @ivar flag: The face's B{texture mode} flags; indicates the selection, 
479       active , and visibility states of a textured face (see
480       L{FaceFlags} for values).
481       This is not the same as the selection or visibility states of
482       the faces in edit mode (see L{sel} and L{hide}).
483       To set the active face, use
484       the L{Mesh.activeFace} attribute instead.
485       Will throw an exception if the mesh does not have UV faces; use
486       L{Mesh.faceUV} to test.
487
488   @ivar transp: Transparency mode.  It is one of the values in 
489       L{FaceTranspModes}).
490       Will throw an exception if the mesh does not have UV faces; use
491       L{Mesh.faceUV} to test.
492   @type transp: int
493
494   @ivar uv: The face's UV coordinates.  Each vertex has its own UV coordinate.
495       Will throw an exception if the mesh does not have UV faces; use
496       L{Mesh.faceUV} to test.
497   @type uv: list of vectors (WRAPPED DATA)
498   @ivar uvSel: The face's UV coordinates seletion state; a 1 indicates the
499       vertex is selected.  Each vertex has its own UV coordinate select state
500       (this is not the same as the vertex's edit mode selection state).
501       Will throw an exception if the mesh does not have UV faces; use
502       L{Mesh.faceUV} to test.
503   @type uvSel: list of ints
504   @ivar no: The face's normal vector (x, y, z).  Read-only.
505   @type no: vector
506   @note: there are regular faces and textured faces in Blender, both currently
507     with their own selection and visibility states, due to a mix of old and new
508     code.  To (un)select or (un)hide regular faces (visible in EditMode), use
509     L{MFace.sel} and L{MFace.hide} attributes.  For textured faces (UV Face 
510     Select and Paint modes in Blender) use the L{MFace.flag} attribute.
511     Check the example above and note L{Window.EditMode}.
512   @note: Assigning UV textures to mesh faces in Blender works like this:
513     1. Select your mesh.
514     2. Enter face select mode (press f) and select at least some face(s).
515     3. In the UV/Image Editor window, load / select an image.
516     4. Play in both windows (better split the screen to see both at the same
517        time) until the UV coordinates are where you want them.  Hint: in the
518        3D window, the 'u' key opens a menu of default UV choices and the 'r'
519        key lets you rotate the UV coords.
520     5. Leave face select mode (press f).
521   """
522
523   def __iter__():
524     """
525     Iterator for MVert.  It iterates over the MVerts of the face, returning
526     v1, v2, v3 (and optionally v4);
527     @return: one of the face's vertices
528     @rtype: MVert
529     """
530
531 class MFaceSeq:
532   """
533   The MFaceSeq object
534   ===================
535     This object provides sequence and iterator access to the mesh's faces.
536   """
537
538   def extend(vertseq):
539     """
540     Add one or more faces to the mesh.  Faces which already exist in the 
541     mesh are ignored.  Sequences of two vertices are accepted, but no face
542     will be created.
543
544     Example::
545       import Blender
546       from Blender import Mesh
547
548       me = Mesh.Get("Plane")          # get the mesh data called "Plane"
549       v = me.verts                    # get vertices
550       if len(v) >= 6:                 # if there are enough vertices...
551         me.faces.extend(v[1],v[2],v[3]) #   add a single edge
552         l=[(v[0],v[1]),[v[0],v[2],v[4],v[5]]]
553         me.faces.extend(l)            #   add another face
554
555     @type vertseq: sequence(s) of MVerts
556     @param vertseq: either two to four MVerts, or sequence (list or tuple) 
557     of sequences each containing two to four MVerts.
558     """
559
560   def delete(deledges, faces):
561     """
562     Deletes one or more faces (and optionally the edges associated with
563     the face(s)) from the mesh.  
564
565     @type deledges: int
566     @param deledges: controls whether just the faces (deledges=0)
567     or the faces and edges (deledges=1) are deleted.  These correspond to the
568     "Only Faces" and "Edges & Faces" options in the Edit Mode pop-up menu
569     @type faces: multiple ints or MFaces
570     @param faces: a sequence (list or tuple) containing one or more of:
571        - an MEdge belonging to the mesh
572        - a integer, specifying an index into the mesh's face list
573     """
574
575   def selected():
576     """
577     Get selected faces.
578     mode.
579     @return: a list of the indices for all faces selected in edit mode.
580     @rtype: list of ints
581     """
582
583 class Mesh:
584   """
585   The Mesh Data object
586   ====================
587     This object gives access to mesh data in Blender.
588   @note: the verts, edges and faces attributes are implemented as sequences.
589   The operator[] and len() are defined for these sequences.  You cannot
590   assign to an item in the sequence, but you can assign to most of the
591   attributes of individual items.
592   @ivar edges: The mesh's edges.
593   @type edges: sequence of MEdges
594   @ivar faces: The mesh's faces.
595   @type faces: sequence of MFaces
596   @ivar verts: The mesh's vertices.
597   @type verts: sequence of MVerts
598
599   @ivar materials: The mesh's materials.  Each mesh can reference up to
600     16 materials.  Empty slots in the mesh's list are represented by B{None}.
601     B{Note}: L{Object.colbits<Object.Object.colbits>} needs to be set correctly
602     for each object in order for these materials to be used instead of
603     the object's materials.
604     B{Note}: Making the material list shorter does not change the faces material indicies,
605     take care when using the faces material indices to reference a material in the materials list.
606   @type materials: list of Materials
607   @ivar degr: The max angle for auto smoothing in [1,80].  
608   @type degr: int
609   @ivar maxSmoothAngle: Same as L{degr}.  This attribute is only for
610     compatibility with NMesh scripts and will probably be deprecated in 
611     the future.
612   @ivar mode: The mesh's mode bitfield.  See L{Modes}.
613   @type mode: int
614
615   @ivar name: The Mesh name.  It's common to use this field to store extra
616      data about the mesh (to be exported to another program, for example).
617   @type name: str
618   @ivar subDivLevels: The [display, rendering] subdivision levels in [1, 6].
619   @type subDivLevels: list of 2 ints
620   @ivar users: The number of Objects using (linked to) this mesh.
621   @type users: int
622
623   @ivar faceUV: The mesh contains UV-mapped textured faces.  Enabling faceUV
624     does not initialize the face colors like the Blender UI does; this must
625     be done in the script.  B{Note}: if faceUV is set, L{vertexColors} cannot
626     be set.  Furthermore, if vertexColors is already set when faceUV is set,
627     vertexColors is cleared.  This is because the vertex color information
628     is stored with UV faces, so enabling faceUV implies enabling vertexColors.
629     In addition, faceUV cannot be set when the mesh has no faces defined
630     (this is the same behavior as the UI).  Attempting to do so will throw
631     a RuntimeError exception.
632   @type faceUV: bool
633   @ivar vertexColors: The mesh contains vertex colors.  See L{faceUV} for the
634     use of vertex colors when UV-mapped texture faces are enabled.
635   @type vertexColors: bool
636   @ivar vertexUV: The mesh contains "sticky" per-vertex UV coordinates.
637   @type vertexUV: bool
638   @ivar activeFace: Index of the mesh's active face in UV Face Select and
639     Paint modes.  Only one face can be active at a time.  Note that this is
640     independent of the selected faces in Face Select and Edit modes.
641     Will throw an exception if the mesh does not have UV faces; use
642     L{faceUV} to test.
643   @type activeFace: int
644   """
645
646   def getFromObject(name,cage=0):
647     """
648     Replace the mesh's existing data with the raw mesh data from a Blender
649     Object.  This method supports all the geometry based objects (mesh, text,
650     curve, surface, and meta).  If the object has modifiers, they will be
651     applied before to the object before extracting the vertex data unless
652     the B{cage} parameter is 1.
653     @note: The mesh coordinates are in I{local space}, not the world space of
654     its object.  For world space vertex coordinates, each vertex location must
655     be multiplied by the object's 4x4 transform matrix (see L{transform}).
656     @note: The objects materials will not be copied into the existing mesh,
657     however the face material indices will match the material list of the original data.
658     @type name: string
659     @param name: name of the Blender object which contains the geometry data.
660     @type cage: int
661     @param cage: determines whether the original vertices or derived vertices
662     (for objects with modifiers) are used.  The default is derived vertices.
663     """
664
665   def calcNormals():
666     """
667     Recalculates the vertex normals using face data.
668     """
669
670   def transform(matrix, recalc_normals = False):
671     """
672     Transforms the mesh by the specified 4x4 matrix (such as returned by
673     L{Object.Object.getMatrix}).  The matrix should be invertible.
674     Ideal usage for this is exporting to an external file where
675     global vertex locations are required for each object.
676     Sometimes external renderers or file formats do not use vertex normals.
677     In this case, you can skip transforming the vertex normals by leaving
678     the optional parameter recalc_normals as False or 0 (the default value).
679
680     Example::
681      # This script outputs deformed meshes worldspace vertex locations
682      # for a selected object without changing the object
683      import Blender
684      from Blender import Mesh, Object
685      
686      ob = Object.GetSelected()[0] # Get the first selected object
687      me = Mesh.New()              # Create a new mesh
688      me.getFromObject(ob.name)    # Get the object's mesh data
689      verts = me.verts[:]          # Save a copy of the vertices
690      me.transform(ob.matrix)      # Convert verts to world space
691      for v in me.verts:
692        print 'worldspace vert', v.co
693      me.verts = verts             # Restore the original verts
694     
695     @type matrix: Py_Matrix
696     @param matrix: 4x4 Matrix which can contain location, scale and rotation. 
697     @type recalc_normals: int
698     @param recalc_normals: if True or 1, also transform vertex normals.
699     @warn: unlike L{NMesh.transform()<NMesh.NMesh.transform>}, this method
700     I{will immediately modify the mesh data} when it is used.  If you
701     transform the mesh using the object's matrix to get the vertices'
702     world positions, the result will be a "double transform".  To avoid
703     this you either need to set the object's matrix to the identity
704     matrix, perform the inverse transform after outputting the transformed
705     vertices, or make a copy of the vertices prior to using this method
706     and restore them after outputting the transformed vertices (as shown
707     in the example).
708     """
709
710   def vertexShade(object):
711     """
712     Colors vertices based on the current lighting setup, like when there
713     are no vertex colors and no textured faces and a user enters Vertex Paint
714     Mode in Blender (only lamps in visible layers account).  An exception is
715     thrown if called while in EditMode.
716     @type object: Object
717     @param object: The Blender Object linked to the mesh.
718     """
719
720   def update():
721     """
722     Update display lists after changes to mesh.  B{Note}: with changes taking
723     place for using a directed acyclic graph (DAG) for scene and object
724     updating, this method may be only temporary and may be removed in future
725     releases.
726     """
727
728   def findEdges(edges):
729     """
730     Quickly search for the location of an edges.  
731     @type edges: sequence(s) of ints or MVerts
732     @param edges: can be tuples of MVerts or integer indexes (B{note:} will
733        not work with PVerts) or a sequence (list or tuple) containing two or
734        more sequences.
735     @rtype: int, None or list
736     @return: if an edge is found, its index is returned; otherwise None is
737     returned.  If a sequence of edges is passed, a list is returned.
738     """
739
740   def addVertGroup(group):
741     """
742     Add a named and empty vertex (deform) group to the object this nmesh is
743     linked to.  The mesh must first be linked to an object (with object.link()
744     or object.getData() ) so the method knows which object to update.  
745     This is because vertex groups in Blender are stored in I{the object} --
746     not in the mesh, which may be linked to more than one object. 
747     @type group: string
748     @param group: the name for the new group.
749     """
750
751   def removeVertGroup(group):
752     """
753     Remove a named vertex (deform) group from the object linked to this mesh.
754     All vertices assigned to the group will be removed (just from the group,
755     not deleted from the mesh), if any. If this mesh was newly created, it
756     must first be linked to an object (read the comment in L{addVertGroup} for
757     more info).
758     @type group: string
759     @param group: the name of a vertex group.
760     """
761
762   def assignVertsToGroup(group, vertList, weight, assignmode = AssignModes['REPLACE']):
763     """
764     Adds an array (a Python list) of vertex points to a named vertex group
765     associated with a mesh. The vertex list is a list of vertex indices from
766     the mesh. You should assign vertex points to groups only when the mesh has
767     all its vertex points added to it and is already linked to an object.
768
769     I{B{Example:}}
770     The example here adds a new set of vertex indices to a sphere primitive::
771      import Blender
772      sphere = Blender.Object.Get('Sphere')
773      replace = Blender.Mesh.AssignModes.REPLACE
774      mesh = sphere.getData(mesh=True)
775      mesh.addVertGroup('firstGroup')
776      vertList = []
777      for x in range(300):
778          if x % 3 == 0:
779              vertList.append(x)
780      mesh.assignVertsToGroup('firstGroup', vertList, 0.5, replace)
781
782     @type group: string
783     @param group: the name of the group.
784     @type vertList: list of ints
785     @param vertList: a list of vertex indices.
786     @type weight: float
787     @param weight: the deform weight for (which means: the amount of influence
788         the group has over) the given vertices. It should be in the range
789         [0.0, 1.0]. If weight <= 0, the given vertices are removed from the
790         group.  If weight > 1, it is clamped.
791     @type assignmode: module constant
792     @param assignmode: Three choices: REPLACE, ADD or SUBTRACT. 
793         See L{AssignModes} for a complete description.
794        """
795
796   def removeVertsFromGroup(group, vertList = None):
797     """
798     Remove a list of vertices from the given group.  If this nmesh was newly
799     created, it must first be linked to an object (check L{addVertGroup}).
800     @type group: string
801     @param group: the name of a vertex group
802     @type vertList: list of ints
803     @param vertList: a list of vertex indices to be removed from I{group}.
804         If None, all vertices are removed -- the group is emptied.
805     """
806
807   def getVertsFromGroup(group, weightsFlag = 0, vertList = None):
808     """
809     Return a list of vertex indices associated with the passed group. This
810     method can be used to test whether a vertex index is part of a group and
811     if so, what its weight is. 
812
813     I{B{Example:}}
814     Append this to the example from L{assignVertsToGroup}::
815      # ...
816      print "Vertex indices from group %s :" % groupName
817      print mesh.getVertsFromGroup('firstGroup')
818      print "Again, with weights:"
819      print mesh.getVertsFromGroup('firstGroup',1)
820      print "Again, with weights and restricted to the given indices:"
821      print mesh.getVertsFromGroup('firstGroup',1,[1,2,3,4,5,6])     
822
823     @type group: string
824     @param group: the group name.
825     @type weightsFlag: bool
826     @param weightsFlag: if 1, the weight is returned along with the index. 
827     @type vertList: list of ints
828     @param vertList: if given, only those vertex points that are both in the
829         list and group passed in are returned.
830     """
831
832   def renameVertGroup(groupName, newName):
833     """
834     Renames a vertex group.
835     @type groupName: string
836     @param groupName: the vertex group name to be renamed.
837     @type newName: string
838     @param newName: the name to replace the old name.
839     """
840
841   def getVertGroupNames():
842     """
843     Return a list of all vertex group names.
844     @rtype: list of strings
845     @return: returns a list of strings representing all vertex group
846     associated with the mesh's object
847     """
848
849   def smooth():
850     """
851     Flattens angle of selected faces. Experimental mesh tool.
852     An exception is thrown if called while in EditMode.
853     """
854
855   def flipNormals():
856     """
857     Toggles the direction of selected face's normals. Experimental mesh tool.
858     An exception is thrown if called while in EditMode.
859     """
860
861   def toSphere():
862     """
863     Moves selected vertices outward in a spherical shape. Experimental mesh
864     tool.
865     An exception is thrown if called while in EditMode.
866     """
867
868   def fill():
869     """
870     Scan fill a closed selected edge loop. Experimental mesh tool.
871     An exception is thrown if called while in EditMode.
872     """
873
874   def triangleToQuad():
875     """
876     Convert selected triangles to quads. Experimental mesh tool.
877     An exception is thrown if called while in EditMode.
878     """
879
880   def quadToTriangle(mode=0):
881     """
882     Convert selected quads to triangles. Experimental mesh tool.
883     An exception is thrown if called while in EditMode.
884     @type mode: int
885     @param mode: specifies whether a to add the new edge between the
886     closest (=0) or farthest(=1) vertices.
887     """
888
889   def subdivide(beauty=0):
890     """
891     Subdivide selected edges in a mesh. Experimental mesh tool.
892     An exception is thrown if called while in EditMode.
893     @type beauty: int
894     @param beauty: specifies whether a "beauty" subdivide should be
895     enabled (disabled is default).  Value must be in the range [0,1].
896     """
897
898   def remDoubles(limit):
899     """
900     Removes duplicates from selected vertices. Experimental mesh tool.
901     An exception is thrown if called while in EditMode.
902     @type limit: float
903     @param limit: specifies the maximum distance considered for vertices
904     to be "doubles".  Value is clamped to the range [0.0,1.0].
905     @rtype: int
906     @return: the number of vertices deleted
907     """
908
909   def recalcNormals(direction=0):
910     """
911     Recalculates inside or outside normals for selected faces. Experimental
912     mesh tool.
913     An exception is thrown if called while in EditMode.
914     @type direction: int
915     @param direction: specifies outward (0) or inward (1) normals.  Outward
916     is the default.  Value must be in the range [0,1].
917     """