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