0c0ab3b547a9feeb4e7029bb820a4d9845802e9a
[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 Mesh Data
7 =========
8
9 This module provides access to B{Mesh Data} objects in Blender.  It differs
10 from the NMesh module by allowing direct access to the actual Blender data, 
11 so that changes are done immediately without need to update or put the data
12 back into the original mesh.  The result is faster operations with less memory
13 usage.
14
15 Example::
16
17   import Blender
18   from Blender import Mesh, Material, Window
19
20   editmode = Window.EditMode()    # are we in edit mode?  If so ...
21   if editmode: Window.EditMode(0) # leave edit mode before getting the mesh
22
23   me = Mesh.Get("Plane")          # get the mesh data called "Plane"
24
25   if not me.materials:             # if there are no materials ...
26     newmat = Material.New()        # create one ...
27     me.materials=[newmat]          # and set the mesh's list of mats
28
29   print me.materials               # print the list of materials
30   mat = me.materials[0]            # grab the first material in the list
31   mat.R = 1.0                      # redefine its red component
32   for v in me.verts:               # loop the list of vertices
33     v.co[0] *= 2.5                 # multiply the coordinates
34     v.co[1] *= 5.0
35     v.co[2] *= 2.5
36
37   if editmode: Window.EditMode(1)  # optional, just being nice
38 """
39
40 def Get(name=None):
41   """
42   Get the mesh data object called I{name} from Blender.
43   @type name: string
44   @param name: The name of the mesh data object.
45   @rtype: Mesh
46   @return: If a name is given, it returns either the requested mesh or None.
47     If no parameter is given, it returns all the meshs in the current scene.
48   """
49
50 def New(name='Mesh'):
51   """
52   Create a new mesh data object called I{name}.
53   @type name: string
54   @param name: The name of the mesh data object.
55   @rtype: Mesh
56   @return: a new Blender mesh.
57   """
58
59 class MCol:
60   """
61   The MCol object
62   ===============
63     This object is four ints representing an RGBA color.
64   @ivar r: The Red component in [0, 255].
65   @type r: int
66   @ivar g: The Green component in [0, 255].
67   @type g: int
68   @ivar b: The Blue component in [0, 255].
69   @type b: int
70   @ivar a: The Alpha (transparency) component in [0, 255].
71   @type a: int
72   """
73
74 class MVert:
75   """
76   The MVert object
77   ================
78     This object holds mesh vertex data.
79   @ivar co: The vertex coordinates (x, y, z).
80   @type co: vector
81   @ivar no: The vertex's unit normal vector (x, y, z).  Read-only.  B{Note}:
82     if vertex coordinates are changed, it may be necessary to use
83     L{Mesh.calcNormals()} to update the vertex normals.
84   @type no: vector
85   @ivar uvco: The vertex texture "sticky" coordinates (x, y), if present. 
86     Use L{Mesh.vertexUV} to test for presence before trying to access;
87     otherwise an exception will may be thrown.
88     (Sticky coordinates can be set when the object is in the Edit mode;
89     from the Editing Panel (F9), look under the "Mesh" properties for the 
90     "Sticky" button).  
91   @type uvco: vector
92   @ivar index: The vertex's index within the mesh.  Read-only.
93   @type index: int
94   @ivar sel: The vertex's selection state (selected=1).
95    B{Note}: a Mesh will return the selection state of the mesh when EditMode 
96    was last exited. A Python script operating in EditMode must exit EditMode 
97    before getting the current selection state of the mesh.
98   @type sel: int
99   @warn:  There are two kinds of UV texture coordinates in Blender: per vertex
100      ("sticky") and per face vertex (UV in L{MFace}).  In the first, there's
101      only one UV pair of coordinates for each vertex in the mesh.  In the
102      second, for each face it belongs to, a vertex can have different UV
103      coordinates.  This makes the per face option more flexible, since two
104      adjacent faces won't have to be mapped to a continuous region in an image:
105      each face can be independently mapped to any part of its texture.
106   """
107
108   def __init__(coord):
109     """
110     Create a new MVert object.
111
112     Example::
113       v = Blender.Mesh.MVert(1,0,0)
114       v = Blender.Mesh.MVert(Blender.Mathutils.Vector([1,0,0]))
115     @type coord: three floats or a Vector object
116     @param coord: the coordinate values for the new vertex
117     @rtype: MVert
118     @return: a new MVert object
119     """
120
121 class MVertSeq:
122   """
123   The MVertSeq object
124   ===================
125     This object provides sequence and iterator access to the mesh's vertices.
126     Access and assignment of single items and slices are also supported.
127     When a single item in the vertex list is accessed, the operator[] returns
128     a MVert object which "wraps" the actual vertex in the mesh; changing any
129     of the vertex's attributes will immediately change the data in the mesh.
130     When a slice of the vertex list is accessed, however, the operator[]
131     returns a list of MVert objects which are copies of the mesh's vertex
132     data.  Changes to these objects have no effect on the mesh; they must be
133     assigned back to the mesh's vertex list.
134
135     Slice assignments cannot change the vertex list size.  The size of the
136     list being assigned must be the same as the specified slice; otherwise an
137     exception is thrown.
138
139     Example::
140       import Blender
141       from Blender import Mesh
142
143       me = Mesh.Get("Plane")          # get the mesh data called "Plane"
144       vert = me.verts[0]              # vert accesses actual mesh data
145       vert.co[0] += 2                 # change the vertex's X location
146       pvert = me.verts[-2:]           # pvert is COPY of mesh's last two verts
147       pvert[0].co[0] += 2             # change the vertex's X location
148       pvert[1].co[0] += 2             # change the vertex's X location
149       me.verts[-1] = pvert[1]         # put change to second vertex into mesh
150
151   """
152
153   def extend(coords):
154     """
155     Append one or more vertices to the mesh.  Unlike L{MEdgeSeq.extend()} and
156     L{MFaceSeq.extend()} no attempt is made to check for duplicate vertices in
157     the parameter list, or for vertices already in the mesh.
158
159     Example::
160       import Blender
161       from Blender import Mesh
162       from Blender.Mathutils import Vector
163
164       me = Mesh.Get("Plane")          # get the mesh data called "Plane"
165       me.verts.extend(1,1,1)          # add one vertex
166       l=[(.1,.1,.1),Vector([2,2,.5])]
167       me.verts.extend(l)              # add multiple vertices
168
169     @type coords: tuple(s) of floats or vectors
170     @param coords: coords can be
171        - a tuple of three floats,
172        - a 3D vector, or
173        - a sequence (list or tuple) of either of the above.
174     """
175
176 class MEdge:
177   """
178   The MEdge object
179   ================
180     This object holds mesh edge data.
181   @ivar v1: The first vertex of the edge.
182   @type v1: MVert
183   @ivar v2: The second vertex of the edge.
184   @type v2: MVert
185   @ivar crease: The crease value of the edge. It is in the range [0,255].
186   @type crease: int
187   @ivar flag: The bitfield describing edge properties. See L{NMesh.EdgeFlags}.
188   @type flag: int
189   @ivar index: The edge's index within the mesh.  Read-only.
190   @type index: int
191   """
192
193   def __iter__():
194     """
195     Iterator for MEdge.  It iterates over the MVerts of the edge, returning
196     v1 then v2.
197     @return: one of the edge's vertices
198     @rtype: MVert
199     """
200
201 class MEdgeSeq:
202   """
203   The MEdgeSeq object
204   ===================
205     This object provides sequence and iterator access to the mesh's edges.
206   """
207
208   def extend(vertseq):
209     """
210     Add one or more edges to the mesh.  Edges which already exist in the 
211     mesh are ignored.  If three or four verts are specified in any tuple,
212     an edge is also created between the first and last vertices (this is
213     useful when adding faces).
214
215     Example::
216       import Blender
217       from Blender import Mesh
218
219       me = Mesh.Get("Plane")          # get the mesh data called "Plane"
220       v = me.verts                    # get vertices
221       if len(v) >= 6:                 # if there are enough vertices...
222         me.edges.extend(v[0],v[1])    #   add a single edge
223         l=[(v[1],v[2],v[3]),(v[0],v[2],v[4],v[5])]
224         me.edges.extend(l)            #   add multiple edges
225
226     @type vertseq: tuple(s) of MVerts
227     @param vertseq: either two to four MVerts, or sequence (list or tuple) 
228     of tuples each containing two to four MVerts.
229     """
230
231 class MFace:
232   """
233   The MFace object
234   ================
235   This object holds mesh face data.
236
237   Example::
238    import Blender
239    from Blender import Mesh, Window
240
241    in_emode = Window.EditMode()
242    if in_emode: Window.EditMode(0)
243
244    me = Mesh.Get("Mesh")
245    faces = me.faces
246
247    ## Example for editmode faces selection:
248    selected_faces = []
249    for f in faces:
250      if f.sel:
251        selected_faces.append(f)
252    # ... unselect selected and select all the others:
253    for f in faces:
254      f.sel = 1 - f.sel # 1 becomes 0, 0 becomes 1
255
256    ## Example for UV textured faces selection:
257    selected_faces = []
258    SEL = NMesh.FaceFlags['SELECT']
259    # get selected faces:
260    for f in faces:
261      if f.flag & SEL:
262        selected_faces.append(f)
263    # ... unselect selected and select all the others:
264    for f in faces:
265      if f.flag & SEL:
266        f.flag &= ~SEL # unselect these
267      else:
268        f.flag |= SEL # and select these
269
270    if in_emode: Window.EditMode(1)
271    Blender.Redraw()
272
273   @ivar verts: The face's vertices.  Each face has 3 or 4 vertices.
274   @type verts: list of MVerts
275   @ivar v: Same as L{verts}.  This attribute is only for compatibility with
276       NMesh scripts and will probably be deprecated in the future.
277   @ivar sel: The face's B{edit mode} selection state (selected=1).
278       This is not the same as the selection state of
279       the textured faces (see L{flag}).
280   @type sel: int
281   @ivar hide: The face's B{edit mode} visibility state (hidden=1).
282       This is not the same as the visibility state of
283       the textured faces (see L{flag}).
284   @type hide: int
285   @ivar smooth: If set, the vertex normals are averaged to make this
286      face look smooth.  (This is the same as choosing "Set Smooth" in the 
287      Editing Panel (F9) under "Link and Material" properties).
288   @type smooth: int
289   @ivar col: The face's vertex colors, if defined.  Each vertex has its own
290      color.
291      Will throw an exception if the mesh does not have UV faces or vertex
292      colors; use L{Mesh.faceUV} and L{Mesh.vertexColors} to test.  B{Note}:
293      if a mesh has i{both} UV faces and vertex colors, the colors stored in
294      the UV faces will be used here. 
295   @type col: list of MCols
296   @ivar mat: The face's index into the mesh's materials
297       list.  It is in the range [0,15].
298   @type mat: int
299   @ivar image: The Image used as a texture for this face.
300       Will throw an exception if the mesh does not have UV faces; use
301       L{Mesh.faceUV} to test.
302   @type image: Image
303   @ivar mode: The texture mode bitfield (see L{NMesh.FaceModes}).
304       Will throw an exception if the mesh does not have UV faces; use
305       L{Mesh.faceUV} to test.
306   @type mode: int
307   @ivar index: The face's index within the mesh.  Read-only.
308   @type index: int
309
310   @ivar flag: The face's B{texture mode} flags; indicates the selection, 
311       active , and visibility states of a textured face (see
312       L{NMesh.FaceFlags} for values).
313       This is not the same as the selection or visibility states of
314       the faces in edit mode (see L{sel} and L{hide}).
315       To set the active face, use
316       the L{Mesh.activeFace} attribute instead.
317       Will throw an exception if the mesh does not have UV faces; use
318       L{Mesh.faceUV} to test.
319
320   @ivar transp: Transparency mode.  It is one of the values in 
321       L{NMesh.FaceTranspModes}).
322       Will throw an exception if the mesh does not have UV faces; use
323       L{Mesh.faceUV} to test.
324   @type transp: int
325
326   @ivar uv: The face's UV coordinates.  Each vertex has its own UV coordinate.
327       Will throw an exception if the mesh does not have UV faces; use
328       L{Mesh.faceUV} to test.
329   @type uv: list of vectors
330   @ivar no: The face's normal vector (x, y, z).  Read-only.
331   @type no: vector
332   @note: there are regular faces and textured faces in Blender, both currently
333     with their own selection and visibility states, due to a mix of old and new
334     code.  To (un)select or (un)hide regular faces (visible in EditMode), use
335     L{MFace.sel} and L{MFace.hide} attributes.  For textured faces (UV Face 
336     Select and Paint modes in Blender) use the L{MFace.flag} attribute.
337     Check the example above and note L{Window.EditMode}.
338   @note: Assigning UV textures to mesh faces in Blender works like this:
339     1. Select your mesh.
340     2. Enter face select mode (press f) and select at least some face(s).
341     3. In the UV/Image Editor window, load / select an image.
342     4. Play in both windows (better split the screen to see both at the same
343        time) until the UV coordinates are where you want them.  Hint: in the
344        3D window, the 'u' key opens a menu of default UV choices and the 'r'
345        key lets you rotate the UV coords.
346     5. Leave face select mode (press f).
347   """
348
349   def __iter__():
350     """
351     Iterator for MVert.  It iterates over the MVerts of the face, returning
352     v1, v2, v3 (and optionally v4);
353     @return: one of the face's vertices
354     @rtype: MVert
355     """
356
357 class MFaceSeq:
358   """
359   The MFaceSeq object
360   ===================
361     This object provides sequence and iterator access to the mesh's faces.
362   """
363
364   def extend(vertseq):
365     """
366     Add one or more faces to the mesh.  Faces which already exist in the 
367     mesh are ignored.  Tuples of two vertices are accepted, but no face
368     will be created.
369
370     Example::
371       import Blender
372       from Blender import Mesh
373
374       me = Mesh.Get("Plane")          # get the mesh data called "Plane"
375       v = me.verts                    # get vertices
376       if len(v) >= 6:                 # if there are enough vertices...
377         me.face.extend(v[1],v[2],v[3]) #   add a single edge
378         l=[(v[0],v[1]),(v[0],v[2],v[4],v[5])]
379         me.face.extend(l)            #   add another face
380
381     @type vertseq: tuple(s) of MVerts
382     @param vertseq: either two to four MVerts, or sequence (list or tuple) 
383     of tuples each containing two to four MVerts.
384     """
385
386
387 class Mesh:
388   """
389   The Mesh Data object
390   ====================
391     This object gives access to mesh data in Blender.
392   @note: the verts, edges and faces attributes are implemented as sequences.
393   The operator[] and len() are defined for these sequences.  You cannot
394   assign to an item in the sequence, but you can assign to most of the
395   attributes of individual items.
396   @ivar edges: The mesh's edges.
397   @type edges: sequence of MEdges
398   @ivar faces: The mesh's faces.
399   @type faces: sequence of MFaces
400   @ivar verts: The mesh's vertices.
401   @type verts: sequence of MVerts
402
403   @ivar materials: The mesh's materials.  Each mesh can reference up to
404     16 materials.  Empty slots in the mesh's list are represented by B{None}.
405   @type materials: list of Materials
406   @ivar degr: The max angle for auto smoothing in [1,80].  
407   @type degr: int
408   @ivar maxSmoothAngle: Same as L{degr}.  This attribute is only for
409     compatibility with NMesh scripts and will probably be deprecated in 
410     the future.
411   @ivar mode: The mesh's mode bitfield.  See L{NMesh.Modes}.
412   @type mode: int
413
414   @ivar name: The Mesh name.  It's common to use this field to store extra
415      data about the mesh (to be exported to another program, for example).
416   @type name: str
417   @ivar subDivLevels: The [display, rendering] subdivision levels in [1, 6].
418   @type subDivLevels: list of 2 ints
419   @ivar users: The number of Objects using (linked to) this mesh.
420   @type users: int
421
422   @ivar faceUV: The mesh contains UV-mapped textured faces.  Read-only.
423   @type faceUV: bool
424   @ivar vertexColors: The mesh contains vertex colors.  Read-only.
425   @type vertexColors: bool
426   @ivar vertexUV: The mesh contains "sticky" per-vertex UV coordinates.  Read-only.
427   @type vertexUV: bool
428   @ivar activeFace: Index of the mesh's active face in UV Face Select and
429     Paint modes.  Only one face can be active at a time.  Note that this is
430     independent of the selected faces in Face Select and Edit modes.
431     Will throw an exception if the mesh does not have UV faces; use
432     L{faceUV} to test.
433   @type activeFace: int
434   """
435
436   def calcNormals():
437     """
438     Recalculates the vertex normals using face data.
439     """
440
441   def vertexShade(object):
442     """
443     Colors vertices based on the current lighting setup, like when there
444     are no vertex colors and no textured faces and a user enters Vertex Paint
445     Mode in Blender (only lamps in visible layers account).  An exception is
446     thrown if called while in EditMode.
447     @type object: Object
448     @param object: The Blender Object linked to the mesh.
449     """
450
451   def update():
452     """
453     Update display lists after changes to mesh.  B{Note}: with changes taking
454     place for using a directed acyclic graph (DAG) for scene and object
455     updating, this method may be only temporary and may be removed in future
456     releases.
457     """
458