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