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