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 - ALPHASORT - game engine sorts these faces only. 73 - INVISIBLE - invisible face. 74 - LIGHT - dynamic lighting. 75 - OBCOL - use object color instead of vertex colors. 76 - SHADOW - shadow type. 77 - SHAREDVERT - apparently unused in Blender. 78 - SHAREDCOL - shared vertex colors (per vertex). 79 - TEX - has texture image. 80 - TILES - uses tiled image. 81 - TWOSIDE - two-sided face. 82 @var FaceTranspModes: The available face transparency modes. Note: these are 83 enumerated values (enums), they can't be combined (ANDed, ORed, etc) like a bit vector. 84 - SOLID - draw solid. 85 - ADD - add to background (halo). 86 - ALPHA - draw with transparency. 87 - SUB - subtract from background. 88 @var EdgeFlags: The available edge flags. 89 - SELECT - selected (B{deprecated}). Use edge.sel attribute instead. 90 - EDGEDRAW - edge is drawn out of edition mode. 91 - EDGERENDER - edge is drawn out of edition mode. 92 - SEAM - edge is a seam for UV unwrapping 93 - FGON - edge is part of a F-Gon. 94 - LOOSE - Edge is not a part of a face (only set on leaving editmode) 95 - SHARP - Edge will be rendered sharp when used with the "Edge Split" modifier. 96 @type AssignModes: readonly dictionary. 97 @var AssignModes: The available vertex group assignment modes, used by 98 L{mesh.assignVertsToGroup()<Mesh.Mesh.assignVertsToGroup>}. 99 - ADD: if the vertex in the list is not assigned to the group 100 already, this creates a new association between this vertex and the 101 group with the weight specified, otherwise the weight given is added to 102 the current weight of an existing association between the vertex and 103 group. 104 - SUBTRACT: will attempt to subtract the weight passed from a vertex 105 already associated with a group, else it does nothing.\n 106 - REPLACE: attempts to replace a weight with the new weight value 107 for an already associated vertex/group, else it does nothing. 108 @type SelectModes: readonly dictionary. 109 @var SelectModes: The available edit select modes. 110 - VERTEX: vertex select mode. 111 - EDGE: edge select mode. 112 - FACE: face select mode. 113 """ 114 115 AssignModes = {'REPLACE':1} 116

117 -def Get(name=None):

118 """ 119 Get the mesh data object called I{name} from Blender. 120 @type name: string 121 @param name: The name of the mesh data object. 122 @rtype: Mesh 123 @return: If a name is given, it returns either the requested mesh or None. 124 If no parameter is given, it returns all the meshes in the current scene. 125 """

126

127 -def New(name='Mesh'):

128 """ 129 Create a new mesh data object called I{name}. 130 @type name: string 131 @param name: The name of the mesh data object. 132 @rtype: Mesh 133 @return: a new Blender mesh. 134 @note: if the mesh is not linked to an object, its datablock will be deleted 135 when the object is deallocated. 136 """

137

138 -def Mode(mode=0):

139 """ 140 Get and/or set the selection modes for mesh editing. These are the modes 141 visible in the 3D window when a mesh is in Edit Mode. 142 @type mode: int 143 @param mode: The desired selection mode. See L{SelectModes} for values. 144 Modes can be combined. If omitted, the selection mode is not changed. 145 @rtype: int 146 @return: the current selection mode. 147 @note: The selection mode is an attribute of the current scene. If the 148 scene is changed, the selection mode may not be the same. 149 """

150

151 -def Unlink(name):

152 """ 153 Delete an unused mesh from Blender's database. The mesh must not have 154 any users (i.e., it must not be linked to any object). 155 @type name: string 156 @param name: The name of the mesh data object. 157 @rtype: None 158 @note: This function may be a temporary solution; it may be replaced 159 in the future by a more general unlink function for many datablock types. 160 Hopefully this will be decided prior to the 2.42 release of Blender. 161 """

162

163 -class MCol:

164 """ 165 The MCol object 166 =============== 167 This object is four ints representing an RGBA color. 168 @ivar r: The Red component in [0, 255]. 169 @type r: int 170 @ivar g: The Green component in [0, 255]. 171 @type g: int 172 @ivar b: The Blue component in [0, 255]. 173 @type b: int 174 @ivar a: The Alpha (transparency) component in [0, 255]. 175 @type a: int 176 """

177

178 -class MVert:

179 """ 180 The MVert object 181 ================ 182 This object holds mesh vertex data. 183 @ivar co: The vertex coordinates (x, y, z). 184 @type co: vector (WRAPPED DATA) 185 @ivar no: The vertex's unit normal vector (x, y, z). 186 B{Note}: if vertex coordinates are changed, it may be necessary to use 187 L{Mesh.calcNormals()} to update the vertex normals. 188 B{Note}: Vertex normals can be set, but are not wrapped so modifying a normal 189 vector will not effect the verts normal. The result is only visible 190 when faces have the smooth option enabled. 191 Example:: 192 # This won't work. 193 for v in me.verts: 194 v.no.x= 0 195 v.no.y= 0 196 v.no.z= 1 197 # This will work 198 no= Blender.Mathutils.Vector(0,0,1) 199 for v in me.verts: 200 v.no= no 201 @type no: vector 202 @ivar uvco: The vertex texture "sticky" coordinates (x, y), 203 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. 204 if present. Available for MVerts only. 205 Use L{Mesh.vertexUV} to test for presence before trying to access; 206 otherwise an exception will may be thrown. 207 (Sticky coordinates can be set when the object is in the Edit mode; 208 from the Editing Panel (F9), look under the "Mesh" properties for the 209 "Sticky" button). 210 @type uvco: vector (WRAPPED DATA) 211 @ivar index: The vertex's index within the mesh (MVerts only). Read-only. 212 @type index: int 213 @ivar sel: The vertex's selection state (selected=1). 214 B{Note}: a Mesh will return the selection state of the mesh when EditMode 215 was last exited. A Python script operating in EditMode must exit EditMode 216 before getting the current selection state of the mesh. 217 @type sel: int 218 @ivar hide: The face's B{edit mode} visibility state (hidden=1). 219 @type hide: int 220 @warn: There are two kinds of UV texture coordinates in Blender: per vertex 221 ("sticky") and per face vertex (UV in L{MFace}). In the first, there's 222 only one UV pair of coordinates for each vertex in the mesh. In the 223 second, for each face it belongs to, a vertex can have different UV 224 coordinates. This makes the per face option more flexible, since two 225 adjacent faces won't have to be mapped to a continuous region in an image: 226 each face can be independently mapped to any part of its texture. 227 """ 228

229 - def __init__(coord):

230 """ 231 Create a new PVert object. 232 233 @note: PVert-type objects are designed to be used for creating and 234 modifying a mesh's vertex list, but since they do not "wrap" any Blender 235 data there are some differences. The B{index} and B{uvco} attributes 236 are not defined for PVerts, and the B{no} attribute contains valid 237 data only if the PVert was created from an MVert (using a slice 238 operation on the mesh's vertex list.) PVerts also cannot be used as an 239 argument to any method which expects data wrapping a Blender mesh, such 240 as L{MVertSeq.delete()}. 241 242 Example:: 243 v = Blender.Mesh.MVert(1,0,0) 244 v = Blender.Mesh.MVert(Blender.Mathutils.Vector([1,0,0])) 245 246 m = Blender.Mesh.Get('Mesh') 247 vlist = m.verts[:] # slice operation also returns PVerts 248 249 @type coord: three floats or a Vector object 250 @param coord: the coordinate values for the new vertex 251 @rtype: PVert 252 @return: a new PVert object 253 254 """

255

256 -class MVertSeq:

257 """ 258 The MVertSeq object 259 =================== 260 This object provides sequence and iterator access to the mesh's vertices. 261 Access and assignment of single items and slices are also supported. 262 When a single item in the vertex list is accessed, the operator[] returns 263 a MVert object which "wraps" the actual vertex in the mesh; changing any 264 of the vertex's attributes will immediately change the data in the mesh. 265 When a slice of the vertex list is accessed, however, the operator[] 266 returns a list of PVert objects which are copies of the mesh's vertex 267 data. Changes to these objects have no effect on the mesh; they must be 268 assigned back to the mesh's vertex list. 269 270 Slice assignments cannot change the vertex list size. The size of the 271 list being assigned must be the same as the specified slice; otherwise an 272 exception is thrown. 273 274 Example:: 275 import Blender 276 from Blender import Mesh 277 278 me = Mesh.Get("Plane") # get the mesh data called "Plane" 279 vert = me.verts[0] # vert accesses actual mesh data 280 vert.co[0] += 2 # change the vertex's X location 281 pvert = me.verts[-2:] # pvert is COPY of mesh's last two verts 282 pvert[0].co[0] += 2 # change the vertex's X location 283 pvert[1].co[0] += 2 # change the vertex's X location 284 me.verts[-1] = pvert[1] # put change to second vertex into mesh 285 286 @note: The mesh can be "cleared" by assigning B{None} to the mesh's vertex 287 list. This does not delete the Blender mesh object, it only deletes all 288 the memory allocated to the mesh. The result is equivalent to calling 289 Mesh.New(). The intent is to allow users writing exporters to free memory 290 after it is used in a quick and simple way. 291 292 Example:: 293 import Blender 294 from Blender import Mesh 295 296 me = Mesh.Get("Plane") # get the mesh data called "Plane" 297 me.verts = None # delete all the mesh's attributes 298 299 """ 300

301 - def extend(coords):

302 """ 303 Append zero or more vertices to the mesh. Unlike L{MEdgeSeq.extend()} and 304 L{MFaceSeq.extend()} no attempt is made to check for duplicate vertices in 305 the parameter list, or for vertices already in the mesh. 306 @note: Since Blender 2.44 all new verts are selected. 307 308 Example:: 309 import Blender 310 from Blender import Mesh 311 from Blender.Mathutils import Vector 312 313 me = Mesh.Get("Plane") # get the mesh data called "Plane" 314 me.verts.extend(1,1,1) # add one vertex 315 l=[(.1,.1,.1),Vector([2,2,.5])] 316 me.verts.extend(l) # add multiple vertices 317 318 @type coords: sequences(s) of floats or vectors 319 @param coords: coords can be 320 - a sequence of three floats, 321 - a 3D vector, or 322 - a sequence (list or tuple) of either of the above. 323 """

324

325 - def delete(verts):

326 """ 327 Deletes one or more vertices from the mesh. Any edge or face which 328 uses the specified vertices are also deleted. 329 330 @type verts: multiple ints or MVerts 331 @param verts: can be 332 - a single MVert belonging to the mesh (B{note:} will not work with 333 PVerts) 334 - a single integer, specifying an index into the mesh's vertex list 335 - a sequence (list or tuple) containing two or more of either of 336 the above. 337 """

338

339 - def selected():

340 """ 341 Get selected vertices. 342 @return: a list of the indices for all vertices selected in edit mode. 343 @rtype: list of ints 344 """

345

346 -class MEdge:

347 """ 348 The MEdge object 349 ================ 350 This object holds mesh edge data. 351 @ivar v1: The first vertex of the edge. 352 @type v1: MVert 353 @ivar v2: The second vertex of the edge. 354 @type v2: MVert 355 @ivar length: The length of the edge, same as (ed.v1.co-ed.v2.co).length where "ed" is an MEdge. 356 @type length: float 357 @ivar crease: The crease value of the edge. It is in the range [0,255]. 358 @type crease: int 359 @ivar flag: The bitfield describing edge properties. See L{EdgeFlags}. 360 Example:: 361 # This script counts fgon and non fgon edges 362 from Blender import Scene, Mesh 363 scn= Scene.GetCurrent() # Current scene, important to be scene aware 364 ob= scn.objects.active # last selected object 365 me= ob.getData(mesh=1) # thin wrapper doesn't copy mesh data like nmesh 366 367 total_fgon_eds= total_nor_eds= 0 368 369 # Look through the edges and find any fgon edges, then print the findings to the console 370 for ed in me.edges: # all meshes have edge data now 371 if ed.flag & Mesh.EdgeFlags.FGON: 372 total_fgon_eds+=1 373 else: 374 total_nor_eds+=1 375 376 print 'Blender has', total_fgon_eds, 'fgon edges and', total_nor_eds, 'non fgon edges' 377 @type flag: int 378 @ivar index: The edge's index within the mesh. Read-only. 379 @type index: int 380 @ivar sel: The edge's B{edit mode} selection state (selected=1). B{Note}: 381 changing the select state of an edge changes the select state of the edge's 382 vertices. 383 @type sel: int 384 @ivar key: The edge's vert indices in an ordered tuple, which can be used 385 as a dictionary key. Read-only. 386 This is the same as (min(ed.v1.index, ed.v2.index), max(ed.v1.index, ed.v2.index)) 387 @type key: tuple 388 """ 389

390 - def __iter__():

391 """ 392 Iterator for MEdge. It iterates over the MVerts of the edge, returning 393 v1 then v2. 394 @return: one of the edge's vertices 395 @rtype: MVert 396 """

397

398 -class MEdgeSeq:

399 """ 400 The MEdgeSeq object 401 =================== 402 This object provides sequence and iterator access to the mesh's edges. 403 """ 404

405 - def extend(vertseq):

406 """ 407 Add zero or more edges to the mesh. Edges which already exist in the 408 mesh or with both vertices the same are ignored. If three or four verts 409 are specified in any sequence, an edge is also created between the first 410 and last vertices (this is useful when adding faces). 411 @note: Since Blender 2.44 all new edges are selected. 412 413 Example:: 414 import Blender 415 from Blender import Mesh 416 417 me = Mesh.Get("Plane") # get the mesh data called "Plane" 418 v = me.verts # get vertices 419 if len(v) >= 6: # if there are enough vertices... 420 me.edges.extend(v[0],v[1]) # add a single edge 421 l=[(v[1],v[2],v[3]),[0,2,4,5]] 422 me.edges.extend(l) # add multiple edges 423 424 @type vertseq: sequence(s) of ints or MVerts 425 @param vertseq: either two to four ints or MVerts, or sequence 426 (list or tuple) of sequences each containing two to four ints or MVerts. 427 """

428

429 - def delete(edges):

430 """ 431 Deletes one or more edges from the mesh. In addition, also delete: 432 - any faces which uses the specified edge(s) 433 - any "orphan" vertices (belonging only to specified edge(s)) 434 435 @type edges: multiple ints or MEdges 436 @param edges: can be 437 - a single MEdge belonging to the mesh 438 - a single integer, specifying an index into the mesh's edge list 439 - a sequence (list or tuple) containing two or more of either of 440 the above. 441 """

442

443 - def selected():

444 """ 445 Get selected edges. 446 Selected edges are those for which both vertices are selected. 447 @return: a list of the indices for all edges selected in edit mode. 448 @rtype: list of ints 449 """

450

451 -class MFace:

452 """ 453 The MFace object 454 ================ 455 This object holds mesh face data. 456 457 Example:: 458 import Blender 459 from Blender import Mesh, Window 460 461 in_emode = Window.EditMode() 462 if in_emode: Window.EditMode(0) 463 464 me = Mesh.Get("Mesh") 465 faces = me.faces 466 467 ## Example for editmode faces selection: 468 selected_faces = [] 469 for f in faces: 470 if f.sel: 471 selected_faces.append(f) 472 # ... unselect selected and select all the others: 473 for f in faces: 474 f.sel = not f.sel # 1 becomes 0, 0 becomes 1 475 476 ## Example for UV textured faces selection: 477 selected_faces = [] 478 SEL = Mesh.FaceFlags['SELECT'] 479 # get selected faces: 480 for f in faces: 481 if f.flag & SEL: 482 selected_faces.append(f) 483 # ... unselect selected and select all the others: 484 for f in faces: 485 if f.flag & SEL: 486 f.flag &= ~SEL # unselect these 487 else: 488 f.flag |= SEL # and select these 489 490 if in_emode: Window.EditMode(1) 491 Blender.Redraw() 492 493 @ivar verts: The face's vertices. Each face has 3 or 4 vertices. 494 @type verts: list of MVerts 495 @ivar v: Same as L{verts}. This attribute is only for compatibility with 496 NMesh scripts and will probably be deprecated in the future. 497 @ivar sel: The face's B{edit mode} selection state (selected=1). 498 This is not the same as the selection state of the textured faces 499 (see L{flag}). B{Note}: changing the select state of a face changes 500 the select state of the face's vertices. 501 @type sel: int 502 @ivar hide: The face's B{edit mode} visibility state (hidden=1). 503 This is not the same as the visibility state of 504 the textured faces (see L{flag}). 505 @type hide: int 506 @ivar smooth: If set, the vertex normals are averaged to make this 507 face look smooth. (This is the same as choosing "Set Smooth" in the 508 Editing Panel (F9) under "Link and Material" properties). 509 @type smooth: int 510 @ivar col: The face's vertex colors, if defined. Each vertex has its own 511 color. 512 Will throw an exception if L{Mesh.vertexColors} is False. 513 514 Example:: 515 # This example uses vertex normals to apply normal colors to each face. 516 import bpy 517 from Blender import Window 518 scn= bpy.scenes.active # Current scene, important to be scene aware 519 ob= scn.objects.active # last selected object 520 me= ob.getData(mesh=1) # thin wrapper doesn't copy mesh data like nmesh 521 me.vertexColors= True # Enable face, vertex colors 522 for f in me.faces: 523 for i, v in enumerate(f): 524 no= v.no 525 col= f.col[i] 526 col.r= int((no.x+1)*128) 527 col.g= int((no.y+1)*128) 528 col.b= int((no.z+1)*128) 529 Window.RedrawAll() 530 @type col: tuple of MCols 531 @ivar mat: The face's index into the mesh's materials 532 list. It is in the range [0,15]. 533 @type mat: int 534 @ivar image: The Image used as a texture for this face. 535 Setting this attribute will create UV faces if they do not exist. 536 Getting this attribute throw an exception if the mesh does not have 537 UV faces; use L{Mesh.faceUV} to test. 538 Assigning an image will automatically set the TEX attribute of the 539 L{mode} bitfield. Use "del f.image" or "f.image = None" to clear the 540 image assigned to the face. 541 @type image: Image 542 @ivar mode: The texture mode bitfield (see L{FaceModes}). 543 Will throw an exception if the mesh does not have UV faces; use 544 L{Mesh.faceUV} to test. 545 @type mode: int 546 @ivar index: The face's index within the mesh. Read-only. 547 @type index: int 548 549 @ivar flag: The face's B{texture mode} flags; indicates the selection, 550 active , and visibility states of a textured face (see 551 L{FaceFlags} for values). 552 This is not the same as the selection or visibility states of 553 the faces in edit mode (see L{sel} and L{hide}). 554 To set the active face, use 555 the L{Mesh.activeFace} attribute instead. 556 Will throw an exception if the mesh does not have UV faces; use 557 L{Mesh.faceUV} to test. 558 559 @ivar transp: Transparency mode. It is one of the values in 560 L{FaceTranspModes}). 561 Will throw an exception if the mesh does not have UV faces; use 562 L{Mesh.faceUV} to test. 563 @type transp: int 564 565 @ivar uv: The face's UV coordinates. Each vertex has its own UV coordinate. 566 Setting this attribute will create UV faces if they do not exist. 567 Getting this attribute throw an exception if the mesh does not have 568 UV faces; use L{Mesh.faceUV} to test. 569 @type uv: tuple of vectors (WRAPPED DATA) 570 @ivar uvSel: The face's UV coordinates selection state; a 1 indicates the 571 vertex is selected. Each vertex has its own UV coordinate select state 572 (this is not the same as the vertex's edit mode selection state). 573 Setting this attribute will create UV faces if they do not exist. 574 Getting this attribute throw an exception if the mesh does not have 575 UV faces; use L{Mesh.faceUV} to test. 576 @type uvSel: tuple of ints 577 @ivar no: The face's normal vector (x, y, z). Read-only. 578 @type no: vector 579 @ivar cent: The center of the face. Read-only. 580 @type cent: vector 581 @ivar area: The area of the face. Read-only. 582 @type area: float 583 @ivar edge_keys: A tuple, each item a key that can reference an edge by its 584 ordered indices. Read-only. This is useful for building connectivity data. 585 Example:: 586 from Blender import Mesh 587 me = Mesh.Get('Cube') 588 # a dictionary where the edge is the key, and a list of faces that use it are the value 589 edge_faces = dict([(ed.key, []) for ed in me.edges]) 590 591 # Add the faces to the dict 592 for f in me.faces: 593 for key in f.edge_keys: 594 edge_faces[key].append(f) # add this face to the edge as a user 595 596 # Print the edges and the number of face users 597 for key, face_users in edge_faces.iteritems(): 598 print 'Edge:', key, 'uses:', len(face_users),'faces' 599 600 @type edge_keys: tuple 601 @note: there are regular faces and textured faces in Blender, both currently 602 with their own selection and visibility states, due to a mix of old and new 603 code. To (un)select or (un)hide regular faces (visible in EditMode), use 604 L{MFace.sel} and L{MFace.hide} attributes. For textured faces (UV Face 605 Select and Paint modes in Blender) use the L{MFace.flag} attribute. 606 Check the example above and note L{Window.EditMode}. 607 @note: Assigning UV textures to mesh faces in Blender works like this: 608 1. Select your mesh. 609 2. Enter face select mode (press f) and select at least some face(s). 610 3. In the UV/Image Editor window, load / select an image. 611 4. Play in both windows (better split the screen to see both at the same 612 time) until the UV coordinates are where you want them. Hint: in the 613 3D window, the 'u' key opens a menu of default UV choices and the 'r' 614 key lets you rotate the UV coords. 615 5. Leave face select mode (press f). 616 """ 617

618 - def __iter__():

619 """ 620 Iterator for MVert. It iterates over the MVerts of the face, returning 621 v1, v2, v3 (and optionally v4); 622 @return: one of the face's vertices 623 @rtype: MVert 624 """

625

626 - def __len__():

627 """ 628 len for MVert. It returns the number of vertices in the face. 629 @rtype: int 630 """

631

632 -class MFaceSeq:

633 """ 634 The MFaceSeq object 635 =================== 636 This object provides sequence and iterator access to the mesh's faces. 637 """ 638

639 - def extend(vertseq,ignoreDups=True,indexList=True,smooth=False):

640 """ 641 Add zero or more faces and edges to the mesh. Faces which already exist 642 in the mesh, or faces which contain the same vertex multiple times are 643 ignored. Sequences of two vertices are accepted, but no face will be 644 created. 645 @note: Since Blender 2.44 all new faces are selected. 646 647 Example:: 648 import Blender 649 from Blender import Mesh 650 651 me = Mesh.Get("Plane") # get the mesh data called "Plane" 652 v = me.verts # get vertices 653 if len(v) >= 6: # if there are enough vertices... 654 me.faces.extend(v[1],v[2],v[3]) # add a single edge 655 l=[(v[0],v[1]),[0,2,4,5]] 656 me.faces.extend(l) # add another face 657 658 @type vertseq: sequence(s) of MVerts 659 @param vertseq: either two to four ints or MVerts, or sequence (list or 660 tuple) of sequences each containing two to four ints or MVerts. 661 @type ignoreDups: boolean 662 @param ignoreDups: keyword parameter (default is False). If supplied and 663 True, do not check the input list or mesh for duplicate faces. This can 664 speed up scripts but can prossibly produce undesirable effects. Only 665 use if you know what you're doing. 666 @type indexList: boolean 667 @param indexList: keyword parameter (default is False). If supplied and 668 True, the method will return a list representing the new index for each 669 face in the input list. If faces are removed as duplicates, None is 670 inserted in place of the index. 671 @type smooth: boolean 672 @param smooth: keyword parameter (default is False). If supplied new faces will have smooth enabled. 673 @warning: Faces using the first vertex at the 3rd or 4th location in the 674 face's vertex list will have their order rotated so that the zero index 675 on in the first or second location in the face. When creating face data 676 with UVs or vertex colors, you may need to work around this, either by 677 checking for zero indices yourself or by adding a dummy first vertex to 678 the mesh that can be removed when your script has finished. 679 """

680

681 - def delete(deledges, faces):

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

695

696 - def sort():

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

711

712 - def selected():

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

718 719 from IDProp import IDGroup, IDArray

720 -class Mesh:

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

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

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

834

835 - def calcNormals():

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

839

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

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

850 - def getTangents():

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

887 888

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

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

930

931 - def vertexShade(object):

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

940

941 - def update(key=None):

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

958

959 - def findEdges(edges):

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

970

971 - def addVertGroup(group):

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

981

982 - def removeVertGroup(group):

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

992

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

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

1026

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

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

1037

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

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

1063

1064 - def renameVertGroup(groupName, newName):

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

1072

1073 - def getVertGroupNames():

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

1080

1081 - def getUVLayerNames():

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

1088

1089 - def getColorLayerNames():

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

1096

1097 - def getVertexInfluences(index):

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

1106

1107 - def removeAllKeys():

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

1113

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

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

1131

1132 - def addUVLayer(name):

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

1138

1139 - def addColorLayer(name):

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

1145

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

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

1154

1155 - def removeUVLayer(name):

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

1161

1162 - def removeColorLayer(name):

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

1168

1169 - def renameUVLayer(name, newname):

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

1177

1178 - def renameColorLayer(name, newname):

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

1186

1187 - def smooth():

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

1192

1193 - def flipNormals():

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

1198

1199 - def toSphere():

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

1205

1206 - def fill():

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

1211

1212 - def triangleToQuad():

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

1217

1218 - def quadToTriangle(mode=0):

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

1226

1227 - def subdivide(beauty=0):

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

1235

1236 - def remDoubles(limit):

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

1246

1247 - def recalcNormals(direction=0):

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

1256

1257 - def __copy__ ():

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

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

Source Code for Module Mesh