* Changed mesh so all new data is selected (fits in with blender's UI and other areas...
[blender.git] / source / blender / python / api2_2x / doc / Mesh.py
1 # Blender.Mesh module and the Mesh PyType object
2
3 """
4 The Blender.Mesh submodule.
5
6 B{New}:
7
8 Mesh Data
9 =========
10
11 This module provides access to B{Mesh Data} objects in Blender.  It differs
12 from the NMesh module by allowing direct access to the actual Blender data, 
13 so that changes are done immediately without need to update or put the data
14 back into the original mesh.  The result is faster operations with less memory
15 usage.  The example below creates a simple pyramid, and sets some of the
16 face's attributes (the vertex color):
17
18 Example::
19         from Blender import *
20
21         editmode = Window.EditMode()    # are we in edit mode?  If so ...
22         if editmode: Window.EditMode(0) # leave edit mode before getting the mesh
23
24         # define vertices and faces for a pyramid
25         coords=[ [-1,-1,-1], [1,-1,-1], [1,1,-1], [-1,1,-1], [0,0,1] ]  
26         faces= [ [3,2,1,0], [0,1,4], [1,2,4], [2,3,4], [3,0,4] ]
27
28         me = Mesh.New('myMesh')          # create a new mesh
29
30         me.verts.extend(coords)          # add vertices to mesh
31         me.faces.extend(faces)           # add faces to the mesh (also adds edges)
32
33         me.vertexColors = 1              # enable vertex colors 
34         me.faces[1].col[0].r = 255       # make each vertex a different color
35         me.faces[1].col[1].g = 255
36         me.faces[1].col[2].b = 255
37
38         scn = Scene.GetCurrent()          # link object to current scene
39         ob = scn.objects.new(me, 'myObj')
40
41         if editmode: Window.EditMode(1)  # optional, just being nice
42
43 Vertices, edges and faces are added to a mesh using the .extend() methods.
44 For best speed and efficiency, gather all vertices, edges or faces into a
45 list and call .extend() once as in the above example.  Similarly, deleting
46 from the mesh is done with the .delete() methods and are most efficient when
47 done once.
48
49 @type Modes: readonly dictionary
50 @type FaceFlags: readonly dictionary
51 @type FaceModes: readonly dictionary
52 @type FaceTranspModes: readonly dictionary
53 @var Modes: The available mesh modes.
54                 - NOVNORMALSFLIP - no flipping of vertex normals during render.
55                 - TWOSIDED - double sided mesh.
56                 - AUTOSMOOTH - turn auto smoothing of faces "on".
57                 - note: SUBSURF and OPTIMAL have been removed, use Modifiers to apply subsurf.
58 @var FaceFlags: The available *texture face* (uv face select mode) selection
59         flags.  Note: these refer to TexFace faces, available if mesh.faceUV
60         returns true.
61                 - SELECT - selected.
62                 - HIDE - hidden.
63                 - ACTIVE - the active face, read only - Use L{mesh.activeFace<Mesh.Mesh.activeFace>} to set.
64 @var FaceModes: The available *texture face* modes. Note: these are only
65         meaningful if mesh.faceUV returns true, since in Blender this info is
66         stored at the TexFace (TexFace button in Edit Mesh buttons) structure.
67                 - ALL - set all modes at once.
68                 - BILLBOARD - always orient after camera.
69                 - HALO - halo face, always point to camera.
70                 - DYNAMIC - respond to collisions.
71                 - INVISIBLE - invisible face.
72                 - LIGHT - dynamic lighting.
73                 - OBCOL - use object color instead of vertex colors.
74                 - SHADOW - shadow type.
75                 - SHAREDVERT - apparently unused in Blender.
76                 - SHAREDCOL - shared vertex colors (per vertex).
77                 - TEX - has texture image.
78                 - TILES - uses tiled image.
79                 - TWOSIDE - two-sided face.
80 @var FaceTranspModes: The available face transparency modes. Note: these are
81         enumerated values (enums), they can't be combined (ANDed, ORed, etc) like a bit vector.
82                 - SOLID - draw solid.
83                 - ADD - add to background (halo).
84                 - ALPHA - draw with transparency.
85                 - SUB - subtract from background.
86 @var EdgeFlags: The available edge flags.
87                 - SELECT - selected (B{deprecated}).  Use edge.sel attribute instead.
88                 - EDGEDRAW - edge is drawn out of edition mode.
89                 - EDGERENDER - edge is drawn out of edition mode.
90                 - SEAM - edge is a seam for UV unwrapping
91                 - FGON - edge is part of a F-Gon.
92                 - LOOSE - Edge is not a part of a face (only set on leaving editmode)
93                 - SHARP - Edge will be rendered sharp when used with the "Edge Split" modifier.
94 @type AssignModes: readonly dictionary.
95 @var AssignModes: The available vertex group assignment modes, used by 
96         L{mesh.assignVertsToGroup()<Mesh.Mesh.assignVertsToGroup>}.
97                 - ADD: if the vertex in the list is not assigned to the group
98                         already, this creates a new association between this vertex and the
99                         group with the weight specified, otherwise the weight given is added to
100                         the current weight of an existing association between the vertex and
101                         group.
102                 - SUBTRACT: will attempt to subtract the weight passed from a vertex
103                         already associated with a group, else it does nothing.\n
104                 - REPLACE: attempts to replace a weight with the new weight value
105                         for an already associated vertex/group, else it does nothing. 
106 @type SelectModes: readonly dictionary.
107 @var SelectModes: The available edit select modes.
108         - VERTEX: vertex select mode.
109         - EDGE: edge select mode.
110         - FACE: face select mode.
111 """
112
113 AssignModes = {'REPLACE':1}
114
115 def Get(name=None):
116         """
117         Get the mesh data object called I{name} from Blender.
118         @type name: string
119         @param name: The name of the mesh data object.
120         @rtype: Mesh
121         @return: If a name is given, it returns either the requested mesh or None.
122                 If no parameter is given, it returns all the meshes in the current scene.
123         """
124
125 def New(name='Mesh'):
126         """
127         Create a new mesh data object called I{name}.
128         @type name: string
129         @param name: The name of the mesh data object.
130         @rtype: Mesh
131         @return: a new Blender mesh.
132         @note: if the mesh is not linked to an object, its datablock will be deleted
133         when the object is deallocated.
134         """
135
136 def Mode(mode=0):
137         """
138         Get and/or set the selection modes for mesh editing.  These are the modes
139         visible in the 3D window when a mesh is in Edit Mode.
140         @type mode: int
141         @param mode: The desired selection mode.  See L{SelectModes} for values.
142         Modes can be combined.  If omitted, the selection mode is not changed.
143         @rtype: int
144         @return: the current selection mode.
145         @note: The selection mode is an attribute of the current scene.  If the
146         scene is changed, the selection mode may not be the same.
147         """
148
149 def Unlink(name):
150         """
151         Delete an unused mesh from Blender's database.  The mesh must not have
152         any users (i.e., it must not be linked to any object).  
153         @type name: string
154         @param name: The name of the mesh data object.  
155         @rtype: None
156         @note: This function may be a temporary solution; it may be replaced
157         in the future by a more general unlink function for many datablock types.
158         Hopefully this will be decided prior to the 2.42 release of Blender.
159         """
160
161 class MCol:
162         """
163         The MCol object
164         ===============
165                 This object is four ints representing an RGBA color.
166         @ivar r: The Red component in [0, 255].
167         @type r: int
168         @ivar g: The Green component in [0, 255].
169         @type g: int
170         @ivar b: The Blue component in [0, 255].
171         @type b: int
172         @ivar a: The Alpha (transparency) component in [0, 255].
173         @type a: int
174         """
175
176 class MVert:
177         """
178         The MVert object
179         ================
180                 This object holds mesh vertex data.
181         @ivar co: The vertex coordinates (x, y, z).
182         @type co: vector (WRAPPED DATA)
183         @ivar no: The vertex's unit normal vector (x, y, z).
184                 B{Note}: if vertex coordinates are changed, it may be necessary to use
185                 L{Mesh.calcNormals()} to update the vertex normals.
186                 B{Note}: Vertex normals can be set, but are not wrapped so modifying a normal
187                 vector will not effect the verts normal. The result is only visible
188                 when faces have the smooth option enabled.
189                 Example::
190                         # This won't work.
191                         for v in me.verts:
192                                 v.no.x= 0
193                                 v.no.y= 0
194                                 v.no.z= 1
195                         # This will work
196                         no= Blender.Mathutils.Vector(0,0,1)
197                         for v in me.verts:
198                                 v.no= no
199         @type no: vector
200         @ivar uvco: The vertex texture "sticky" coordinates (x, y),
201                 B{Note}: These are not seen in the UV editor and they are not a part of UV a UVLayer. Use face UV's for that.
202                 if present. Available for MVerts only. 
203                 Use L{Mesh.vertexUV} to test for presence before trying to access;
204                 otherwise an exception will may be thrown.
205                 (Sticky coordinates can be set when the object is in the Edit mode;
206                 from the Editing Panel (F9), look under the "Mesh" properties for the 
207                 "Sticky" button).  
208         @type uvco: vector (WRAPPED DATA)
209         @ivar index: The vertex's index within the mesh (MVerts only). Read-only.
210         @type index: int
211         @ivar sel: The vertex's selection state (selected=1).
212                 B{Note}: a Mesh will return the selection state of the mesh when EditMode 
213                 was last exited. A Python script operating in EditMode must exit EditMode 
214                 before getting the current selection state of the mesh.
215         @type sel: int
216         @ivar hide: The face's B{edit mode} visibility state (hidden=1).
217         @type hide: int
218         @warn:  There are two kinds of UV texture coordinates in Blender: per vertex
219                 ("sticky") and per face vertex (UV in L{MFace}).  In the first, there's
220                 only one UV pair of coordinates for each vertex in the mesh.  In the
221                 second, for each face it belongs to, a vertex can have different UV
222                 coordinates.  This makes the per face option more flexible, since two
223                 adjacent faces won't have to be mapped to a continuous region in an image:
224                 each face can be independently mapped to any part of its texture.
225         """
226
227         def __init__(coord):
228                 """
229                 Create a new PVert object.  
230
231                 @note: PVert-type objects are designed to be used for creating and
232                 modifying a mesh's vertex list, but since they do not "wrap" any Blender
233                 data there are some differences.  The B{index} and B{uvco} attributes 
234                 are not defined for PVerts, and the B{no} attribute contains valid
235                 data only if the PVert was created from an MVert (using a slice
236                 operation on the mesh's vertex list.)  PVerts also cannot be used as an
237                 argument to any method which expects data wrapping a Blender mesh, such
238                 as L{MVertSeq.delete()}.
239
240                 Example::
241                         v = Blender.Mesh.MVert(1,0,0)
242                         v = Blender.Mesh.MVert(Blender.Mathutils.Vector([1,0,0]))
243
244                         m = Blender.Mesh.Get('Mesh')
245                         vlist = m.verts[:]   # slice operation also returns PVerts
246
247                 @type coord: three floats or a Vector object
248                 @param coord: the coordinate values for the new vertex
249                 @rtype: PVert
250                 @return: a new PVert object
251
252                 """
253
254 class MVertSeq:
255         """
256         The MVertSeq object
257         ===================
258                 This object provides sequence and iterator access to the mesh's vertices.
259                 Access and assignment of single items and slices are also supported.
260                 When a single item in the vertex list is accessed, the operator[] returns
261                 a MVert object which "wraps" the actual vertex in the mesh; changing any
262                 of the vertex's attributes will immediately change the data in the mesh.
263                 When a slice of the vertex list is accessed, however, the operator[]
264                 returns a list of PVert objects which are copies of the mesh's vertex
265                 data.  Changes to these objects have no effect on the mesh; they must be
266                 assigned back to the mesh's vertex list.
267
268                 Slice assignments cannot change the vertex list size.  The size of the
269                 list being assigned must be the same as the specified slice; otherwise an
270                 exception is thrown.
271
272                 Example::
273                         import Blender
274                         from Blender import Mesh
275
276                         me = Mesh.Get("Plane")          # get the mesh data called "Plane"
277                         vert = me.verts[0]              # vert accesses actual mesh data
278                         vert.co[0] += 2                 # change the vertex's X location
279                         pvert = me.verts[-2:]           # pvert is COPY of mesh's last two verts
280                         pvert[0].co[0] += 2             # change the vertex's X location
281                         pvert[1].co[0] += 2             # change the vertex's X location
282                         me.verts[-1] = pvert[1]         # put change to second vertex into mesh
283
284                 @note: The mesh can be "cleared" by assigning B{None} to the mesh's vertex
285                 list.  This does not delete the Blender mesh object, it only deletes all
286                 the memory allocated to the mesh.  The result is equivalent to calling 
287                 Mesh.New().  The intent is to allow users writing exporters to free memory
288                 after it is used in a quick and simple way.
289
290                 Example::
291                         import Blender
292                         from Blender import Mesh
293
294                         me = Mesh.Get("Plane")          # get the mesh data called "Plane"
295                         me.verts = None                 # delete all the mesh's attributes
296
297         """
298
299         def extend(coords):
300                 """
301                 Append zero or more vertices to the mesh.  Unlike L{MEdgeSeq.extend()} and
302                 L{MFaceSeq.extend()} no attempt is made to check for duplicate vertices in
303                 the parameter list, or for vertices already in the mesh.
304                 @note: Since Blender 2.44 all new verts are selected.
305
306                 Example::
307                         import Blender
308                         from Blender import Mesh
309                         from Blender.Mathutils import Vector
310
311                         me = Mesh.Get("Plane")          # get the mesh data called "Plane"
312                         me.verts.extend(1,1,1)          # add one vertex
313                         l=[(.1,.1,.1),Vector([2,2,.5])]
314                         me.verts.extend(l)              # add multiple vertices
315
316                 @type coords: sequences(s) of floats or vectors
317                 @param coords: coords can be
318                         - a sequence of three floats,
319                         - a 3D vector, or
320                         - a sequence (list or tuple) of either of the above.
321                 """
322
323         def delete(verts):
324                 """
325                 Deletes one or more vertices from the mesh.  Any edge or face which
326                 uses the specified vertices are also deleted.
327
328                 @type verts: multiple ints or MVerts
329                 @param verts: can be
330                         - a single MVert belonging to the mesh (B{note:} will not work with
331                                 PVerts)
332                         - a single integer, specifying an index into the mesh's vertex list
333                         - a sequence (list or tuple) containing two or more of either of
334                                 the above.
335                 """
336
337         def selected():
338                 """
339                 Get selected vertices.
340                 @return: a list of the indices for all vertices selected in edit mode.
341                 @rtype: list of ints
342                 """
343
344 class MEdge:
345         """
346         The MEdge object
347         ================
348                 This object holds mesh edge data.
349         @ivar v1: The first vertex of the edge.
350         @type v1: MVert
351         @ivar v2: The second vertex of the edge.
352         @type v2: MVert
353         @ivar length: The length of the edge, same as (ed.v1.co-ed.v2.co).length where "ed" is an MEdge.
354         @type length: float
355         @ivar crease: The crease value of the edge. It is in the range [0,255].
356         @type crease: int
357         @ivar flag: The bitfield describing edge properties. See L{EdgeFlags}.
358                 Example::
359                         # This script counts fgon and non fgon edges
360                         from Blender import Scene, Mesh
361                         scn= Scene.GetCurrent() # Current scene, important to be scene aware
362                         ob= scn.objects.active # last selected object
363                         me= ob.getData(mesh=1) # thin wrapper doesn't copy mesh data like nmesh
364                 
365                         total_fgon_eds= total_nor_eds= 0
366                         
367                         # Look through the edges and find any fgon edges, then print the findings to the console
368                         for ed in me.edges: # all meshes have edge data now
369                                 if ed.flag & Mesh.EdgeFlags.FGON:
370                                         total_fgon_eds+=1
371                                 else:
372                                         total_nor_eds+=1
373                         
374                         print 'Blender has', total_fgon_eds, 'fgon edges and', total_nor_eds, 'non fgon edges'
375         @type flag: int
376         @ivar index: The edge's index within the mesh.  Read-only.
377         @type index: int
378         @ivar sel: The edge's B{edit mode} selection state (selected=1).  B{Note}:
379         changing the select state of an edge changes the select state of the edge's
380         vertices.
381         @type sel: int
382         @ivar key: The edge's vert indices in an ordered tuple, which can be used
383         as a dictionary key. Read-only.
384         This is the same as (min(ed.v1.index, ed.v2.index), max(ed.v1.index, ed.v2.index))
385         @type key: tuple
386         """
387
388         def __iter__():
389                 """
390                 Iterator for MEdge.  It iterates over the MVerts of the edge, returning
391                 v1 then v2.
392                 @return: one of the edge's vertices
393                 @rtype: MVert
394                 """
395
396 class MEdgeSeq:
397         """
398         The MEdgeSeq object
399         ===================
400                 This object provides sequence and iterator access to the mesh's edges.
401         """
402
403         def extend(vertseq):
404                 """
405                 Add zero or more edges to the mesh.  Edges which already exist in the 
406                 mesh or with both vertices the same are ignored.  If three or four verts
407                 are specified in any sequence, an edge is also created between the first
408                 and last vertices (this is useful when adding faces).  
409                 @note: Since Blender 2.44 all new edges are selected.
410
411                 Example::
412                         import Blender
413                         from Blender import Mesh
414
415                         me = Mesh.Get("Plane")          # get the mesh data called "Plane"
416                         v = me.verts                    # get vertices
417                         if len(v) >= 6:                 # if there are enough vertices...
418                                 me.edges.extend(v[0],v[1])    #   add a single edge
419                                 l=[(v[1],v[2],v[3]),[0,2,4,5]]
420                                 me.edges.extend(l)            #   add multiple edges
421
422                 @type vertseq: sequence(s) of ints or MVerts
423                 @param vertseq: either two to four ints or MVerts, or sequence
424                 (list or tuple) of sequences each containing two to four ints or MVerts.
425                 """
426
427         def delete(edges):
428                 """
429                 Deletes one or more edges from the mesh.  In addition, also delete:
430                         - any faces which uses the specified edge(s)
431                         - any "orphan" vertices (belonging only to specified edge(s))
432
433                 @type edges: multiple ints or MEdges
434                 @param edges: can be
435                         - a single MEdge belonging to the mesh
436                         - a single integer, specifying an index into the mesh's edge list
437                         - a sequence (list or tuple) containing two or more of either of
438                                 the above.
439                 """
440
441         def selected():
442                 """
443                 Get selected edges.
444                 Selected edges are those for which both vertices are selected.
445                 @return: a list of the indices for all edges selected in edit mode.
446                 @rtype: list of ints
447                 """
448
449 class MFace:
450         """
451         The MFace object
452         ================
453         This object holds mesh face data.
454
455         Example::
456                 import Blender
457                 from Blender import Mesh, Window
458
459                 in_emode = Window.EditMode()
460                 if in_emode: Window.EditMode(0)
461
462                 me = Mesh.Get("Mesh")
463                 faces = me.faces
464
465                 ## Example for editmode faces selection:
466                 selected_faces = []
467                 for f in faces:
468                         if f.sel:
469                                 selected_faces.append(f)
470                 # ... unselect selected and select all the others:
471                 for f in faces:
472                         f.sel = not f.sel # 1 becomes 0, 0 becomes 1
473
474                 ## Example for UV textured faces selection:
475                 selected_faces = []
476                 SEL = Mesh.FaceFlags['SELECT']
477                 # get selected faces:
478                 for f in faces:
479                         if f.flag & SEL:
480                                 selected_faces.append(f)
481                 # ... unselect selected and select all the others:
482                 for f in faces:
483                         if f.flag & SEL:
484                                 f.flag &= ~SEL # unselect these
485                         else:
486                                 f.flag |= SEL # and select these
487
488                 if in_emode: Window.EditMode(1)
489                 Blender.Redraw()
490
491         @ivar verts: The face's vertices.  Each face has 3 or 4 vertices.
492         @type verts: list of MVerts
493         @ivar v: Same as L{verts}.  This attribute is only for compatibility with
494                 NMesh scripts and will probably be deprecated in the future.
495         @ivar sel: The face's B{edit mode} selection state (selected=1).
496                 This is not the same as the selection state of the textured faces
497                 (see L{flag}). B{Note}: changing the select state of a face changes
498                 the select state of the face's vertices.
499         @type sel: int
500         @ivar hide: The face's B{edit mode} visibility state (hidden=1).
501                 This is not the same as the visibility state of
502                 the textured faces (see L{flag}).
503         @type hide: int
504         @ivar smooth: If set, the vertex normals are averaged to make this
505                 face look smooth.  (This is the same as choosing "Set Smooth" in the 
506                 Editing Panel (F9) under "Link and Material" properties).
507         @type smooth: int
508         @ivar col: The face's vertex colors, if defined.  Each vertex has its own
509                 color.
510                 Will throw an exception if L{Mesh.vertexColors} is False.
511
512                 Example::
513                         # This example uses vertex normals to apply normal colors to each face.
514                         import bpy
515                         from Blender import Window
516                         scn= bpy.scenes.active  # Current scene, important to be scene aware
517                         ob= scn.objects.active  # last selected object
518                         me= ob.getData(mesh=1)  # thin wrapper doesn't copy mesh data like nmesh
519                         me.vertexColors= True   # Enable face, vertex colors
520                         for f in me.faces:
521                                 for i, v in enumerate(f.v):
522                                         no= v.no
523                                         col= f.col[i]
524                                         col.r= int((no.x+1)*128)
525                                         col.g= int((no.y+1)*128)
526                                         col.b= int((no.z+1)*128)
527                         Window.RedrawAll()
528         @type col: tuple of MCols
529         @ivar mat: The face's index into the mesh's materials
530                         list.  It is in the range [0,15].
531         @type mat: int
532         @ivar image: The Image used as a texture for this face.
533                         Setting this attribute will create UV faces if they do not exist.
534                         Getting this attribute throw an exception if the mesh does not have 
535                         UV faces; use L{Mesh.faceUV} to test.  
536                         Assigning an image will automatically set the TEX attribute of the
537                         L{mode} bitfield.  Use "del f.image" or "f.image = None" to clear the
538                         image assigned to the face.
539         @type image: Image
540         @ivar mode: The texture mode bitfield (see L{FaceModes}).
541                         Will throw an exception if the mesh does not have UV faces; use
542                         L{Mesh.faceUV} to test.
543         @type mode: int
544         @ivar index: The face's index within the mesh.  Read-only.
545         @type index: int
546
547         @ivar flag: The face's B{texture mode} flags; indicates the selection, 
548                         active , and visibility states of a textured face (see
549                         L{FaceFlags} for values).
550                         This is not the same as the selection or visibility states of
551                         the faces in edit mode (see L{sel} and L{hide}).
552                         To set the active face, use
553                         the L{Mesh.activeFace} attribute instead.
554                         Will throw an exception if the mesh does not have UV faces; use
555                         L{Mesh.faceUV} to test.
556
557         @ivar transp: Transparency mode.  It is one of the values in 
558                         L{FaceTranspModes}).
559                         Will throw an exception if the mesh does not have UV faces; use
560                         L{Mesh.faceUV} to test.
561         @type transp: int
562
563         @ivar uv: The face's UV coordinates.  Each vertex has its own UV coordinate.
564                         Setting this attribute will create UV faces if they do not exist.
565                         Getting this attribute throw an exception if the mesh does not have 
566                         UV faces; use L{Mesh.faceUV} to test.  
567         @type uv: tuple of vectors (WRAPPED DATA)
568         @ivar uvSel: The face's UV coordinates selection state; a 1 indicates the
569                         vertex is selected.  Each vertex has its own UV coordinate select state
570                         (this is not the same as the vertex's edit mode selection state).
571                         Setting this attribute will create UV faces if they do not exist.
572                         Getting this attribute throw an exception if the mesh does not have 
573                         UV faces; use L{Mesh.faceUV} to test.  
574         @type uvSel: tuple of ints
575         @ivar no: The face's normal vector (x, y, z).  Read-only.
576         @type no: vector
577         @ivar cent: The center of the face. Read-only.
578         @type cent: vector
579         @ivar area: The area of the face. Read-only.
580         @type area: float
581         @ivar edge_keys: A tuple, each item a key that can reference an edge by its
582         ordered indices. Read-only.  This is useful for building connectivity data.
583         Example::
584                         from Blender import Mesh
585                         me = Mesh.Get('Cube')
586                         # a dictionary where the edge is the key, and a list of faces that use it are the value
587                         edge_faces = dict([(ed.key, []) for ed in me.edges])
588
589                         # Add the faces to the dict
590                         for f in me.faces:
591                                 for key in f.edge_keys:
592                                         edge_faces[key].append(f) # add this face to the edge as a user
593
594                         # Print the edges and the number of face users
595                         for key, face_users in edge_faces.iteritems():
596                                 print 'Edge:', key, 'uses:', len(face_users),'faces'
597
598         @type edge_keys: tuple
599         @note: there are regular faces and textured faces in Blender, both currently
600                 with their own selection and visibility states, due to a mix of old and new
601                 code.  To (un)select or (un)hide regular faces (visible in EditMode), use
602                 L{MFace.sel} and L{MFace.hide} attributes.  For textured faces (UV Face 
603                 Select and Paint modes in Blender) use the L{MFace.flag} attribute.
604                 Check the example above and note L{Window.EditMode}.
605         @note: Assigning UV textures to mesh faces in Blender works like this:
606                 1. Select your mesh.
607                 2. Enter face select mode (press f) and select at least some face(s).
608                 3. In the UV/Image Editor window, load / select an image.
609                 4. Play in both windows (better split the screen to see both at the same
610                         time) until the UV coordinates are where you want them.  Hint: in the
611                         3D window, the 'u' key opens a menu of default UV choices and the 'r'
612                         key lets you rotate the UV coords.
613                 5. Leave face select mode (press f).
614         """
615
616         def __iter__():
617                 """
618                 Iterator for MVert.  It iterates over the MVerts of the face, returning
619                 v1, v2, v3 (and optionally v4);
620                 @return: one of the face's vertices
621                 @rtype: MVert
622                 """
623
624         def __len__():
625                 """
626                 len for MVert.  It returns the number of vertices in the face.
627                 @rtype: int
628                 """
629
630 class MFaceSeq:
631         """
632         The MFaceSeq object
633         ===================
634                 This object provides sequence and iterator access to the mesh's faces.
635         """
636
637         def extend(vertseq,ignoreDups=True,indexList=True):
638                 """
639                 Add zero or more faces and edges to the mesh.  Faces which already exist
640                 in the mesh, or faces which contain the same vertex multiple times are
641                 ignored.  Sequences of two vertices are accepted, but no face will be
642                 created.
643                 @note: Since Blender 2.44 all new faces are selected.
644
645                 Example::
646                         import Blender
647                         from Blender import Mesh
648
649                         me = Mesh.Get("Plane")          # get the mesh data called "Plane"
650                         v = me.verts                    # get vertices
651                         if len(v) >= 6:                 # if there are enough vertices...
652                                 me.faces.extend(v[1],v[2],v[3]) #   add a single edge
653                                 l=[(v[0],v[1]),[0,2,4,5]]
654                                 me.faces.extend(l)            #   add another face
655
656                 @type vertseq: sequence(s) of MVerts
657                 @param vertseq: either two to four ints or MVerts, or sequence (list or
658                 tuple) of sequences each containing two to four ints or MVerts.
659                 @type ignoreDups: boolean
660                 @param ignoreDups: keyword parameter (default is False).  If supplied and
661                 True, do not check the input list or mesh for duplicate faces.  This can
662                 speed up scripts but can prossibly produce undesirable effects.  Only
663                 use if you know what you're doing.
664                 @type indexList: boolean
665                 @param indexList: keyword parameter (default is False).  If supplied and
666                 True, the method will return a list representing the new index for each
667                 face in the input list.  If faces are removed as duplicates, None is
668                 inserted in place of the index.
669                 @warning: Faces using the first vertex at the 3rd or 4th location in the
670                 face's vertex list will have their order rotated so that the zero index
671                 on in the first or second location in the face. When creating face data
672                 with UVs or vertex colors, you may need to work around this, either by
673                 checking for zero indices yourself or by adding a dummy first vertex to
674                 the mesh that can be removed when your script has finished.
675                 """
676
677         def delete(deledges, faces):
678                 """
679                 Deletes one or more faces (and optionally the edges associated with
680                 the face(s)) from the mesh.  
681
682                 @type deledges: int
683                 @param deledges: controls whether just the faces (deledges=0)
684                 or the faces and edges (deledges=1) are deleted.  These correspond to the
685                 "Only Faces" and "Edges & Faces" options in the Edit Mode pop-up menu
686                 @type faces: multiple ints or MFaces
687                 @param faces: a sequence (list or tuple) containing one or more of:
688                         - an MEdge belonging to the mesh
689                         - a integer, specifying an index into the mesh's face list
690                 """
691
692         def selected():
693                 """
694                 Get selected faces.
695                 @return: a list of the indices for all faces selected in edit mode.
696                 @rtype: list of ints
697                 """
698
699 from IDProp import IDGroup, IDArray
700 class Mesh:
701         """
702         The Mesh Data object
703         ====================
704                 This object gives access to mesh data in Blender.
705
706         @note: the verts, edges and faces attributes are implemented as sequences.
707         The operator[] and len() are defined for these sequences.  You cannot
708         assign to an item in the sequence, but you can assign to most of the
709         attributes of individual items.
710         @ivar edges: The mesh's edges.
711         @type edges: sequence of MEdges
712         @ivar faces: The mesh's faces.
713         @type faces: sequence of MFaces
714         @ivar verts: The mesh's vertices.
715         @type verts: sequence of MVerts
716
717         @ivar materials: The mesh's materials.  Each mesh can reference up to
718                 16 materials.  Empty slots in the mesh's list are represented by B{None}.
719                 B{Note}: L{Object.colbits<Object.Object.colbits>} needs to be set correctly
720                 for each object in order for these materials to be used instead of
721                 the object's materials.
722                 B{Note}: Making the material list shorter does not change the face's material indices.
723                 Take care when using the face's material indices to reference a material in this list.
724                 B{Note}: The list that's returned is I{not} linked to the original mesh.
725                 mesh.materials.append(material) won't do anything.
726                 Use mesh.materials += [material] instead.
727         @type materials: list of L{Material}s
728         @ivar degr: The max angle for auto smoothing in [1,80].  
729         @type degr: int
730         @ivar maxSmoothAngle: Same as L{degr}.  This attribute is only for
731                 compatibility with NMesh scripts and will probably be deprecated in 
732                 the future.
733         @ivar mode: The mesh's mode bitfield.  See L{Modes}.
734         @type mode: int
735         @ivar sel: Sets selection status for all vertices, edges and faces in the
736                 mesh (write only).
737         @type sel: boolean
738         @ivar hide: Sets hidden status for all vertices, edges and faces in the
739                 mesh (write only).
740         @type hide: boolean
741         @ivar subDivLevels: The [display, rendering] subdivision levels in [1, 6].
742         @type subDivLevels: list of 2 ints
743
744         @ivar faceUV: The mesh contains UV-mapped textured faces.  Enabling faceUV
745                 does not initialize the face colors like the Blender UI does; this must
746                 be done in the script.  B{Note}: if faceUV is set, L{vertexColors} cannot
747                 be set.  Furthermore, if vertexColors is already set when faceUV is set,
748                 vertexColors is cleared.  This is because the vertex color information
749                 is stored with UV faces, so enabling faceUV implies enabling vertexColors.
750                 In addition, faceUV cannot be set when the mesh has no faces defined
751                 (this is the same behavior as the UI).  Attempting to do so will throw
752                 a RuntimeError exception.
753         @type faceUV: bool
754         @ivar vertexColors: The mesh contains vertex colors.  See L{faceUV} for the
755                 use of vertex colors when UV-mapped texture faces are enabled.
756         @type vertexColors: bool
757         @ivar vertexUV: The mesh contains "sticky" per-vertex UV coordinates.
758         @type vertexUV: bool
759         @ivar activeFace: Index of the mesh's active face in UV Face Select and
760                 Paint modes.  Only one face can be active at a time.  Note that this is
761                 independent of the selected faces in Face Select and Edit modes.
762                 Will throw an exception if the mesh does not have UV faces; use
763                 L{faceUV} to test.
764         @type activeFace: int
765         @ivar activeGroup: The mesh's active vertex group.  The mesh must be
766                 linked to an object (read the comment in L{addVertGroup} for more info).
767         @type activeGroup: string or None
768         @ivar texMesh: The mesh's texMesh setting, used so coordinates from another
769                 mesh can be used for rendering textures.
770         @type texMesh: Mesh or None
771         @ivar key: The L{Key<Key.Key>} object containing the keyframes for this mesh, if any.
772         @type key: Key or None
773         @ivar activeUVLayer: The mesh's active UV/Image layer. None if there is no UV/Image layers.
774
775                 B{Note}: After setting this value, call L{update} so the result can be seen the the 3d view.
776         @type activeUVLayer: string
777         @ivar activeColorLayer: The mesh's active Vertex Color layer. None if there is no UV/Image layers.
778
779                 B{Note}: After setting this value, call L{update} so the result can be seen the the 3d view.
780         @type activeColorLayer: string
781         @ivar multires: The mesh has multires data, set True to add multires data.
782                 Will throw an exception if the mesh has shape keys; use L{key} to test.
783         @type multires: bool
784         @ivar multiresLevelCount: The mesh has multires data. (read only)
785         @type multiresLevelCount: int
786         @ivar multiresDrawLevel: The multires level to display in the 3dview in [1 - multiresLevelCount].
787         @type multiresDrawLevel: int
788         @ivar multiresEdgeLevel: The multires level edge display in the 3dview [1 - multiresLevelCount].
789         @type multiresEdgeLevel: int
790         @ivar multiresPinLevel: The multires pin level, used for applying modifiers [1 - multiresLevelCount].
791         @type multiresPinLevel: int
792         @ivar multiresRenderLevel: The multires level to render [1 - multiresLevelCount].
793         @type multiresRenderLevel: int
794         
795         
796         """
797
798         def getFromObject(object, cage=0, render=0):
799                 """
800                 Replace the mesh's existing data with the raw mesh data from a Blender
801                 Object.  This method supports all the geometry based objects (mesh, text,
802                 curve, surface, and meta).  If the object has modifiers, they will be
803                 applied before to the object before extracting the vertex data unless
804                 the B{cage} parameter is 1.
805                 @note: The mesh coordinates are in I{local space}, not the world space of
806                 its object.  For world space vertex coordinates, each vertex location must
807                 be multiplied by the object's 4x4 transform matrix (see L{transform}).
808                 @note: The objects materials will not be copied into the existing mesh,
809                 however the face material indices will match the material list of the original data.
810                 @type object: blender object or string
811                 @param object: The Blender object or its name, which contains the geometry data.
812                 @type cage: int
813                 @param cage: determines whether the original vertices or derived vertices
814                 @type render: int
815                 @param render: determines whether the render setting for modifiers will be used or not.
816                 (for objects with modifiers) are used.  The default is derived vertices.
817                 """
818
819         def calcNormals():
820                 """
821                 Recalculates the vertex normals using face data.
822                 """
823         
824         def pointInside(vector):
825                 """
826                 Returns true if vector is inside the mesh.
827                 @note: Only returns a valid result for mesh data that has no holes.
828                 """
829         
830         def transform(matrix, recalc_normals = False, selected_only=False):
831                 """
832                 Transforms the mesh by the specified 4x4 matrix (such as returned by
833                 L{Object.Object.getMatrix}).  The matrix should be invertible.
834                 Ideal usage for this is exporting to an external file where
835                 global vertex locations are required for each object.
836                 Sometimes external renderers or file formats do not use vertex normals.
837                 In this case, you can skip transforming the vertex normals by leaving
838                 the optional parameter recalc_normals as False or 0 (the default value).
839
840                 Example::
841                         # This script outputs deformed meshes worldspace vertex locations
842                         # for a selected object without changing the object
843                         import Blender
844                         from Blender import Mesh, Object
845                         
846                         ob = Object.GetSelected()[0] # Get the first selected object
847                         me = Mesh.New()              # Create a new mesh
848                         me.getFromObject(ob.name)    # Get the object's mesh data
849                         verts = me.verts[:]          # Save a copy of the vertices
850                         me.transform(ob.matrix)      # Convert verts to world space
851                         for v in me.verts:
852                                 print 'worldspace vert', v.co
853                         me.verts = verts             # Restore the original verts
854                 
855                 @type matrix: Py_Matrix
856                 @param matrix: 4x4 Matrix which can contain location, scale and rotation. 
857                 @type recalc_normals: int
858                 @param recalc_normals: if True or 1, also transform vertex normals.
859                 @type selected_only: int
860                 @param selected_only: if True or 1, only the selected verts will be transformed.
861                 @warn: unlike L{NMesh.transform()<NMesh.NMesh.transform>}, this method
862                 I{will immediately modify the mesh data} when it is used.  If you
863                 transform the mesh using the object's matrix to get the vertices'
864                 world positions, the result will be a "double transform".  To avoid
865                 this you either need to set the object's matrix to the identity
866                 matrix, perform the inverse transform after outputting the transformed
867                 vertices, or make a copy of the vertices prior to using this method
868                 and restore them after outputting the transformed vertices (as shown
869                 in the example).
870                 """
871
872         def vertexShade(object):
873                 """
874                 Colors vertices based on the current lighting setup, like when there
875                 are no vertex colors and no textured faces and a user enters Vertex Paint
876                 Mode in Blender (only lamps in visible layers account).  An exception is
877                 thrown if called while in EditMode.
878                 @type object: Object
879                 @param object: The Blender Object linked to the mesh.
880                 """
881
882         def update():
883                 """
884                 Update display lists after changes to mesh.  B{Note}: with changes taking
885                 place for using a directed acyclic graph (DAG) for scene and object
886                 updating, this method may be only temporary and may be removed in future
887                 releases.
888                 @warn: Since Blender 2.42 this function has changed; now it won't recalculate
889                 vertex normals (seen when faces are smooth). See L{Mesh.calcNormals()}.
890                 """
891
892         def findEdges(edges):
893                 """
894                 Quickly search for the location of an edges.  
895                 @type edges: sequence(s) of ints or MVerts
896                 @param edges: can be tuples of MVerts or integer indexes (B{note:} will
897                         not work with PVerts) or a sequence (list or tuple) containing two or
898                         more sequences.
899                 @rtype: int, None or list
900                 @return: if an edge is found, its index is returned; otherwise None is
901                 returned.  If a sequence of edges is passed, a list is returned.
902                 """
903
904         def addVertGroup(group):
905                 """
906                 Add a named and empty vertex (deform) group to the object this mesh is
907                 linked to.  The mesh must first be linked to an object (with object.link()
908                 or object.getData() ) so the method knows which object to update.  
909                 This is because vertex groups in Blender are stored in I{the object} --
910                 not in the mesh, which may be linked to more than one object. 
911                 @type group: string
912                 @param group: the name for the new group.
913                 """
914
915         def removeVertGroup(group):
916                 """
917                 Remove a named vertex (deform) group from the object linked to this mesh.
918                 All vertices assigned to the group will be removed (just from the group,
919                 not deleted from the mesh), if any. If this mesh was newly created, it
920                 must first be linked to an object (read the comment in L{addVertGroup} for
921                 more info).
922                 @type group: string
923                 @param group: the name of a vertex group.
924                 """
925
926         def assignVertsToGroup(group, vertList, weight, assignmode = AssignModes['REPLACE']):
927                 """
928                 Adds an array (a Python list) of vertex points to a named vertex group
929                 associated with a mesh. The vertex list is a list of vertex indices from
930                 the mesh. You should assign vertex points to groups only when the mesh has
931                 all its vertex points added to it and is already linked to an object.
932
933                 I{B{Example:}}
934                 The example here adds a new set of vertex indices to a sphere primitive::
935                         import Blender
936                         sphere = Blender.Object.Get('Sphere')
937                         replace = Blender.Mesh.AssignModes.REPLACE
938                         mesh = sphere.getData(mesh=True)
939                         mesh.addVertGroup('firstGroup')
940                         vertList = []
941                         for x in range(300):
942                                 if x % 3 == 0:
943                                         vertList.append(x)
944                         mesh.assignVertsToGroup('firstGroup', vertList, 0.5, replace)
945
946                 @type group: string
947                 @param group: the name of the group.
948                 @type vertList: list of ints
949                 @param vertList: a list of vertex indices.
950                 @type weight: float
951                 @param weight: the deform weight for (which means: the amount of influence
952                                 the group has over) the given vertices. It should be in the range
953                                 [0.0, 1.0]. If weight <= 0, the given vertices are removed from the
954                                 group.  If weight > 1, it is clamped.
955                 @type assignmode: module constant
956                 @param assignmode: Three choices: REPLACE, ADD or SUBTRACT. 
957                         See L{AssignModes} for a complete description.
958                 """
959
960         def removeVertsFromGroup(group, vertList = None):
961                 """
962                 Remove a list of vertices from the given group.  If this mesh was newly
963                 created, it must first be linked to an object (check L{addVertGroup}).
964                 @type group: string
965                 @param group: the name of a vertex group
966                 @type vertList: list of ints
967                 @param vertList: a list of vertex indices to be removed from I{group}.
968                                 If None, all vertices are removed -- the group is emptied.
969                 """
970
971         def getVertsFromGroup(group, weightsFlag = 0, vertList = None):
972                 """
973                 Return a list of vertex indices associated with the passed group. This
974                 method can be used to test whether a vertex index is part of a group and
975                 if so, what its weight is. 
976
977                 I{B{Example:}}
978                 Append this to the example from L{assignVertsToGroup}::
979                         # ...
980                         print "Vertex indices from group %s :" % groupName
981                         print mesh.getVertsFromGroup('firstGroup')
982                         print "Again, with weights:"
983                         print mesh.getVertsFromGroup('firstGroup',1)
984                         print "Again, with weights and restricted to the given indices:"
985                         print mesh.getVertsFromGroup('firstGroup',1,[1,2,3,4,5,6])     
986
987                 @type group: string
988                 @param group: the group name.
989                 @type weightsFlag: bool
990                 @param weightsFlag: if 1, the weight is returned along with the index. 
991                 @type vertList: list of ints
992                 @param vertList: if given, only those vertex points that are both in the
993                                 list and group passed in are returned.
994                 """
995
996         def renameVertGroup(groupName, newName):
997                 """
998                 Renames a vertex group.
999                 @type groupName: string
1000                 @param groupName: the vertex group name to be renamed.
1001                 @type newName: string
1002                 @param newName: the name to replace the old name.
1003                 """
1004
1005         def getVertGroupNames():
1006                 """
1007                 Return a list of all vertex group names.
1008                 @rtype: list of strings
1009                 @return: returns a list of strings representing all vertex group
1010                 associated with the mesh's object
1011                 """
1012
1013         def getUVLayerNames():
1014                 """
1015                 Return a list of all UV layer names
1016                 @rtype: list of strings
1017                 @return: returns a list of strings representing all UV layers
1018                 associated with the mesh's object
1019                 """
1020
1021         def getColorLayerNames():
1022                 """
1023                 Return a list of all color layer names
1024                 @rtype: list of strings
1025                 @return: returns a list of strings representing all color layers
1026                 associated with the mesh's object
1027                 """
1028
1029         def getVertexInfluences(index):
1030                 """
1031                 Get the bone influences for a specific vertex.
1032                 @type index: int
1033                 @param index: The index of a vertex.
1034                 @rtype: list of lists
1035                 @return: List of pairs [name, weight], where name is the bone name (string)
1036                                 and weight is a float value.
1037                 """
1038
1039         def removeAllKeys():
1040                 """
1041                 Remove all mesh keys stored in this mesh.
1042                 @rtype: bool
1043                 @return: True if successful or False if the Mesh has no keys.
1044                 """
1045
1046         def insertKey(frame = None, type = 'relative'):
1047                 """
1048                 Insert a mesh key at the given frame. 
1049                 @type frame: int
1050                 @type type: string
1051                 @param frame: The Scene frame where the mesh key should be inserted.  If
1052                                 None or the arg is not given, the current frame is used.
1053                 @param type: The mesh key type: 'relative' or 'absolute'.  This is only
1054                                 relevant on meshes with no keys.
1055                 @warn: This and L{removeAllKeys} were included in this release only to
1056                                 make accessing vertex keys possible, but may not be a proper solution
1057                                 and may be substituted by something better later.  For example, it
1058                                 seems that 'frame' should be kept in the range [1, 100]
1059                                 (the curves can be manually tweaked in the Ipo Curve Editor window in
1060                                 Blender itself later).
1061                 @warn: Will throw an error if the mesh has multires. use L{multires} to check.
1062                 """
1063
1064         def addUVLayer(name):
1065                 """
1066                 Adds a new UV/Image layer to this mesh, it will always be the last layer but not made active.
1067                 @type name: string
1068                 @param name: The name of the new UV layer, 31 characters max.
1069                 """
1070
1071         def addColorLayer(name):
1072                 """
1073                 Adds a new Vertex Color layer to this mesh, it will always be the last layer but not made active.
1074                 @type name: string
1075                 @param name: The name of the new Color layer, 31 characters max.
1076                 """
1077
1078         def removeUVLayer(name):
1079                 """
1080                 Removes the active UV/Image layer.
1081                 @type name: string
1082                 @param name: The name of the UV layer to remove.
1083                 """
1084
1085         def removeColorLayer(name):
1086                 """
1087                 Removes the active Vertex Color layer.
1088                 @type name: string
1089                 @param name: The name of the Color layer to remove.
1090                 """
1091
1092         def renameUVLayer(name, newname):
1093                 """
1094                 Renames the UV layer called name to newname.
1095                 @type name: string
1096                 @param name: The UV layer to rename.
1097                 @type newname: string
1098                 @param newname: The new name of the UV layer, will be made unique.
1099                 """
1100
1101         def renameColorLayer(name, newname):
1102                 """
1103                 Renames the color layer called name to newname.
1104                 @type name: string
1105                 @param name: The Color layer to rename.
1106                 @type newname: string
1107                 @param newname: The new name of the Color layer, will be made unique.
1108                 """
1109
1110         def smooth():
1111                 """
1112                 Flattens angle of selected faces. Experimental mesh tool.
1113                 An exception is thrown if called while in EditMode.
1114                 """
1115
1116         def flipNormals():
1117                 """
1118                 Toggles the direction of selected face's normals. Experimental mesh tool.
1119                 An exception is thrown if called while in EditMode.
1120                 """
1121
1122         def toSphere():
1123                 """
1124                 Moves selected vertices outward in a spherical shape. Experimental mesh
1125                 tool.
1126                 An exception is thrown if called while in EditMode.
1127                 """
1128
1129         def fill():
1130                 """
1131                 Scan fill a closed selected edge loop. Experimental mesh tool.
1132                 An exception is thrown if called while in EditMode.
1133                 """
1134
1135         def triangleToQuad():
1136                 """
1137                 Convert selected triangles to quads. Experimental mesh tool.
1138                 An exception is thrown if called while in EditMode.
1139                 """
1140
1141         def quadToTriangle(mode=0):
1142                 """
1143                 Convert selected quads to triangles. Experimental mesh tool.
1144                 An exception is thrown if called while in EditMode.
1145                 @type mode: int
1146                 @param mode: specifies whether a to add the new edge between the
1147                 closest (=0) or farthest(=1) vertices.
1148                 """
1149
1150         def subdivide(beauty=0):
1151                 """
1152                 Subdivide selected edges in a mesh. Experimental mesh tool.
1153                 An exception is thrown if called while in EditMode.
1154                 @type beauty: int
1155                 @param beauty: specifies whether a "beauty" subdivide should be
1156                 enabled (disabled is default).  Value must be in the range [0,1].
1157                 """
1158
1159         def remDoubles(limit):
1160                 """
1161                 Removes duplicates from selected vertices. Experimental mesh tool.
1162                 An exception is thrown if called while in EditMode.
1163                 @type limit: float
1164                 @param limit: specifies the maximum distance considered for vertices
1165                 to be "doubles".  Value is clamped to the range [0.0,1.0].
1166                 @rtype: int
1167                 @return: the number of vertices deleted
1168                 """
1169
1170         def recalcNormals(direction=0):
1171                 """
1172                 Recalculates inside or outside normals for selected faces. Experimental
1173                 mesh tool.
1174                 An exception is thrown if called while in EditMode.
1175                 @type direction: int
1176                 @param direction: specifies outward (0) or inward (1) normals.  Outward
1177                 is the default.  Value must be in the range [0,1].
1178                 """
1179
1180         def __copy__ ():
1181                 """
1182                 Make a copy of this mesh
1183                 @rtype: Mesh
1184                 @return:  a copy of this mesh
1185                 """
1186
1187 import id_generics
1188 Mesh.__doc__ += id_generics.attributes