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 - CLIP - Clipped alpha. 89 @var EdgeFlags: The available edge flags. 90 - SELECT - selected (B{deprecated}). Use edge.sel attribute instead. 91 - EDGEDRAW - edge is drawn out of edition mode. 92 - EDGERENDER - edge is drawn out of edition mode. 93 - SEAM - edge is a seam for UV unwrapping 94 - FGON - edge is part of a F-Gon. 95 - LOOSE - Edge is not a part of a face (only set on leaving editmode) 96 - SHARP - Edge will be rendered sharp when used with the "Edge Split" modifier. 97 @type AssignModes: readonly dictionary. 98 @var AssignModes: The available vertex group assignment modes, used by 99 L{mesh.assignVertsToGroup()<Mesh.Mesh.assignVertsToGroup>}. 100 - ADD: if the vertex in the list is not assigned to the group 101 already, this creates a new association between this vertex and the 102 group with the weight specified, otherwise the weight given is added to 103 the current weight of an existing association between the vertex and 104 group. 105 - SUBTRACT: will attempt to subtract the weight passed from a vertex 106 already associated with a group, else it does nothing.\n 107 - REPLACE: attempts to replace a weight with the new weight value 108 for an already associated vertex/group, else it does nothing. 109 @type SelectModes: readonly dictionary. 110 @var SelectModes: The available edit select modes. 111 - VERTEX: vertex select mode. 112 - EDGE: edge select mode. 113 - FACE: face select mode. 114 """ 115 116 AssignModes = {'REPLACE':1} 117

118 -def Get(name=None):

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

127

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

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

138

139 -def Mode(mode=0):

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

151

152 -def Unlink(name):

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

163

164 -class MCol:

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

178

179 -class MVert:

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

230 - def __init__(coord):

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

256

257 -class MVertSeq:

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

302 - def extend(coords):

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

325

326 - def delete(verts):

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

339

340 - def selected():

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

346

347 -class MEdge:

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

391 - def __iter__():

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

398

399 -class MEdgeSeq:

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

406 - def extend(vertseq):

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

429

430 - def delete(edges):

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

443

444 - def selected():

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

451

452 -class MFace:

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

619 - def __iter__():

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

626

627 - def __len__():

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

632

633 -class MFaceSeq:

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

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

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

681

682 - def delete(deledges, faces):

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

696

697 - def sort():

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

712

713 - def selected():

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

719 720 from IDProp import IDGroup, IDArray

721 -class Mesh:

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

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

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

835

836 - def calcNormals():

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

840

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

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

851 - def getTangents():

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

888 889

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

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

931

932 - def vertexShade(object):

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

941

942 - def update(key=None):

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

959

960 - def findEdges(edges):

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

971

972 - def addVertGroup(group):

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

982

983 - def removeVertGroup(group):

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

993

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

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

1027

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

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

1038

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

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

1064

1065 - def renameVertGroup(groupName, newName):

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

1073

1074 - def getVertGroupNames():

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

1081

1082 - def getUVLayerNames():

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

1089

1090 - def getColorLayerNames():

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

1097

1098 - def getVertexInfluences(index):

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

1107

1108 - def removeAllKeys():

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

1114

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

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

1132

1133 - def addUVLayer(name):

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

1139

1140 - def addColorLayer(name):

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

1146

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

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

1155

1156 - def removeUVLayer(name):

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

1162

1163 - def removeColorLayer(name):

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

1169

1170 - def renameUVLayer(name, newname):

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

1178

1179 - def renameColorLayer(name, newname):

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

1187

1188 - def smooth():

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

1193

1194 - def flipNormals():

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

1199

1200 - def toSphere():

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

1206

1207 - def fill():

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

1212

1213 - def triangleToQuad():

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

1218

1219 - def quadToTriangle(mode=0):

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

1227

1228 - def subdivide(beauty=0):

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

1236

1237 - def remDoubles(limit):

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

1247

1248 - def recalcNormals(direction=0):

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

1257

1258 - def __copy__ ():

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

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

Source Code for Module Mesh