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