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