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