Mesh

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 @type smooth: boolean 671 @param smooth: keyword parameter (default is False). If supplied new faces will have smooth enabled. 672 @warning: Faces using the first vertex at the 3rd or 4th location in the 673 face's vertex list will have their order rotated so that the zero index 674 on in the first or second location in the face. When creating face data 675 with UVs or vertex colors, you may need to work around this, either by 676 checking for zero indices yourself or by adding a dummy first vertex to 677 the mesh that can be removed when your script has finished. 678 """

679

680 - def delete(deledges, faces):

681 """ 682 Deletes one or more faces (and optionally the edges associated with 683 the face(s)) from the mesh. 684 685 @type deledges: int 686 @param deledges: controls whether just the faces (deledges=0) 687 or the faces and edges (deledges=1) are deleted. These correspond to the 688 "Only Faces" and "Edges & Faces" options in the Edit Mode pop-up menu 689 @type faces: multiple ints or MFaces 690 @param faces: a sequence (list or tuple) containing one or more of: 691 - an MEdge belonging to the mesh 692 - a integer, specifying an index into the mesh's face list 693 """

694

695 - def sort():

696 """ 697 Sorts the faces using exactly the same syntax as pythons own list sorting function. 698 699 Example:: 700 import Blender 701 from Blender import Mesh 702 me = Mesh.Get('mymesh') 703 704 me.faces.sort(key=lambda f: f.area) 705 706 me.faces.sort(key=lambda f: f.cent) 707 708 @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. 709 """

710

711 - def selected():

712 """ 713 Get selected faces. 714 @return: a list of the indices for all faces selected in edit mode. 715 @rtype: list of ints 716 """

717 718 from IDProp import IDGroup, IDArray

719 -class Mesh:

720 """ 721 The Mesh Data object 722 ==================== 723 This object gives access to mesh data in Blender. 724 725 @note: the verts, edges and faces attributes are implemented as sequences. 726 The operator[] and len() are defined for these sequences. You cannot 727 assign to an item in the sequence, but you can assign to most of the 728 attributes of individual items. 729 @ivar edges: The mesh's edges. 730 @type edges: sequence of MEdges 731 @ivar faces: The mesh's faces. 732 @type faces: sequence of MFaces 733 @ivar verts: The mesh's vertices. 734 @type verts: sequence of MVerts 735 736 @ivar materials: The mesh's materials. Each mesh can reference up to 737 16 materials. Empty slots in the mesh's list are represented by B{None}. 738 B{Note}: L{Object.colbits<Object.Object.colbits>} needs to be set correctly 739 for each object in order for these materials to be used instead of 740 the object's materials. 741 B{Note}: Making the material list shorter does not change the face's material indices. 742 Take care when using the face's material indices to reference a material in this list. 743 B{Note}: The list that's returned is I{not} linked to the original mesh. 744 mesh.materials.append(material) won't do anything. 745 Use mesh.materials += [material] instead. 746 @type materials: list of L{Material}s 747 @ivar degr: The max angle for auto smoothing in [1,80]. 748 @type degr: int 749 @ivar maxSmoothAngle: Same as L{degr}. This attribute is only for 750 compatibility with NMesh scripts and will probably be deprecated in 751 the future. 752 @ivar mode: The mesh's mode bitfield. See L{Modes}. 753 @type mode: int 754 @ivar sel: Sets selection status for all vertices, edges and faces in the 755 mesh (write only). 756 @type sel: boolean 757 @ivar hide: Sets hidden status for all vertices, edges and faces in the 758 mesh (write only). 759 @type hide: boolean 760 @ivar subDivLevels: The [display, rendering] subdivision levels in [1, 6]. 761 @type subDivLevels: list of 2 ints 762 @ivar faceUV: The mesh contains UV-mapped textured faces. 763 @type faceUV: bool 764 @ivar vertexColors: The mesh contains vertex colors. Set True to add vertex colors. 765 @type vertexColors: bool 766 @ivar vertexUV: The mesh contains "sticky" per-vertex UV coordinates. 767 @type vertexUV: bool 768 @ivar activeFace: Index of the mesh's active face in UV Face Select and 769 Paint modes. Only one face can be active at a time. Note that this is 770 independent of the selected faces in Face Select and Edit modes. 771 Will throw an exception if the mesh does not have UV faces; use 772 L{faceUV} to test. 773 @type activeFace: int 774 @ivar activeGroup: The mesh's active vertex group. The mesh must be 775 linked to an object (read the comment in L{addVertGroup} for more info). 776 @type activeGroup: string or None 777 @ivar texMesh: The mesh's texMesh setting, used so coordinates from another 778 mesh can be used for rendering textures. 779 @type texMesh: Mesh or None 780 @ivar key: The L{Key<Key.Key>} object containing the keyframes for this mesh, if any. 781 @type key: Key or None 782 @ivar activeUVLayer: The mesh's active UV/Image layer. None if there is no UV/Image layers. 783 784 B{Note}: After setting this value, call L{update} so the result can be seen the the 3d view. 785 @type activeUVLayer: string 786 @ivar activeColorLayer: The mesh's active Vertex Color layer. None if there is no UV/Image layers. 787 788 B{Note}: After setting this value, call L{update} so the result can be seen the the 3d view. 789 @type activeColorLayer: string 790 791 @ivar renderUVLayer: The mesh's rendered UV/Image layer. None if there is no UV/Image layers. 792 @type renderUVLayer: string 793 @ivar renderColorLayer: The mesh's rendered Vertex Color layer. None if there is no UV/Image layers. 794 @type renderColorLayer: string 795 796 @ivar multires: The mesh has multires data, set True to add multires data. 797 Will throw an exception if the mesh has shape keys; use L{key} to test. 798 @type multires: bool 799 @ivar multiresLevelCount: The mesh has multires data. (read only) 800 @type multiresLevelCount: int 801 @ivar multiresDrawLevel: The multires level to display in the 3dview in [1 - multiresLevelCount]. 802 @type multiresDrawLevel: int 803 @ivar multiresEdgeLevel: The multires level edge display in the 3dview [1 - multiresLevelCount]. 804 @type multiresEdgeLevel: int 805 @ivar multiresPinLevel: The multires pin level, used for applying modifiers [1 - multiresLevelCount]. 806 @type multiresPinLevel: int 807 @ivar multiresRenderLevel: The multires level to render [1 - multiresLevelCount]. 808 @type multiresRenderLevel: int 809 810 811 """ 812

813 - def getFromObject(object, cage=0, render=0):

814 """ 815 Replace the mesh's existing data with the raw mesh data from a Blender 816 Object. This method supports all the geometry based objects (mesh, text, 817 curve, surface, and meta). If the object has modifiers, they will be 818 applied before to the object before extracting the vertex data unless 819 the B{cage} parameter is 1. 820 @note: The mesh coordinates are in I{local space}, not the world space of 821 its object. For world space vertex coordinates, each vertex location must 822 be multiplied by the object's 4x4 transform matrix (see L{transform}). 823 @note: The objects materials will not be copied into the existing mesh, 824 however the face material indices will match the material list of the original data. 825 @type object: blender object or string 826 @param object: The Blender object or its name, which contains the geometry data. 827 @type cage: int 828 @param cage: determines whether the original vertices or derived vertices 829 @type render: int 830 @param render: determines whether the render setting for modifiers will be used or not. 831 (for objects with modifiers) are used. The default is derived vertices. 832 """

833

834 - def calcNormals():

835 """ 836 Recalculates the vertex normals using face data. 837 """

838

839 - def pointInside(point, selected_only=False):

840 """ 841 @type point: vector 842 @param point: Test if this point is inside the mesh 843 @type selected_only: bool 844 @param selected_only: if True or 1, only the selected faces are taken into account. 845 Returns true if vector is inside the mesh. 846 @note: Only returns a valid result for mesh data that has no holes. 847 @note: Bubbles in the mesh work as expect. 848 """

849 - def getTangents():

850 """ 851 Calculates tangents for this mesh, returning a list of tuples, 852 each with 3 or 4 tangent vectors, these are alligned with the meshes faces. 853 854 Example:: 855 # Display the tangents as edges over a the active mesh object 856 from Blender import * 857 sce = Scene.GetCurrent() 858 ob = sce.objects.active 859 860 me = ob.getData(mesh=1) 861 ts = me.getTangents() 862 me_disp = Mesh.New() 863 864 verts = [] 865 edges = [] 866 for i, f in enumerate(me.faces): 867 ft = ts[i] 868 for j, v in enumerate(f): 869 tan = ft[j] 870 print tan 871 co = v.co 872 873 verts.append(co) 874 verts.append(co+tan) 875 876 i = len(verts) 877 edges.append((i-1, i-2)) 878 879 me_disp.verts.extend( verts ) 880 me_disp.edges.extend( edges ) 881 882 sce.objects.new( me_disp ) 883 884 @note: The tangents are computed using the active UV layer, if there are no UV layers, orco coords are used. 885 """

886 887

888 - def transform(matrix, recalc_normals = False, selected_only=False):

889 """ 890 Transforms the mesh by the specified 4x4 matrix (such as returned by 891 L{Object.Object.getMatrix}). The matrix should be invertible. 892 Ideal usage for this is exporting to an external file where 893 global vertex locations are required for each object. 894 Sometimes external renderers or file formats do not use vertex normals. 895 In this case, you can skip transforming the vertex normals by leaving 896 the optional parameter recalc_normals as False or 0 (the default value). 897 898 Example:: 899 # This script outputs deformed meshes worldspace vertex locations 900 # for a selected object without changing the object 901 import Blender 902 from Blender import Mesh, Object 903 904 ob = Object.GetSelected()[0] # Get the first selected object 905 me = Mesh.New() # Create a new mesh 906 me.getFromObject(ob.name) # Get the object's mesh data 907 verts = me.verts[:] # Save a copy of the vertices 908 me.transform(ob.matrix) # Convert verts to world space 909 for v in me.verts: 910 print 'worldspace vert', v.co 911 me.verts = verts # Restore the original verts 912 913 @type matrix: Py_Matrix 914 @param matrix: 4x4 Matrix which can contain location, scale and rotation. 915 @type recalc_normals: int 916 @param recalc_normals: if True or 1, also transform vertex normals. 917 @type selected_only: bool 918 @param selected_only: if True or 1, only the selected verts will be transformed. 919 @warn: unlike L{NMesh.transform()<NMesh.NMesh.transform>}, this method 920 I{will immediately modify the mesh data} when it is used. If you 921 transform the mesh using the object's matrix to get the vertices' 922 world positions, the result will be a "double transform". To avoid 923 this you either need to set the object's matrix to the identity 924 matrix, perform the inverse transform after outputting the transformed 925 vertices, or make a copy of the vertices prior to using this method 926 and restore them after outputting the transformed vertices (as shown 927 in the example). 928 """

929

930 - def vertexShade(object):

931 """ 932 Colors vertices based on the current lighting setup, like when there 933 are no vertex colors and no textured faces and a user enters Vertex Paint 934 Mode in Blender (only lamps in visible layers account). An exception is 935 thrown if called while in EditMode. 936 @type object: Object 937 @param object: The Blender Object linked to the mesh. 938 """

939

940 - def update(key=None):

941 """ 942 Update display lists after changes to mesh. B{Note}: with changes taking 943 place for using a directed acyclic graph (DAG) for scene and object 944 updating, this method may be only temporary and may be removed in future 945 releases. 946 @type key: string 947 @param key: Use this optional argument to write the current vertex 948 locations to the a shape key. the name must match an existing shape key for this mesh 949 See L{Mesh.Mesh.key} and L{Key.Key.blocks} to get a list of the named shape keys, setting the active keys is 950 done from the object with L{Object.Object.pinShape}, L{Object.Object.activeShape}. 951 952 953 954 @warn: Since Blender 2.42 this function has changed; now it won't recalculate 955 vertex normals (seen when faces are smooth). See L{Mesh.calcNormals()}. 956 """

957

958 - def findEdges(edges):

959 """ 960 Quickly search for the location of an edges. 961 @type edges: sequence(s) of ints or MVerts 962 @param edges: can be tuples of MVerts or integer indexes (B{note:} will 963 not work with PVerts) or a sequence (list or tuple) containing two or 964 more sequences. 965 @rtype: int, None or list 966 @return: if an edge is found, its index is returned; otherwise None is 967 returned. If a sequence of edges is passed, a list is returned. 968 """

969

970 - def addVertGroup(group):

971 """ 972 Add a named and empty vertex (deform) group to the object this mesh is 973 linked to. The mesh must first be linked to an object (with object.link() 974 or object.getData() ) so the method knows which object to update. 975 This is because vertex groups in Blender are stored in I{the object} -- 976 not in the mesh, which may be linked to more than one object. 977 @type group: string 978 @param group: the name for the new group. 979 """

980

981 - def removeVertGroup(group):

982 """ 983 Remove a named vertex (deform) group from the object linked to this mesh. 984 All vertices assigned to the group will be removed (just from the group, 985 not deleted from the mesh), if any. If this mesh was newly created, it 986 must first be linked to an object (read the comment in L{addVertGroup} for 987 more info). 988 @type group: string 989 @param group: the name of a vertex group. 990 """

991

992 - def assignVertsToGroup(group, vertList, weight, assignmode):

993 """ 994 Adds an array (a Python list) of vertex points to a named vertex group 995 associated with a mesh. The vertex list is a list of vertex indices from 996 the mesh. You should assign vertex points to groups only when the mesh has 997 all its vertex points added to it and is already linked to an object. 998 999 I{B{Example:}} 1000 The example here adds a new set of vertex indices to a sphere primitive:: 1001 import Blender 1002 sphere = Blender.Object.Get('Sphere') 1003 replace = Blender.Mesh.AssignModes.REPLACE 1004 mesh = sphere.getData(mesh=True) 1005 mesh.addVertGroup('firstGroup') 1006 vertList = [] 1007 for x in range(300): 1008 if x % 3 == 0: 1009 vertList.append(x) 1010 mesh.assignVertsToGroup('firstGroup', vertList, 0.5, replace) 1011 1012 @type group: string 1013 @param group: the name of the group. 1014 @type vertList: list of ints 1015 @param vertList: a list of vertex indices. 1016 @type weight: float 1017 @param weight: the deform weight for (which means: the amount of influence 1018 the group has over) the given vertices. It should be in the range 1019 [0.0, 1.0]. If weight <= 0, the given vertices are removed from the 1020 group. If weight > 1, it is clamped. 1021 @type assignmode: module constant 1022 @param assignmode: Three choices: REPLACE, ADD or SUBTRACT. 1023 See L{AssignModes} for a complete description. 1024 """

1025

1026 - def removeVertsFromGroup(group, vertList = None):

1027 """ 1028 Remove a list of vertices from the given group. If this mesh was newly 1029 created, it must first be linked to an object (check L{addVertGroup}). 1030 @type group: string 1031 @param group: the name of a vertex group 1032 @type vertList: list of ints 1033 @param vertList: a list of vertex indices to be removed from I{group}. 1034 If None, all vertices are removed -- the group is emptied. 1035 """

1036

1037 - def getVertsFromGroup(group, weightsFlag = 0, vertList = None):

1038 """ 1039 Return a list of vertex indices associated with the passed group. This 1040 method can be used to test whether a vertex index is part of a group and 1041 if so, what its weight is. 1042 1043 I{B{Example:}} 1044 Append this to the example from L{assignVertsToGroup}:: 1045 # ... 1046 print "Vertex indices from group %s :" % groupName 1047 print mesh.getVertsFromGroup('firstGroup') 1048 print "Again, with weights:" 1049 print mesh.getVertsFromGroup('firstGroup',1) 1050 print "Again, with weights and restricted to the given indices:" 1051 print mesh.getVertsFromGroup('firstGroup',1,[1,2,3,4,5,6]) 1052 1053 @type group: string 1054 @param group: the group name. 1055 @type weightsFlag: bool 1056 @param weightsFlag: if 1, each item in the list returned contains a 1057 tuple pair (index, weight), the weight is a float between 0.0 and 1.0. 1058 @type vertList: list of ints 1059 @param vertList: if given, only those vertex points that are both in the 1060 list and group passed in are returned. 1061 """

1062

1063 - def renameVertGroup(groupName, newName):

1064 """ 1065 Renames a vertex group. 1066 @type groupName: string 1067 @param groupName: the vertex group name to be renamed. 1068 @type newName: string 1069 @param newName: the name to replace the old name. 1070 """

1071

1072 - def getVertGroupNames():

1073 """ 1074 Return a list of all vertex group names. 1075 @rtype: list of strings 1076 @return: returns a list of strings representing all vertex group 1077 associated with the mesh's object 1078 """

1079

1080 - def getUVLayerNames():

1081 """ 1082 Return a list of all UV layer names 1083 @rtype: list of strings 1084 @return: returns a list of strings representing all UV layers 1085 associated with the mesh's object 1086 """

1087

1088 - def getColorLayerNames():

1089 """ 1090 Return a list of all color layer names 1091 @rtype: list of strings 1092 @return: returns a list of strings representing all color layers 1093 associated with the mesh's object 1094 """

1095

1096 - def getVertexInfluences(index):

1097 """ 1098 Get the bone influences for a specific vertex. 1099 @type index: int 1100 @param index: The index of a vertex. 1101 @rtype: list of lists 1102 @return: List of pairs [name, weight], where name is the bone name (string) 1103 and weight is a float value. 1104 """

1105

1106 - def removeAllKeys():

1107 """ 1108 Remove all mesh keys stored in this mesh. 1109 @rtype: bool 1110 @return: True if successful or False if the Mesh has no keys. 1111 """

1112

1113 - def insertKey(frame = None, type = 'relative'):

1114 """ 1115 Insert a mesh key at the given frame. 1116 @type frame: int 1117 @type type: string 1118 @param frame: The Scene frame where the mesh key should be inserted. If 1119 None or the arg is not given, the current frame is used. 1120 @param type: The mesh key type: 'relative' or 'absolute'. This is only 1121 relevant on meshes with no keys. 1122 @warn: This and L{removeAllKeys} were included in this release only to 1123 make accessing vertex keys possible, but may not be a proper solution 1124 and may be substituted by something better later. For example, it 1125 seems that 'frame' should be kept in the range [1, 100] 1126 (the curves can be manually tweaked in the Ipo Curve Editor window in 1127 Blender itself later). 1128 @warn: Will throw an error if the mesh has multires. use L{multires} to check. 1129 """

1130

1131 - def addUVLayer(name):

1132 """ 1133 Adds a new UV/Image layer to this mesh, it will always be the last layer but not made active. 1134 @type name: string 1135 @param name: The name of the new UV layer, 31 characters max. 1136 """

1137

1138 - def addColorLayer(name):

1139 """ 1140 Adds a new Vertex Color layer to this mesh, it will always be the last layer but not made active. 1141 @type name: string 1142 @param name: The name of the new Color layer, 31 characters max. 1143 """

1144

1145 - def addMultiresLevel(levels = 1, type = 'catmull-clark'):

1146 """ 1147 Adds multires levels to this mesh. 1148 @type levels: int 1149 @param levels: The number of levels to add 1150 @type type: string 1151 @param type: The type of multires level, 'catmull-clark' or 'simple'. 1152 """

1153

1154 - def removeUVLayer(name):

1155 """ 1156 Removes the active UV/Image layer. 1157 @type name: string 1158 @param name: The name of the UV layer to remove. 1159 """

1160

1161 - def removeColorLayer(name):

1162 """ 1163 Removes the active Vertex Color layer. 1164 @type name: string 1165 @param name: The name of the Color layer to remove. 1166 """

1167

1168 - def renameUVLayer(name, newname):

1169 """ 1170 Renames the UV layer called name to newname. 1171 @type name: string 1172 @param name: The UV layer to rename. 1173 @type newname: string 1174 @param newname: The new name of the UV layer, will be made unique. 1175 """

1176

1177 - def renameColorLayer(name, newname):

1178 """ 1179 Renames the color layer called name to newname. 1180 @type name: string 1181 @param name: The Color layer to rename. 1182 @type newname: string 1183 @param newname: The new name of the Color layer, will be made unique. 1184 """

1185

1186 - def smooth():

1187 """ 1188 Flattens angle of selected faces. Experimental mesh tool. 1189 An exception is thrown if called while in EditMode. 1190 """

1191

1192 - def flipNormals():

1193 """ 1194 Toggles the direction of selected face's normals. Experimental mesh tool. 1195 An exception is thrown if called while in EditMode. 1196 """

1197

1198 - def toSphere():

1199 """ 1200 Moves selected vertices outward in a spherical shape. Experimental mesh 1201 tool. 1202 An exception is thrown if called while in EditMode. 1203 """

1204

1205 - def fill():

1206 """ 1207 Scan fill a closed selected edge loop. Experimental mesh tool. 1208 An exception is thrown if called while in EditMode. 1209 """

1210

1211 - def triangleToQuad():

1212 """ 1213 Convert selected triangles to quads. Experimental mesh tool. 1214 An exception is thrown if called while in EditMode. 1215 """

1216

1217 - def quadToTriangle(mode=0):

1218 """ 1219 Convert selected quads to triangles. Experimental mesh tool. 1220 An exception is thrown if called while in EditMode. 1221 @type mode: int 1222 @param mode: specifies whether a to add the new edge between the 1223 closest (=0) or farthest(=1) vertices. 1224 """

1225

1226 - def subdivide(beauty=0):

1227 """ 1228 Subdivide selected edges in a mesh. Experimental mesh tool. 1229 An exception is thrown if called while in EditMode. 1230 @type beauty: int 1231 @param beauty: specifies whether a "beauty" subdivide should be 1232 enabled (disabled is default). Value must be in the range [0,1]. 1233 """

1234

1235 - def remDoubles(limit):

1236 """ 1237 Removes duplicates from selected vertices. Experimental mesh tool. 1238 An exception is thrown if called while in EditMode. 1239 @type limit: float 1240 @param limit: specifies the maximum distance considered for vertices 1241 to be "doubles". Value is clamped to the range [0.0,1.0]. 1242 @rtype: int 1243 @return: the number of vertices deleted 1244 """

1245

1246 - def recalcNormals(direction=0):

1247 """ 1248 Recalculates inside or outside normals for selected faces. Experimental 1249 mesh tool. 1250 An exception is thrown if called while in EditMode. 1251 @type direction: int 1252 @param direction: specifies outward (0) or inward (1) normals. Outward 1253 is the default. Value must be in the range [0,1]. 1254 """

1255

1256 - def __copy__ ():

1257 """ 1258 Make a copy of this mesh 1259 @rtype: Mesh 1260 @return: a copy of this mesh 1261 """

1262 1263 import id_generics 1264 Mesh.__doc__ += id_generics.attributes 1265

Source Code for Module Mesh