Scripts:
[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}: L{NMesh.getMaterials}, L{NMesh.setMaterials}.
7
8 Mesh Data
9 =========
10
11 This module provides access to B{Mesh Data} objects in Blender.
12
13 Example::
14
15   import Blender
16   from Blender import NMesh, Material
17   #
18   me = NMesh.GetRaw("Plane")       # get the mesh data called "Plane"
19
20   if not me.materials:             # if there are no materials ...
21     newmat = Material.New()        # create one ...
22     me.materials.append(newmat)    # and append it to the mesh's list of mats
23
24   print me.materials               # print the list of materials
25   mat = me.materials[0]            # grab the first material in the list
26   mat.R = 1.0                      # redefine its red component
27   for v in me.verts:               # loop the list of vertices
28     v.co[0] *= 2.5                 # multiply the coordinates
29     v.co[1] *= 5.0
30     v.co[2] *= 2.5
31   me.update()                      # update the real mesh in Blender
32
33 @type Modes: readonly dictionary
34 @type FaceFlags: readonly dictionary
35 @type FaceModes: readonly dictionary
36 @type FaceTranspModes: readonly dictionary
37 @var Modes: The available mesh modes.
38     - NOVNORMALSFLIP - no flipping of vertex normals during render.
39     - TWOSIDED - double sided mesh.
40     - AUTOSMOOTH - turn auto smoothing of faces "on".
41     - SUBSURF - turn Catmull-Clark subdivision of surfaces "on".
42     - OPTIMAL - optimal drawing of edges when "SubSurf" is "on".
43 @var FaceFlags: The available face selection flags.
44     - SELECT - selected.
45     - HIDE - hidden.
46     - ACTIVE - the active face.
47 @var FaceModes: The available face modes. Note: these are only meaninful if
48   nmesh.hasFaceUV() returns true, since in Blender this info is stored at the
49   TexFace (TexFace button in Edit Mesh buttons) structure.
50     - ALL - set all modes at once.
51     - BILLBOARD - always orient after camera.
52     - HALO - halo face, always point to camera.
53     - DINAMYC - respond to collisions.
54     - INVISIBLE - invisible face.
55     - LIGHT - dinamyc lighting.
56     - OBCOL - use object colour instead of vertex colours.
57     - SHADOW - shadow type.
58     - SHAREDVERT - apparently unused in Blender.
59     - SHAREDCOL - shared vertex colours (per vertex).
60     - TEX - has texture image.
61     - TILES - uses tiled image.
62     - TWOSIDE - two-sided face.
63 @var FaceTranspModes: The available face transparency modes. Note: these are
64   ENUMS, they can't be combined (and'ed, or'ed, etc) like a bit vector.
65     - SOLID - draw solid.
66     - ADD - add to background (halo).
67     - ALPHA - draw with transparency.
68     - SUB - subtract from background.
69 """
70
71 def Col(col = [255, 255, 255, 255]):
72   """
73   Get a new mesh rgba color.
74   @type col: list
75   @param col: A list [red, green, blue, alpha] of int values in [0, 255].
76   @rtype: NMCol
77   @return:  A new NMCol (mesh rgba color) object.
78   """
79
80 def Vert(x = 0, y = 0, z = 0):
81   """
82   Get a new vertex object.
83   @type x: float
84   @type y: float
85   @type z: float
86   @param x: The x coordinate of the vertex.
87   @param y: The y coordinate of the vertex.
88   @param z: The z coordinate of the vertex.
89   @rtype: NMVert
90   @return: A new NMVert object.
91   """
92
93 def Face(vertexList = None):
94   """
95   Get a new face object.
96   @type vertexList: list
97   @param vertexList: A list of B{up to 4} NMVerts (mesh vertex
98       objects).
99   @rtype: NMFace
100   @return: A new NMFace object.
101   """
102
103 def New(name = 'Mesh'):
104   """
105   Create a new mesh object.
106   @type name: string
107   @param name: An optional name for the created mesh.
108   rtype: NMesh
109   @return: A new (B{empty}) NMesh object.
110   """
111
112 def GetRaw(name = None):
113   """
114   Get the mesh data object called I{name} from Blender.
115   @type name: string
116   @param name: The name of the mesh data object.
117   @rtype: NMesh
118   @return: It depends on the 'name' parameter:
119       - (name) - The NMesh wrapper of the mesh called I{name},
120         None if not found.
121       - () - A new (empty) NMesh object.
122   """
123
124 def GetRawFromObject(name):
125   """
126   Get the raw mesh data object from the Object in Blender called I{name}.
127   @type name: string
128   @param name: The name of an Object of type "Mesh".
129   @rtype: NMesh
130   @return: The NMesh wrapper of the mesh data from the Object called I{name}.
131   @warn: This function gets I{deformed} mesh data, already modified for
132       rendering (think "display list").  It also doesn't let you overwrite the
133       original mesh in Blender, so if you try to update it, a new mesh will
134       be created.
135   """
136
137 def PutRaw(nmesh, name = None, recalculate_normals = 1):
138   """
139   Put an NMesh object back in Blender.
140   @type nmesh: NMesh
141   @type name: string
142   @type recalculate_normals: int
143   @param name: The name of the mesh data object in Blender which will receive
144      this nmesh data.  It can be an existing mesh data object or a new one.
145   @param recalculate_normals: If non-zero, the vertex normals for the mesh will
146      be recalculated.
147   @rtype: None or Object
148   @return: It depends on the 'name' parameter:
149       - I{name} refers to an existing mesh data obj already linked to an
150            object: return None.
151       - I{name} refers to a new mesh data obj or an unlinked (no users) one:
152            return the created Blender Object wrapper.
153   """
154
155 class NMCol:
156   """
157   The NMCol object
158   ================
159     This object is a list of ints: [r, g, b, a] representing an
160     rgba colour.
161   @cvar r: The Red component in [0, 255].
162   @cvar g: The Green component in [0, 255].
163   @cvar b: The Blue component in [0, 255].
164   @cvar a: The Alpha (transparency) component in [0, 255].
165   """
166
167 class NMVert:
168   """
169   The NMVert object
170   =================
171     This object holds mesh vertex data.
172   @type co: list of three floats
173   @cvar co: The vertex coordinates (x, y, z).
174   @type no: list of three floats
175   @cvar no: The vertex normal vector (x, y, z).
176   @type uvco: list of two floats
177   @cvar uvco: The vertex texture "sticky" coordinates.
178   @type index: int
179   @cvar index: The vertex index, if owned by a mesh.
180   @type sel: int
181   @cvar sel: The selection state (selected:1, unselected:0) of this vertex.
182   @warn:  There are two kinds of uv texture coordinates in Blender: per vertex
183      ("sticky") and per face vertex (uv in L{NMFace}).  In the first, there's
184      only one uv pair of coordinates for each vertex in the mesh.  In the
185      second, for each face it belongs to, a vertex can have different uv
186      coordinates.  This makes the per face option more flexible, since two
187      adjacent faces won't have to be mapped to a continuous region in an image:
188      each face can be independently mapped to any part of its texture.
189   """
190
191 class NMFace:
192   """
193   The NMFace object
194   =================
195   This object holds mesh face data.
196
197   Example::
198    import Blender
199    from Blender import NMesh
200
201    me = NMesh.GetRaw("Mesh")
202    faces = me.faces
203    selected_faces = []
204    SEL = NMesh.FaceFlags['SELECT']
205    # get selected faces:
206    for f in faces:
207      if f.flag & SEL:
208      selected_faces.append(f)
209    # ... unselect selected and select all the others:
210    for f in faces:
211      if f.flag & SEL:
212        f.flag &=~SEL # unselect these
213      else: f.flag |= SEL # and select these
214
215   @type v: list
216   @cvar v: The list of face vertices (B{up to 4}).
217   @cvar col: The list of vertex colours.
218   @cvar mat: Same as I{materialIndex} below.
219   @cvar materialIndex: The index of this face's material in its NMesh materials
220       list.
221   @cvar smooth: If non-zero, the vertex normals are averaged to make this
222      face look smooth.
223   @cvar image: The Image used as a texture for this face.
224   @cvar mode: The display mode (see L{Mesh.FaceModes<FaceModes>})
225   @cvar flag: Bit vector specifying selection flags
226      (see L{NMesh.FaceFlags<FaceFlags>}).
227   @cvar transp: Transparency mode bit vector
228      (see L{NMesh.FaceTranspModes<FaceTranspModes>}).
229   @cvar uv: List of per-face UV coordinates: [(u0, v0), (u1, v1), ...].
230   @cvar normal: (or just B{no}) The normal vector for this face: [x,y,z].
231   @note: Assigning uv textures to mesh faces in Blender works like this:
232     1. Select your mesh.
233     2. Enter face select mode (press f) and select at least some face(s).
234     3. In the UV/Image Editor window, load / select an image.
235     4. Play in both windows (better split the screen to see both at the same
236        time) until the uv coordinates are where you want them.  Hint: in the
237        3d window, the 'u' key opens a menu of default uv choices and the 'r'
238        key lets you rotate the uv coords.
239     5. Leave face select mode (press f).
240   """
241
242   def append(vertex):
243     """
244     Append a vertex to this face's vertex list.
245     @type vertex: NMVert
246     @param vertex: An NMVert object.
247     """
248
249 class NMesh:
250   """
251   The NMesh Data object
252   =====================
253     This object gives access to mesh data in Blender.  We refer to mesh as the
254     object in Blender and NMesh as its Python counterpart.
255   @cvar name: The NMesh name.  It's common to use this field to store extra
256      data about the mesh (to be exported to another program, for example).
257   @cvar materials: The list of materials used by this NMesh.  See
258      L{NMesh.getMaterials} for important details.
259   @cvar verts: The list of NMesh vertices (NMVerts).
260   @cvar users: The number of Objects using (linked to) this mesh.
261   @cvar faces: The list of NMesh faces (NMFaces).
262   @cvar mode:  The mode flags for this mesh.  See L{setMode}.
263   @cvar subDivLevels: The [display, rendering] subdivision levels in [1, 6].
264   @cvar maxSmoothAngle: The max angle for auto smoothing.  See L{setMode}.
265   """
266
267   def addMaterial(material):
268     """
269     Add a new material to this NMesh's list of materials.  This method is the
270     slower but safer way to add materials, since it checks if the argument
271     given is really a material, imposes a limit of 16 materials and only adds
272     the material if it wasn't already in the list.
273     @type material: Blender Material
274     @param material: A Blender Material.
275     """
276
277   def getMaterials(what = -1):
278     """
279     Get this NMesh's list of materials.
280     @type what: int
281     @param what: determines the list's contents:
282         - -1: return the current nmesh's list;
283         -  0: retrieve a fresh list from the Blender mesh -- eventual
284               modifications made by the script not included, unless
285               L{NMesh.update}d is called before this method;
286         -  1: like 0, but empty slots are not ignored, they are returned as
287               None's.
288     @note: what >= 0 also updates nmesh.materials attribute.
289     @rtype: list of materials
290     @return: the requested list of materials.
291     @note: if a user goes to the material buttons window and removes some
292         mesh's link to a material, that material slot becomes empty.
293         Previously such materials were ignored.
294     """
295
296   def setMaterials(matlist):
297     """
298     Set this NMesh's list of materials.  This method checks the consistency of
299     the passed list: must only have materials or None's and can't contain more
300     than 16 entries.
301     @type matlist: list of materials
302     @param matlist: a list with materials, None's also accepted (they become
303         empty material slots in Blender.
304     """
305
306   def hasVertexColours(flag = None):
307     """
308     Get (and optionally set) if this NMesh has vertex colours.
309     @type flag: int
310     @param flag: If given and non-zero, the "vertex colour" flag for this NMesh
311         is turned I{on}.
312     @rtype: bool
313     @return: The current value of the "vertex colour" flag.
314     @warn: If a mesh has both vertex colours and textured faces, this function
315        will return False.  This is due to the way Blender deals internally with
316        the vertex colours array (if there are textured faces, it is copied to
317        the textured face structure and the original array is freed/deleted).
318        If you want to know if a mesh has both textured faces and vertex
319        colours, set *in Blender* the "VCol Paint" flag for each material that
320        covers an area that was also vertex painted and then check in your
321        Python script if that material flag is set.  Of course also tell others
322        who use your script to do the same.  The "VCol Paint" material mode flag
323        is the way to tell Blender itself to render with vertex colours, too, so
324        it's a natural solution.
325     """
326
327   def hasFaceUV(flag = None):
328     """
329     Get (and optionally set) if this NMesh has UV-mapped textured faces.
330     @type flag: int
331     @param flag: If given and non-zero, the "textured faces" flag for this
332         NMesh is turned I{on}.
333     @rtype: bool
334     @return: The current value of the "textured faces" flag.
335     """
336
337   def hasVertexUV(flag = None):
338     """
339     Get (and optionally set) the "sticky" flag that controls if a mesh has
340     per vertex UV coordinates.
341     @type flag: int
342     @param flag: If given and non-zero, the "sticky" flag for this NMesh is
343         turned I{on}.
344     @rtype: bool
345     @return: The current value of the "sticky" flag.
346     """
347
348   def getActiveFace():
349     """
350     Get the index of the active face.
351     @rtype: int
352     @return: The index of the active face.
353     """
354
355   def getSelectedFaces(flag = None):
356     """
357     Get list of selected faces.
358     @type flag: int
359     @param flag: If given and non-zero, the list will have indices instead of
360         the NMFace objects themselves.
361     @rtype: list
362     @return:  It depends on the I{flag} parameter:
363         - if None or zero: List of NMFace objects.
364         - if non-zero: List of indices to NMFace objects.
365     """
366
367   def getVertexInfluences(index):
368     """
369     Get influences of bones in a specific vertex.
370     @type index: int
371     @param index: The index of a vertex.
372     @rtype: list of lists
373     @return: List of pairs (name, weight), where name is the bone name (string)
374         and its weight is a float value.
375     """
376
377   def insertKey(frame = None, type = 'relative'):
378     """
379     Insert a mesh key at the given frame.  Remember to L{update} the nmesh
380     before doing this, or changes in the vertices won't be updated in the
381     Blender mesh.
382     @type frame: int
383     @type type: string
384     @param frame: The Scene frame where the mesh key should be inserted.  If
385         None, the current frame is used.
386     @param type: The mesh key type: 'relative' or 'absolute'.  This is only
387         relevant on the first call to insertKey for each nmesh (and after all
388         keys were removed with L{removeAllKeys}, of course).
389     @warn: This and L{removeAllKeys} were included in this release only to
390         make accessing vertex keys possible, but may not be a proper solution
391         and may be substituted by something better later.  For example, it
392         seems that 'frame' should be kept in the range [1, 100]
393         (the curves can be manually tweaked in the Ipo Curve Editor window in
394         Blender itself later).
395     """
396
397   def removeAllKeys():
398     """
399     Remove all mesh keys stored in this mesh.
400     @rtype: bool
401     @return: True if successful or False if this NMesh wasn't linked to a real
402        Blender Mesh yet (or was, but the Mesh had no keys).
403     @warn: Currently the mesh keys from meshes that are grabbed with
404        NMesh.GetRaw() or .GetRawFromObject() are preserved, so if you want to
405        clear them or don't want them at all, remember to call this method.  Of
406        course NMeshes created with NMesh.New() don't have mesh keys until you
407        add them.
408     """
409
410   def update(recalc_normals = 0):
411     """
412     Update the mesh in Blender.  The changes made are put back to the mesh in
413     Blender, if available, or put in a newly created mesh object if this NMesh
414     wasn't already linked to one.
415     @type recalc_normals: int
416     @param recalc_normals: If given and equal to 1, the vertex normals are
417         recalculated.
418     @note: if your mesh disappears after it's updated, try
419         L{Object.Object.makeDisplayList}.  'Subsurf' meshes (see L{getMode},
420         L{setMode}) need their display lists updated, too.
421     """
422
423   def getMode():
424     """
425     Get this mesh's mode flags.
426     @rtype: int
427     @return: Or'ed value.  See L{Modes}.
428     """
429
430   def setMode(m = None, m1=None, m2=None, m3=None):
431     """
432     Set the mode flags for this mesh.  Given mode strings turn the mode "on".
433     Modes not passed in are turned "off", so setMode() (without arguments)
434     unsets all mode flags.
435     @type m: string
436     @param m: mode string.  From none to 5 can be given:
437        - "NoVNormalsFlip"
438        - "TwoSided"
439        - "AutoSmooth"
440        - "SubSurf"
441        - "Optimal"
442     """
443
444   def addVertGroup(group):
445     """
446     Add a named and empty vertex (deform) group to the object this nmesh is
447     linked to. If this nmesh was newly created or accessed with GetRaw, it must
448     first be linked to an object (with object.link or NMesh.PutRaw) so the
449     method knows which object to update.\n
450     This is because vertex groups in Blender are stored in I{the object} --
451     not in the mesh, which may be linked to more than one object. For this
452     reason, it's better to use "mesh = object.getData()" than
453     "mesh = NMesh.GetRaw(meshName)" to access an existing mesh.
454     @type group: string
455     @param group: the name for the new group.
456     """
457
458   def removeVertGroup(group):
459     """
460     Remove a named vertex (deform) group from the object linked to this nmesh.
461     All vertices assigned to the group will be removed (just from the group,
462     not deleted from the mesh), if any. If this nmesh was newly created, it
463     must first be linked to an object (read the comment in L{addVertGroup} for
464     more info).
465     @type group: string
466     @param group: the name of a vertex group.
467     """
468
469   def assignVertsToGroup(group, vertList, weight, assignmode = 'replace'):
470     """
471     Adds an array (a python list) of vertex points to a named vertex group
472     associated with a mesh. The vertex list is a list of vertex indices from
473     the mesh. You should assign vertex points to groups only when the mesh has
474     all its vertex points added to it and is already linked to an object.
475
476     I{B{Example:}}
477     The example here adds a new set of vertex indices to a sphere primitive::
478      import Blender
479      sphere = Blender.Object.Get('Sphere')
480      mesh = sphere.getData()
481      mesh.addVertGroup('firstGroup')
482      vertList = []
483      for x in range(300):
484          if x % 3 == 0:
485              vertList.append(x)
486      mesh.assignVertsToGroup('firstGroup', vertList, 0.5, 'add')
487
488     @type group: string
489     @param group: the name of the group.
490     @type vertList: list of ints
491     @param vertList: a list of vertex indices.
492     @type weight: float
493     @param weight: the deform weight for (which means: the amount of influence
494         the group has over) the given vertices. It should be in the range
495         [0.0, 1.0]. If weight <= 0, the given vertices are removed from the
496         group.  If weight > 1, it is clamped.
497     @type assignmode: string
498     @param assignmode: Three choices:
499         - 'add'
500         - 'substract'
501         - 'replace'\n
502         
503         'B{add}': if the vertex in the list is not assigned to the group
504         already, this creates a new association between this vertex and the
505         group with the weight specified, otherwise the weight given is added to
506         the current weight of an existing association between the vertex and
507         group.\n
508         'B{subtract}' will attempt to subtract the weight passed from a vertex
509         already associated with a group, else it does nothing.\n
510         'B{replace}' attempts to replace a weight with the new weight value
511         for an already associated vertex/group, else it does nothing. 
512        """
513
514   def removeVertsFromGroup(group, vertList = None):
515     """
516     Remove a list of vertices from the given group.  If this nmesh was newly
517     created, it must first be linked to an object (check L{addVertGroup}).
518     @type group: string
519     @param group: the name of a vertex group
520     @type vertList: list of ints
521     @param vertList: a list of vertex indices to be removed from the given
522         'group'.  If None, all vertices are removed -- the group is emptied.
523     """
524
525   def getVertsFromGroup(group, weightsFlag = 0, vertList = None):
526     """
527     Return a list of vertex indices associated with the passed group. This
528     method can be used to test whether a vertex index is part of a group and
529     if so, what its weight is. 
530
531     I{B{Example:}}
532     Append this to the example from L{assignVertsToGroup}::
533      # ...
534      print "Vertex indices from group %s :" % groupName
535      print mesh.getVertsFromGroup('firstGroup')
536      print "Again, with weights:"
537      print mesh.getVertsFromGroup('firstGroup',1)
538      print "Again, with weights and restricted to the given indices:"
539      print mesh.getVertsFromGroup('firstGroup',1,[1,2,3,4,5,6])     
540
541     @type group: string
542     @param group: the group name.
543     @type weightsFlag: bool
544     @param weightsFlag: if 1, the weight is returned along with the index. 
545     @type vertList: list of ints
546     @param vertList: if given, only those vertex points that are both in the
547         list and group passed in are returned.
548     """
549
550   def renameVertGroup(groupName, newName):
551     """
552     Renames a vertex group.
553     @type groupName: string
554     @param groupName: the vertex group name to be renamed.
555     @type newName: string
556     @param newName: the name to replace the old name.
557     """
558
559   def getVertGroupNames():
560     """
561     Return a list of all vertex group names.
562     @rtype: list of strings
563     @return: returns a list of strings representing all vertex group
564     associated with the mesh's object
565     """
566
567   def getMaxSmoothAngle():
568     """
569     Get the max angle for auto smoothing.
570     @return: The value in degrees.
571     """
572
573   def setMaxSmoothAngle(angle):
574     """
575     Set the max angle for auto smoothing.
576     @type angle: int
577     @param angle: The new value in degrees -- it's clamped to [1, 80].
578     """
579
580   def getSubDivLevels():
581     """
582     Get the mesh subdivision levels for realtime display and rendering.
583     @return: list of ints: [display, render].
584     """
585
586   def setSubDivLevels(subdiv):
587     """
588     Set the mesh subdivision levels for realtime display and rendering.
589     @type subdiv: list of 2 ints
590     @param subdiv: new subdiv levels: [display, render].  Both are clamped to
591         lie in the range [1, 6].
592     """
593
594