Updating build systems: folder release/bpydata/ moved to release/scripts/bpydata/
[blender.git] / source / blender / python / api2_2x / doc / NMesh.py
1 # Blender.NMesh module and the NMesh PyType object
2
3 """
4 The Blender.NMesh submodule.
5
6 B{New}: edges class (L{NMEdge}) and nmesh methods (L{NMesh.addEdge},
7 L{NMesh.addEdgesData}, etc.); new optional arguments to L{NMesh.update};
8 L{NMesh.transform}.
9
10 Mesh Data
11 =========
12
13 This module provides access to B{Mesh Data} objects in Blender.
14
15 Example::
16
17   import Blender
18   from Blender import NMesh, Material, Window
19
20   editmode = Window.EditMode()    # are we in edit mode?  If so ...
21   if editmode: Window.EditMode(0) # leave edit mode before getting the mesh
22
23   me = NMesh.GetRaw("Plane")       # get the mesh data called "Plane"
24
25   if not me.materials:             # if there are no materials ...
26     newmat = Material.New()        # create one ...
27     me.materials.append(newmat)    # and append it to the mesh's list of mats
28
29   print me.materials               # print the list of materials
30   mat = me.materials[0]            # grab the first material in the list
31   mat.R = 1.0                      # redefine its red component
32   for v in me.verts:               # loop the list of vertices
33     v.co[0] *= 2.5                 # multiply the coordinates
34     v.co[1] *= 5.0
35     v.co[2] *= 2.5
36   me.update()                      # update the real mesh in Blender
37
38   if editmode: Window.EditMode(1)  # optional, just being nice
39
40 @type Modes: readonly dictionary
41 @type FaceFlags: readonly dictionary
42 @type FaceModes: readonly dictionary
43 @type FaceTranspModes: readonly dictionary
44 @var Modes: The available mesh modes.
45     - NOVNORMALSFLIP - no flipping of vertex normals during render.
46     - TWOSIDED - double sided mesh.
47     - AUTOSMOOTH - turn auto smoothing of faces "on".
48     - SUBSURF - turn Catmull-Clark subdivision of surfaces "on".
49     - OPTIMAL - optimal drawing of edges when "SubSurf" is "on".
50 @var FaceFlags: The available *texture face* (uv face select mode) selection
51   flags.  Note: these refer to TexFace faces, available if nmesh.hasFaceUV()
52   returns true.
53     - SELECT - selected.
54     - HIDE - hidden.
55     - ACTIVE - the active face.
56 @var FaceModes: The available *texture face* modes. Note: these are only
57   meaningful if nmesh.hasFaceUV() returns true, since in Blender this info is
58   stored at the TexFace (TexFace button in Edit Mesh buttons) structure.
59     - ALL - set all modes at once.
60     - BILLBOARD - always orient after camera.
61     - HALO - halo face, always point to camera.
62     - DYNAMIC - respond to collisions.
63     - INVISIBLE - invisible face.
64     - LIGHT - dynamic lighting.
65     - OBCOL - use object color instead of vertex colors.
66     - SHADOW - shadow type.
67     - SHAREDVERT - apparently unused in Blender.
68     - SHAREDCOL - shared vertex colors (per vertex).
69     - TEX - has texture image.
70     - TILES - uses tiled image.
71     - TWOSIDE - two-sided face.
72 @var FaceTranspModes: The available face transparency modes. Note: these are
73   ENUMS, they can't be combined (and'ed, or'ed, etc) like a bit vector.
74     - SOLID - draw solid.
75     - ADD - add to background (halo).
76     - ALPHA - draw with transparency.
77     - SUB - subtract from background.
78 @var EdgeFlags: The available edge flags.
79     - SELECT - selected.
80     - EDGEDRAW - edge is drawn out of edition mode.
81     - SEAM - edge is a seam for LSCM UV unwrapping
82     - FGON - edge is part of a F-Gon.
83 """
84
85 def Col(col = [255, 255, 255, 255]):
86   """
87   Get a new mesh rgba color.
88   @type col: list
89   @param col: A list [red, green, blue, alpha] of integer values in [0, 255].
90   @rtype: NMCol
91   @return:  A new NMCol (mesh rgba color) object.
92   """
93
94 def Vert(x = 0, y = 0, z = 0):
95   """
96   Get a new vertex object.
97   @type x: float
98   @type y: float
99   @type z: float
100   @param x: The x coordinate of the vertex.
101   @param y: The y coordinate of the vertex.
102   @param z: The z coordinate of the vertex.
103   @rtype: NMVert
104   @return: A new NMVert object.
105   """
106
107 def Face(vertexList = None):
108   """
109   Get a new face object.
110   @type vertexList: list
111   @param vertexList: A list of B{up to 4} NMVerts (mesh vertex
112       objects).
113   @rtype: NMFace
114   @return: A new NMFace object.
115   """
116
117 def New(name = 'Mesh'):
118   """
119   Create a new mesh object.
120   @type name: string
121   @param name: An optional name for the created mesh.
122   rtype: NMesh
123   @return: A new (B{empty}) NMesh object.
124   """
125
126 def GetRaw(name = None):
127   """
128   Get the mesh data object called I{name} from Blender.
129   @type name: string
130   @param name: The name of the mesh data object.
131   @rtype: NMesh
132   @return: It depends on the 'name' parameter:
133       - (name) - The NMesh wrapper of the mesh called I{name},
134         None if not found.
135       - () - A new (empty) NMesh object.
136   """
137
138 def GetRawFromObject(name):
139   """
140   Get the raw mesh data object from the Object in Blender called I{name}.\n
141   Note: The mesh coordinates are in local space, not the world space of its Object.\n
142   For world space vertex coordinates, each vertex location must be multiplied by the object's 4x4 matrix.
143   @type name: string
144   @param name: The name of an Object of type "Mesh".
145   @rtype: NMesh
146   @return: The NMesh wrapper of the mesh data from the Object called I{name}.
147   @note: For "subsurfed" meshes, it's the B{display} level of subdivision that
148       matters, the rendering one is only processed at the rendering pre-stage
149       and is not available for scripts.  This is not a problem at all, since
150       you can get and set the subdivision levels via scripting, too (see
151       L{NMesh.getSubDivLevels}, L{NMesh.setSubDivLevels}).
152   @warn: This function gets I{deformed} mesh data, already modified for
153       displaying (think "display list").  It also doesn't let you overwrite the
154       original mesh in Blender, so if you try to update it, a new mesh will
155       be created.
156   """
157
158 def PutRaw(nmesh, name = None, recalc_normals = 1, store_edges = 0):
159   """
160   Put a BPython NMesh object as a mesh data object in Blender.
161   @note: if there is already a mesh with the given 'name', its contents are
162   freed and the new data is put in it.  Also, if this mesh is not linked to any
163   object, a new object for it is created.  Reminder: in Blender an object is
164   composed of the base object and linked object data (mesh, metaball, camera,
165   etc. etc).
166   @type nmesh: NMesh
167   @type name: string
168   @type recalc_normals: int
169   @type store_edges: int
170   @param name: The name of the mesh data object in Blender which will receive
171      this nmesh data.  It can be an existing mesh data object or a new one.
172   @param recalc_normals: If non-zero, the vertex normals for the mesh will
173      be recalculated.
174   @param store_edges: if non-zero, the edges data are stored
175   @rtype: None or Object
176   @return: It depends on the 'name' parameter:
177       - I{name} refers to an existing mesh data obj already linked to an
178            object: return None.
179       - I{name} refers to a new mesh data obj or an unlinked (no users) one:
180            return the created Blender Object wrapper.
181   """
182
183 class NMCol:
184   """
185   The NMCol object
186   ================
187     This object is a list of ints: [r, g, b, a] representing an
188     rgba color.
189   @cvar r: The Red component in [0, 255].
190   @cvar g: The Green component in [0, 255].
191   @cvar b: The Blue component in [0, 255].
192   @cvar a: The Alpha (transparency) component in [0, 255].
193   """
194
195 class NMVert:
196   """
197   The NMVert object
198   =================
199     This object holds mesh vertex data.
200   @type co: 3D Vector object.
201   @cvar co: The vertex coordinates (x, y, z).
202   @type no: 3D Vector object. (unit length)
203   @cvar no: The vertex normal vector (x, y, z).
204   @type uvco: 3D Vector object.
205   @cvar uvco: The vertex texture "sticky" coordinates. The Z value of the Vector is ignored.
206   @type index: int
207   @cvar index: The vertex index, if owned by a mesh.
208   @type sel: int
209   @cvar sel: The selection state (selected:1, unselected:0) of this vertex.\n
210   Note: An NMesh will return the selection state of the mesh when EditMod was last exited. A python script operating in EditMode must exit edit mode, before getting the current selection state of the mesh.
211   @warn:  There are two kinds of uv texture coordinates in Blender: per vertex
212      ("sticky") and per face vertex (uv in L{NMFace}).  In the first, there's
213      only one uv pair of coordinates for each vertex in the mesh.  In the
214      second, for each face it belongs to, a vertex can have different uv
215      coordinates.  This makes the per face option more flexible, since two
216      adjacent faces won't have to be mapped to a continuous region in an image:
217      each face can be independently mapped to any part of its texture.
218   """
219
220 class NMEdge:
221   """
222   The NMEdge object
223   =================
224     This object holds mesh edge data.
225   @type v1: NMVert
226   @cvar v1: The first vertex of the edge.
227   @type v2: NMVert
228   @cvar v2: The second vertex of the edge.
229   @type crease: int
230   @cvar crease: The crease value of the edge. It is in the range [0,255].
231   @type flag: int
232   @cvar flag: The bitmask describing edge properties. See L{NMesh.EdgeFlags<EdgeFlags>}.
233   """
234
235 class NMFace:
236   """
237   The NMFace object
238   =================
239   This object holds mesh face data.
240
241   Example::
242    import Blender
243    from Blender import NMesh, Window
244
245    in_emode = Window.EditMode()
246    if in_emode: Window.EditMode(0)
247
248    me = NMesh.GetRaw("Mesh")
249    faces = me.faces
250
251    ## Example for editmode faces selection:
252    selected_faces = []
253    for f in faces:
254      if f.sel:
255        selected_faces.append(f)
256    # ... unselect selected and select all the others:
257    for f in faces:
258      f.sel = 1 - f.sel # 1 becomes 0, 0 becomes 1
259
260    ## Example for uv textured faces selection:
261    selected_faces = []
262    SEL = NMesh.FaceFlags['SELECT']
263    # get selected faces:
264    for f in faces:
265      if f.flag & SEL:
266        selected_faces.append(f)
267    # ... unselect selected and select all the others:
268    for f in faces:
269      if f.flag & SEL:
270        f.flag &=~SEL # unselect these
271      else: f.flag |= SEL # and select these
272
273    me.update()
274    if in_emode: Window.EditMode(1)
275    Blender.Redraw()
276
277   @type v: list
278   @cvar v: The list of face vertices (B{up to 4}).
279   @type sel: bool
280   @cvar sel: The selection state (1: selected, 0: unselected) of this NMesh's
281       faces *in edit mode*.  This is not the same as the selection state of
282       the textured faces (see L{NMesh.NMFace.flag}).
283   @type hide: bool
284   @cvar hide: The visibility state (1: hidden, 0: visible) of this NMesh's
285       faces *in edit mode*.  This is not the same as the visibility state of
286       the textured faces (see L{NMesh.NMFace.flag}).
287   @cvar col: The list of vertex colours.
288   @cvar mat: Same as I{materialIndex} below.
289   @cvar materialIndex: The index of this face's material in its NMesh materials
290       list.
291   @cvar smooth: If non-zero, the vertex normals are averaged to make this
292      face look smooth.
293   @cvar image: The Image used as a texture for this face.
294   @cvar mode: The display mode (see L{Mesh.FaceModes<FaceModes>})
295   @cvar flag: Bit vector specifying selection / visibility flags for uv
296      textured faces (visible in Face Select mode, see
297      L{NMesh.FaceFlags<FaceFlags>}).
298   @cvar transp: Transparency mode bit vector
299      (see L{NMesh.FaceTranspModes<FaceTranspModes>}).
300   @cvar uv: List of per-face UV coordinates: [(u0, v0), (u1, v1), ...].
301   @cvar normal: (or just B{no}) The normal vector for this face: [x,y,z].
302   @note: there are normal faces and textured faces in Blender, both currently
303     with their own selection and visibility states, due to a mix of old and new
304     code.  To (un)select or (un)hide normal faces (visible in editmode), use
305     L{NMFace.sel} and L{NMFace.hide} vars.  For textured faces (Face Select
306     mode in Blender) use the old L{NMFace.flag} bitflag.  Also check the
307     example above and note L{Window.EditMode}.
308   @note: Assigning uv textures to mesh faces in Blender works like this:
309     1. Select your mesh.
310     2. Enter face select mode (press f) and select at least some face(s).
311     3. In the UV/Image Editor window, load / select an image.
312     4. Play in both windows (better split the screen to see both at the same
313        time) until the uv coordinates are where you want them.  Hint: in the
314        3d window, the 'u' key opens a menu of default uv choices and the 'r'
315        key lets you rotate the uv coords.
316     5. Leave face select mode (press f).
317   """
318
319   def append(vertex):
320     """
321     Append a vertex to this face's vertex list.
322     @type vertex: NMVert
323     @param vertex: An NMVert object.
324     """
325
326 class NMesh:
327   """
328   The NMesh Data object
329   =====================
330     This object gives access to mesh data in Blender.  We refer to mesh as the
331     object in Blender and NMesh as its Python counterpart.
332   @cvar name: The NMesh name.  It's common to use this field to store extra
333      data about the mesh (to be exported to another program, for example).
334   @cvar materials: The list of materials used by this NMesh.  See
335      L{NMesh.getMaterials} for important details.
336   @cvar verts: The list of NMesh vertices (NMVerts).
337   @cvar users: The number of Objects using (linked to) this mesh.
338   @cvar faces: The list of NMesh faces (NMFaces).
339   @cvar edges: None if mesh has no edge data, else a list of L{NMEdge} edges. Use L{addEdgesData} to create edge data if it do not exist.
340   @cvar mode:  The mode flags for this mesh.  See L{setMode}.
341   @cvar subDivLevels: The [display, rendering] subdivision levels in [1, 6].
342   @cvar maxSmoothAngle: The max angle for auto smoothing.  See L{setMode}.
343   """
344
345   def addEdge(v1, v2):
346     """
347     Create an edge between two vertices.
348     If an edge already exists between those vertices, it is returned.
349     Created edge is automatically added to edges list.
350     You can only call this method if mesh has edge data.
351     @note: In Blender only zero or one edge can link two vertices.
352     @type v1: NMVert
353     @param v1: the first vertex of the edge.
354     @type v2: NMVert
355     @param v2: the second vertex of the edge.
356     @rtype: NMEdge
357     @return: The created or already existing edge.
358     """
359
360   def findEdge(v1, v2):
361     """
362     Try to find an edge between two vertices.
363     If no edge exists between v1 and v2, None is returned.
364     You can only call this method if mesh has edge data.
365     @type v1: NMVert
366     @param v1: the first vertex of the edge.
367     @type v2: NMVert
368     @param v2: the second vertex of the edge.
369     @rtype: NMEdge
370     @return: The found edge. None if no edge was found.
371     """
372
373   def removeEdge(v1, v2):
374     """
375     Remove an edge between two vertices.
376     All faces using this edge are removed from faces list.
377     You can only call this method if mesh has edge data.
378     @type v1: NMVert
379     @param v1: the first vertex of the edge.
380     @type v2: NMVert
381     @param v2: the second vertex of the edge.
382     """
383
384   def addFace(face):
385     """
386     Add a face to face list and add to edge list (if edge data exists) necessary edges.
387     @type face: NMFace
388     @param face: the face to add to the mesh.
389     @rtype: list of NMEdge
390     @return: If mesh has edge data, return the list of face edges.
391     """
392
393   def removeFace(face):
394     """
395     Remove a face for face list and remove edges no more used by any other face (if edge data exists).
396     @type face: NMFace
397     @param face: the face to add to the mesh.
398     """
399
400   def addEdgesData():
401     """
402     If edge data does not exist for the mesh (ie L{edges}==None), then create them.
403     """
404     
405   def addMaterial(material):
406     """
407     Add a new material to this NMesh's list of materials.  This method is the
408     slower but safer way to add materials, since it checks if the argument
409     given is really a material, imposes a limit of 16 materials and only adds
410     the material if it wasn't already in the list.
411     @type material: Blender Material
412     @param material: A Blender Material.
413     """
414
415   def getMaterials(what = -1):
416     """
417     Get this NMesh's list of materials.
418     @type what: int
419     @param what: determines the list's contents:
420         - -1: return the current nmesh's list;
421         -  0: retrieve a fresh list from the Blender mesh -- eventual
422               modifications made by the script not included, unless
423               L{NMesh.update}d is called before this method;
424         -  1: like 0, but empty slots are not ignored, they are returned as
425               None's.
426     @note: what >= 0 also updates nmesh.materials attribute.
427     @rtype: list of materials
428     @return: the requested list of materials.
429     @note: if a user goes to the material buttons window and removes some
430         mesh's link to a material, that material slot becomes empty.
431         Previously such materials were ignored.
432     """
433
434   def setMaterials(matlist):
435     """
436     Set this NMesh's list of materials.  This method checks the consistency of
437     the passed list: must only have materials or None's and can't contain more
438     than 16 entries.
439     @type matlist: list of materials
440     @param matlist: a list with materials, None's also accepted (they become
441         empty material slots in Blender.
442     """
443
444   def hasVertexColours(flag = None):
445     """
446     Get (and optionally set) if this NMesh has vertex colours.
447     @type flag: int
448     @param flag: If given and non-zero, the "vertex colour" flag for this NMesh
449         is turned I{on}.
450     @rtype: bool
451     @return: The current value of the "vertex colour" flag.
452     @warn: If a mesh has both vertex colours and textured faces, this function
453        will return False.  This is due to the way Blender deals internally with
454        the vertex colours array (if there are textured faces, it is copied to
455        the textured face structure and the original array is freed/deleted).
456        If you want to know if a mesh has both textured faces and vertex
457        colours, set *in Blender* the "VCol Paint" flag for each material that
458        covers an area that was also vertex painted and then check in your
459        Python script if that material flag is set.  Of course also tell others
460        who use your script to do the same.  The "VCol Paint" material mode flag
461        is the way to tell Blender itself to render with vertex colours, too, so
462        it's a natural solution.
463     """
464
465   def hasFaceUV(flag = None):
466     """
467     Get (and optionally set) if this NMesh has UV-mapped textured faces.
468     @type flag: int
469     @param flag: If given and non-zero, the "textured faces" flag for this
470         NMesh is turned I{on}.
471     @rtype: bool
472     @return: The current value of the "textured faces" flag.
473     """
474
475   def hasVertexUV(flag = None):
476     """
477     Get (and optionally set) the "sticky" flag that controls if a mesh has
478     per vertex UV coordinates.
479     @type flag: int
480     @param flag: If given and non-zero, the "sticky" flag for this NMesh is
481         turned I{on}.
482     @rtype: bool
483     @return: The current value of the "sticky" flag.
484     """
485
486   def getActiveFace():
487     """
488     Get the index of the active face.
489     @rtype: int
490     @return: The index of the active face.
491     """
492
493   def getSelectedFaces(flag = None):
494     """
495     Get list of selected faces.
496     @type flag: int
497     @param flag: If given and non-zero, the list will have indices instead of
498         the NMFace objects themselves.
499     @rtype: list
500     @return:  It depends on the I{flag} parameter:
501         - if None or zero: List of NMFace objects.
502         - if non-zero: List of indices to NMFace objects.
503     @warn: this method exists to speed up retrieving of selected faces from
504        the actual mesh in Blender.  So, if you make changes to the nmesh, you
505        need to L{update} it before using this method.
506     """
507
508   def getVertexInfluences(index):
509     """
510     Get influences of bones in a specific vertex.
511     @type index: int
512     @param index: The index of a vertex.
513     @rtype: list of lists
514     @return: List of pairs (name, weight), where name is the bone name (string)
515         and its weight is a float value.
516     """
517
518   def insertKey(frame = None, type = 'relative'):
519     """
520     Insert a mesh key at the given frame.  Remember to L{update} the nmesh
521     before doing this, or changes in the vertices won't be updated in the
522     Blender mesh.
523     @type frame: int
524     @type type: string
525     @param frame: The Scene frame where the mesh key should be inserted.  If
526         None, the current frame is used.
527     @param type: The mesh key type: 'relative' or 'absolute'.  This is only
528         relevant on the first call to insertKey for each nmesh (and after all
529         keys were removed with L{removeAllKeys}, of course).
530     @warn: This and L{removeAllKeys} were included in this release only to
531         make accessing vertex keys possible, but may not be a proper solution
532         and may be substituted by something better later.  For example, it
533         seems that 'frame' should be kept in the range [1, 100]
534         (the curves can be manually tweaked in the Ipo Curve Editor window in
535         Blender itself later).
536     """
537
538   def removeAllKeys():
539     """
540     Remove all mesh keys stored in this mesh.
541     @rtype: bool
542     @return: True if successful or False if this NMesh wasn't linked to a real
543        Blender Mesh yet (or was, but the Mesh had no keys).
544     @warn: Currently the mesh keys from meshes that are grabbed with
545        NMesh.GetRaw() or .GetRawFromObject() are preserved, so if you want to
546        clear them or don't want them at all, remember to call this method.  Of
547        course NMeshes created with NMesh.New() don't have mesh keys until you
548        add them.
549     """
550
551   def update(recalc_normals = 0, store_edges = 0, vertex_shade = 0):
552     """
553     Update the mesh in Blender.  The changes made are put back to the mesh in
554     Blender, if available, or put in a newly created mesh if this NMesh wasn't
555     already linked to one.
556     @type recalc_normals: int (bool)
557     @param recalc_normals: if nonzero the vertex normals are recalculated.
558     @type store_edges: int (bool)
559     @param store_edges: if nonzero, then edge data is stored.
560     @type vertex_shade: int (bool)
561     @param vertex_shade: if nonzero vertices are colored based on the
562         current lighting setup, like when there are no vertex colors and no
563         textured faces and a user enters Vertex Paint Mode in Blender (only
564         lamps in visible layers account).  To use this functionality, be out of
565         edit mode or else an error will be returned.
566     @warn: edit mesh and normal mesh are two different structures in Blender,
567         synchronized upon leaving or entering edit mode.  Always remember to
568         leave edit mode (L{Window.EditMode}) before calling this update
569         method, or your changes will be lost.  Even better: for the same reason
570         programmers should leave EditMode B{before} getting a mesh, or changes
571         made to the editmesh in Blender may not be visible to your script
572         (check the example at the top of NMesh module doc).
573     @warn: unlike the L{PutRaw} function, this method doesn't check validity of
574         vertex, face and material lists, because it is meant to be as fast as
575         possible (and already performs many tasks).  So programmers should make
576         sure they only feed proper data to the nmesh -- a good general
577         recommendation, of course.  It's also trivial to write code to check
578         all data before updating, for example by comparing each item's type
579         with the actual L{Types}, if you need to.
580     @note: this method also redraws the 3d view and -- if 'vertex_shade' is
581         nonzero -- the edit buttons window.
582     @note: if your mesh disappears after it's updated, try
583         L{Object.Object.makeDisplayList}.  'Subsurf' meshes (see L{getMode},
584         L{setMode}) need their display lists updated, too.
585     """
586
587   def transform(matrix, recalc_normals = False):
588     """
589     Transforms the mesh by the specified 4x4 matrix, as returned by
590     L{Object.Object.getMatrix}, though this will work with any invertible 4x4
591     matrix type.  Ideal Usage for this is exporting to an external file, where
592     global vertex locations are required for each object.
593     Sometimes external renderers / file formats do not use vertex normals.
594     In this case you can skip transforming the vertex normals by letting
595     the optional parameter recalc_normals as False or 0.
596     
597     Example::
598      # This script outputs deformed meshes worldspace vertex locations
599      # for a selected object
600      import Blender
601      from Blender import NMesh, Object
602      
603      ob = Object.GetSelected()[0] # Get the first selected object
604      me = NMesh.GetRawFromObject(ob) # Get the objects deformed mesh data
605      me.transform(ob.matrix)
606    
607      for v in me.verts:
608        print 'worldspace vert', v.co
609     
610     @type matrix: Py_Matrix
611     @param matrix: 4x4 Matrix which can contain location, scale and rotation. 
612     @type recalc_normals: int (bool)
613     @param recalc_normals: if True or 1, will only transform vertex locations.
614     @warn: if you call this method and later L{update} the mesh, the new
615         vertex positions will be passed back to Blender, but the object
616         matrix of each object linked to this mesh won't be automatically
617         updated.  You need to set the object transformations (rotation,
618         translation and scaling) to identities, then, or the mesh data will
619         be changed ("transformed twice").
620     """
621
622   def getMode():
623     """
624     Get this mesh's mode flags.
625     @rtype: int
626     @return: Or'ed value.  See L{Modes}.
627     """
628
629   def setMode(m = None, m1=None, m2=None, m3=None):
630     """
631     Set the mode flags for this mesh.  Given mode strings turn the mode "on".
632     Modes not passed in are turned "off", so setMode() (without arguments)
633     unsets all mode flags.
634     @type m: string or int (bitflag)
635     @param m: mode string or int.  An int (see L{Modes}) or from none to 5
636       strings can be given:
637        - "NoVNormalsFlip"
638        - "TwoSided"
639        - "AutoSmooth"
640        - "SubSurf"
641        - "Optimal"
642     """
643
644   def addVertGroup(group):
645     """
646     Add a named and empty vertex (deform) group to the object this nmesh is
647     linked to. If this nmesh was newly created or accessed with GetRaw, it must
648     first be linked to an object (with object.link or NMesh.PutRaw) so the
649     method knows which object to update.\n
650     This is because vertex groups in Blender are stored in I{the object} --
651     not in the mesh, which may be linked to more than one object. For this
652     reason, it's better to use "mesh = object.getData()" than
653     "mesh = NMesh.GetRaw(meshName)" to access an existing mesh.
654     @type group: string
655     @param group: the name for the new group.
656     """
657
658   def removeVertGroup(group):
659     """
660     Remove a named vertex (deform) group from the object linked to this nmesh.
661     All vertices assigned to the group will be removed (just from the group,
662     not deleted from the mesh), if any. If this nmesh was newly created, it
663     must first be linked to an object (read the comment in L{addVertGroup} for
664     more info).
665     @type group: string
666     @param group: the name of a vertex group.
667     """
668
669   def assignVertsToGroup(group, vertList, weight, assignmode = 'replace'):
670     """
671     Adds an array (a python list) of vertex points to a named vertex group
672     associated with a mesh. The vertex list is a list of vertex indices from
673     the mesh. You should assign vertex points to groups only when the mesh has
674     all its vertex points added to it and is already linked to an object.
675
676     I{B{Example:}}
677     The example here adds a new set of vertex indices to a sphere primitive::
678      import Blender
679      sphere = Blender.Object.Get('Sphere')
680      mesh = sphere.getData()
681      mesh.addVertGroup('firstGroup')
682      vertList = []
683      for x in range(300):
684          if x % 3 == 0:
685              vertList.append(x)
686      mesh.assignVertsToGroup('firstGroup', vertList, 0.5, 'add')
687
688     @type group: string
689     @param group: the name of the group.
690     @type vertList: list of ints
691     @param vertList: a list of vertex indices.
692     @type weight: float
693     @param weight: the deform weight for (which means: the amount of influence
694         the group has over) the given vertices. It should be in the range
695         [0.0, 1.0]. If weight <= 0, the given vertices are removed from the
696         group.  If weight > 1, it is clamped.
697     @type assignmode: string
698     @param assignmode: Three choices:
699         - 'add'
700         - 'substract'
701         - 'replace'\n
702         
703         'B{add}': if the vertex in the list is not assigned to the group
704         already, this creates a new association between this vertex and the
705         group with the weight specified, otherwise the weight given is added to
706         the current weight of an existing association between the vertex and
707         group.\n
708         'B{subtract}' will attempt to subtract the weight passed from a vertex
709         already associated with a group, else it does nothing.\n
710         'B{replace}' attempts to replace a weight with the new weight value
711         for an already associated vertex/group, else it does nothing. 
712        """
713
714   def removeVertsFromGroup(group, vertList = None):
715     """
716     Remove a list of vertices from the given group.  If this nmesh was newly
717     created, it must first be linked to an object (check L{addVertGroup}).
718     @type group: string
719     @param group: the name of a vertex group
720     @type vertList: list of ints
721     @param vertList: a list of vertex indices to be removed from the given
722         'group'.  If None, all vertices are removed -- the group is emptied.
723     """
724
725   def getVertsFromGroup(group, weightsFlag = 0, vertList = None):
726     """
727     Return a list of vertex indices associated with the passed group. This
728     method can be used to test whether a vertex index is part of a group and
729     if so, what its weight is. 
730
731     I{B{Example:}}
732     Append this to the example from L{assignVertsToGroup}::
733      # ...
734      print "Vertex indices from group %s :" % groupName
735      print mesh.getVertsFromGroup('firstGroup')
736      print "Again, with weights:"
737      print mesh.getVertsFromGroup('firstGroup',1)
738      print "Again, with weights and restricted to the given indices:"
739      print mesh.getVertsFromGroup('firstGroup',1,[1,2,3,4,5,6])     
740
741     @type group: string
742     @param group: the group name.
743     @type weightsFlag: bool
744     @param weightsFlag: if 1, the weight is returned along with the index. 
745     @type vertList: list of ints
746     @param vertList: if given, only those vertex points that are both in the
747         list and group passed in are returned.
748     """
749
750   def renameVertGroup(groupName, newName):
751     """
752     Renames a vertex group.
753     @type groupName: string
754     @param groupName: the vertex group name to be renamed.
755     @type newName: string
756     @param newName: the name to replace the old name.
757     """
758
759   def getVertGroupNames():
760     """
761     Return a list of all vertex group names.
762     @rtype: list of strings
763     @return: returns a list of strings representing all vertex group
764     associated with the mesh's object
765     """
766
767   def getMaxSmoothAngle():
768     """
769     Get the max angle for auto smoothing.
770     Note: This will only affect smoothing generated at render time.
771     Smoothing can also be set per face which is visible in Blenders 3D View.
772     @return: The value in degrees.
773     """
774
775   def setMaxSmoothAngle(angle):
776     """
777     Set the max angle for auto smoothing.
778     @type angle: int
779     @param angle: The new value in degrees -- it's clamped to [1, 80].
780     """
781
782   def getSubDivLevels():
783     """
784     Get the mesh subdivision levels for realtime display and rendering.
785     @return: list of ints: [display, render].
786     """
787
788   def setSubDivLevels(subdiv):
789     """
790     Set the mesh subdivision levels for realtime display and rendering.
791     @type subdiv: list of 2 ints
792     @param subdiv: new subdiv levels: [display, render].  Both are clamped to
793         lie in the range [1, 6].
794     """
795
796