BPython:
[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}: vertex selection.
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   @type v: list
197   @cvar v: The list of face vertices (B{up to 4}).
198   @cvar col: The list of vertex colours.
199   @cvar mat: Same as I{materialIndex} below.
200   @cvar materialIndex: The index of this face's material in its NMesh materials
201       list.
202   @cvar smooth: If non-zero, the vertex normals are averaged to make this
203      face look smooth.
204   @cvar image: The Image used as a texture for this face.
205   @cvar mode: The display mode (see L{Mesh.FaceModes<FaceModes>})
206   @cvar flag: Bit vector specifying selection flags
207      (see L{NMesh.FaceFlags<FaceFlags>}).
208   @cvar transp: Transparency mode bit vector
209      (see L{NMesh.FaceTranspModes<FaceTranspModes>}).
210   @cvar uv: List of per-face UV coordinates: [(u0, v0), (u1, v1), ...].
211   @cvar normal: (or just B{no}) The normal vector for this face: [x,y,z].
212   @warn: Assigning uv textures to mesh faces in Blender works like this:
213     1. Select your mesh.
214     2. Enter face select mode (press f) and select at least some face(s).
215     3. In the UV/Image Editor window, load / select an image.
216     4. Play in both windows (better split the screen to see both at the same
217        time) until the uv coordinates are where you want them.  Hint: in the
218        3d window, the 'u' key opens a menu of default uv choices and the 'r'
219        key lets you rotate the uv coords.
220     5. Leave face select mode (press f).
221   """
222
223   def append(vertex):
224     """
225     Append a vertex to this face's vertex list.
226     @type vertex: NMVert
227     @param vertex: An NMVert object.
228     """
229
230 class NMesh:
231   """
232   The NMesh Data object
233   =====================
234     This object gives access to mesh data in Blender.  We refer to mesh as the
235     object in Blender and NMesh as its Python counterpart.
236   @cvar name: The NMesh name.  It's common to use this field to store extra
237      data about the mesh (to be exported to another program, for example).
238   @cvar materials: The list of materials used by this NMesh.
239   @cvar verts: The list of NMesh vertices (NMVerts).
240   @cvar users: The number of Objects using (linked to) this mesh.
241   @cvar faces: The list of NMesh faces (NMFaces).
242   @cvar mode:  The mode flags for this mesh.  See L{setMode}.
243   @cvar subDivLevels: The [display, rendering] subdivision levels in [1, 6].
244   @cvar maxSmoothAngle: The max angle for auto smoothing.  See L{setMode}.
245   """
246
247   def addMaterial(material):
248     """
249     Add a new material to this NMesh's list of materials.  This method is the
250     slower but safer way to add materials, since it checks if the argument
251     given is really a material, imposes a limit of 16 materials and only adds
252     the material if it wasn't already in the list.
253     @type material: Blender Material
254     @param material: A Blender Material.
255     """
256
257   def hasVertexColours(flag = None):
258     """
259     Get (and optionally set) if this NMesh has vertex colours.
260     @type flag: int
261     @param flag: If given and non-zero, the "vertex colour" flag for this NMesh
262         is turned I{on}.
263     @rtype: bool
264     @return: The current value of the "vertex colour" flag.
265     @warn: If a mesh has both vertex colours and textured faces, this function
266        will return False.  This is due to the way Blender deals internally with
267        the vertex colours array (if there are textured faces, it is copied to
268        the textured face structure and the original array is freed/deleted).
269        If you want to know if a mesh has both textured faces and vertex
270        colours, set *in Blender* the "VCol Paint" flag for each material that
271        covers an area that was also vertex painted and then check in your
272        Python script if that material flag is set.  Of course also tell others
273        who use your script to do the same.  The "VCol Paint" material mode flag
274        is the way to tell Blender itself to render with vertex colours, too, so
275        it's a natural solution.
276     """
277
278   def hasFaceUV(flag = None):
279     """
280     Get (and optionally set) if this NMesh has UV-mapped textured faces.
281     @type flag: int
282     @param flag: If given and non-zero, the "textured faces" flag for this
283         NMesh is turned I{on}.
284     @rtype: bool
285     @return: The current value of the "textured faces" flag.
286     """
287
288   def hasVertexUV(flag = None):
289     """
290     Get (and optionally set) the "sticky" flag that controls if a mesh has
291     per vertex UV coordinates.
292     @type flag: int
293     @param flag: If given and non-zero, the "sticky" flag for this NMesh is
294         turned I{on}.
295     @rtype: bool
296     @return: The current value of the "sticky" flag.
297     """
298
299   def getActiveFace():
300     """
301     Get the index of the active face.
302     @rtype: int
303     @return: The index of the active face.
304     """
305
306   def getSelectedFaces(flag = None):
307     """
308     Get list of selected faces.
309     @type flag: int
310     @param flag: If given and non-zero, the list will have indices instead of
311         the NMFace objects themselves.
312     @rtype: list
313     @return:  It depends on the I{flag} parameter:
314         - if None or zero: List of NMFace objects.
315         - if non-zero: List of indices to NMFace objects.
316     """
317
318   def getVertexInfluences(index):
319     """
320     Get influences of bones in a specific vertex.
321     @type index: int
322     @param index: The index of a vertex.
323     @rtype: list of lists
324     @return: List of pairs (name, weight), where name is the bone name (string)
325         and its weight is a float value.
326     """
327
328   def insertKey(frame = None, type = 'relative'):
329     """
330     Insert a mesh key at the given frame.  Remember to L{update} the nmesh
331     before doing this, or changes in the vertices won't be updated in the
332     Blender mesh.
333     @type frame: int
334     @type type: string
335     @param frame: The Scene frame where the mesh key should be inserted.  If
336         None, the current frame is used.
337     @param type: The mesh key type: 'relative' or 'absolute'.  This is only
338         relevant on the first call to insertKey for each nmesh (and after all
339         keys were removed with L{removeAllKeys}, of course).
340     @warn: This and L{removeAllKeys} were included in this release only to
341         make accessing vertex keys possible, but may not be a proper solution
342         and may be substituted by something better later.  For example, it
343         seems that 'frame' should be kept in the range [1, 100]
344         (the curves can be manually tweaked in the Ipo Curve Editor window in
345         Blender itself later).
346     """
347
348   def removeAllKeys():
349     """
350     Remove all mesh keys stored in this mesh.
351     @rtype: bool
352     @return: True if successful or False if this NMesh wasn't linked to a real
353        Blender Mesh yet (or was, but the Mesh had no keys).
354     @warn: Currently the mesh keys from meshs that are grabbed with
355        NMesh.GetRaw() or .GetRawFromObject() are preserved, so if you want to
356        clear them or don't want them at all, remember to call this method.  Of
357        course NMeshes created with NMesh.New() don't have mesh keys until you
358        add them.
359     """
360
361   def update(recalc_normals = 0):
362     """
363     Update the mesh in Blender.  The changes made are put back to the mesh in
364     Blender, if available, or put in a newly created mesh object if this NMesh
365     wasn't linked to one, yet.
366     @type recalc_normals: int
367     @param recalc_normals: If given and equal to 1, the vertex normals are
368         recalculated.
369     """
370
371   def getMode():
372     """
373     Get this mesh's mode flags.
374     @rtype: int
375     @return: Or'ed value.  See L{Modes}.
376     """
377
378   def setMode(m = None, m1=None, m2=None, m3=None):
379     """
380     Set the mode flags for this mesh.  Given mode strings turn the mode "on".
381     Modes not passed in are turned "off", so setMode() (without arguments)
382     unsets all mode flags.
383     @type m: string
384     @param m: mode string.  From none to 5 can be given:
385        - "NoVNormalsFlip"
386        - "TwoSided"
387        - "AutoSmooth"
388        - "SubSurf"
389        - "Optimal"
390     """
391
392   def addVertGroup(group):
393     """
394     Add a named and empty vertex (deform) group to the object this nmesh is
395     linked to. If this nmesh was newly created or accessed with GetRaw, it must
396     first be linked to an object (with object.link or NMesh.PutRaw) so the
397     method knows which object to update.\n
398     This is because vertex groups in Blender are stored in I{the object} --
399     not in the mesh, which may be linked to more than one object. For this
400     reason, it's better to use "mesh = object.getData()" than
401     "mesh = NMesh.GetRaw(meshName)" to access an existing mesh.
402     @type group: string
403     @param group: the name for the new group.
404     """
405
406   def removeVertGroup(group):
407     """
408     Remove a named vertex (deform) group from the object linked to this nmesh.
409     All vertices assigned to the group will be removed (just from the group,
410     not deleted from the mesh), if any. If this nmesh was newly created, it
411     must first be linked to an object (read the comment in L{addVertGroup} for
412     more info).
413     @type group: string
414     @param group: the name of a vertex group.
415     """
416
417   def assignVertsToGroup(group, vertList, weight, assignmode = 'replace'):
418     """
419     Adds an array (a python list) of vertex points to a named vertex group
420     associated with a mesh. The vertex list is a list of vertex indices from
421     the mesh. You should assign vertex points to groups only when the mesh has
422     all its vertex points added to it and is already linked to an object.
423
424     I{B{Example:}}
425     The example here adds a new set of vertex indices to a sphere primitive::
426      import Blender
427      sphere = Blender.Object.Get('Sphere')
428      mesh = sphere.getData()
429      mesh.addVertGroup('firstGroup')
430      vertList = []
431      for x in range(300):
432          if x % 3 == 0:
433              vertList.append(x)
434      mesh.assignVertsToGroup('firstGroup', vertList, 0.5, 'add')
435
436     @type group: string
437     @param group: the name of the group.
438     @type vertList: list of ints
439     @param vertList: a list of vertex indices.
440     @type weight: float
441     @param weight: the deform weight for (which means: the amount of influence
442         the group has over) the given vertices. It should be in the range
443         [0.0, 1.0]. If weight <= 0, the given vertices are removed from the
444         group.  If weight > 1, it is clamped.
445     @type assignmode: string
446     @param assignmode: Three choices:
447         - 'add'
448         - 'substract'
449         - 'replace'\n
450         
451         'B{add}': if the vertex in the list is not assigned to the group
452         already, this creates a new association between this vertex and the
453         group with the weight specified, otherwise the weight given is added to
454         the current weight of an existing association between the vertex and
455         group.\n
456         'B{subtract}' will attempt to subtract the weight passed from a vertex
457         already associated with a group, else it does nothing.\n
458         'B{replace}' attempts to replace a weight with the new weight value
459         for an already associated vertex/group, else it does nothing. 
460        """
461
462   def removeVertsFromGroup(group, vertList = None):
463     """
464     Remove a list of vertices from the given group.  If this nmesh was newly
465     created, it must first be linked to an object (check L{addVertGroup}).
466     @type group: string
467     @param group: the name of a vertex group
468     @type vertList: list of ints
469     @param vertList: a list of vertex indices to be removed from the given
470         'group'.  If None, all vertices are removed -- the group is emptied.
471     """
472
473   def getVertsFromGroup(group, weightsFlag = 0, vertList = None):
474     """
475     Return a list of vertex indices associated with the passed group. This
476     method can be used to test whether a vertex index is part of a group and
477     if so, what its weight is. 
478
479     I{B{Example:}}
480     Append this to the example from L{assignVertsToGroup}::
481      # ...
482      print "Vertex indices from group %s :" % groupName
483      print mesh.getVertsFromGroup('firstGroup')
484      print "Again, with weights:"
485      print mesh.getVertsFromGroup('firstGroup',1)
486      print "Again, with weights and restricted to the given indices:"
487      print mesh.getVertsFromGroup('firstGroup',1,[1,2,3,4,5,6])     
488
489     @type group: string
490     @param group: the group name.
491     @type weightsFlag: bool
492     @param weightsFlag: if 1, the weight is returned along with the index. 
493     @type vertList: list of ints
494     @param vertList: if given, only those vertex points that are both in the
495         list and group passed in are returned.
496     """
497
498   def renameVertGroup(groupName, newName):
499     """
500     Renames a vertex group.
501     @type groupName: string
502     @param groupName: the vertex group name to be renamed.
503     @type newName: string
504     @param newName: the name to replace the old name.
505     """
506
507   def getVertGroupNames():
508     """
509     Return a list of all vertex group names.
510     @rtype: list of strings
511     @return: returns a list of strings representing all vertex group
512     associated with the mesh's object
513     """
514
515   def getMaxSmoothAngle():
516     """
517     Get the max angle for auto smoothing.
518     @return: The value in degrees.
519     """
520
521   def setMaxSmoothAngle(angle):
522     """
523     Set the max angle for auto smoothing.
524     @type angle: int
525     @param angle: The new value in degrees -- it's clamped to [1, 80].
526     """
527
528   def getSubDivLevels():
529     """
530     Get the mesh subdivision levels for realtime display and rendering.
531     @return: list of ints: [display, render].
532     """
533
534   def setSubDivLevels(subdiv):
535     """
536     Set the mesh subdivision levels for realtime display and rendering.
537     @type subdiv: list of 2 ints
538     @param subdiv: new subdiv levels: [display, render].  Both are clamped to
539         lie in the range [1, 6].
540     """
541
542