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