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