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