Module NMesh

Source Code for Module NMesh

  1  # Blender.NMesh module and the NMesh PyType object 
  2   
  3  """ 
  4  The Blender.NMesh submodule. 
  5   
  6  B{Deprecated}: 
  7  This module is now maintained but not actively developed. 
  8   
  9  Access to data such as properties, library, UVLayers and ColorLayers is not available 
 10  further more, a mesh modified with NMesh will destroy inactive UV and Color layers 
 11  so writing tools that use NMesh is discouraged. 
 12   
 13  Use L{Mesh} instead. 
 14   
 15  Mesh Data 
 16  ========= 
 17   
 18  This module provides access to B{Mesh Data} objects in Blender. 
 19   
 20  Example:: 
 21   
 22    import Blender 
 23    from Blender import NMesh, Material, Window 
 24   
 25    editmode = Window.EditMode()    # are we in edit mode?  If so ... 
 26    if editmode: Window.EditMode(0) # leave edit mode before getting the mesh 
 27   
 28    me = NMesh.GetRaw("Plane")       # get the mesh data called "Plane" 
 29   
 30    if not me.materials:             # if there are no materials ... 
 31      newmat = Material.New()        # create one ... 
 32      me.materials.append(newmat)    # and append it to the mesh's list of mats 
 33   
 34    print me.materials               # print the list of materials 
 35    mat = me.materials[0]            # grab the first material in the list 
 36    mat.R = 1.0                      # redefine its red component 
 37    for v in me.verts:               # loop the list of vertices 
 38      v.co[0] *= 2.5                 # multiply the coordinates 
 39      v.co[1] *= 5.0 
 40      v.co[2] *= 2.5 
 41    me.update()                      # update the real mesh in Blender 
 42   
 43    if editmode: Window.EditMode(1)  # optional, just being nice 
 44   
 45  @type Modes: readonly dictionary 
 46  @type FaceFlags: readonly dictionary 
 47  @type FaceModes: readonly dictionary 
 48  @type FaceTranspModes: readonly dictionary 
 49  @var Modes: The available mesh modes. 
 50      - NOVNORMALSFLIP - no flipping of vertex normals during render. 
 51      - TWOSIDED - double sided mesh. 
 52      - AUTOSMOOTH - turn auto smoothing of faces "on". 
 53  @var FaceFlags: The available *texture face* (uv face select mode) selection 
 54    flags.  Note: these refer to TexFace faces, available if nmesh.hasFaceUV() 
 55    returns true. 
 56      - SELECT - selected (deprecated after 2.43 release, use face.sel). 
 57      - HIDE - hidden (deprecated after 2.43 release, use face.sel). 
 58      - ACTIVE - the active face. 
 59  @var FaceModes: The available *texture face* modes. Note: these are only 
 60    meaningful if nmesh.hasFaceUV() returns true, since in Blender this info is 
 61    stored at the TexFace (TexFace button in Edit Mesh buttons) structure. 
 62      - ALL - set all modes at once. 
 63      - BILLBOARD - always orient after camera. 
 64      - HALO - halo face, always point to camera. 
 65      - DYNAMIC - respond to collisions. 
 66      - INVISIBLE - invisible face. 
 67      - LIGHT - dynamic lighting. 
 68      - OBCOL - use object color instead of vertex colors. 
 69      - SHADOW - shadow type. 
 70      - SHAREDVERT - apparently unused in Blender. 
 71      - SHAREDCOL - shared vertex colors (per vertex). 
 72      - TEX - has texture image. 
 73      - TILES - uses tiled image. 
 74      - TWOSIDE - two-sided face. 
 75  @var FaceTranspModes: The available face transparency modes. Note: these are 
 76    enumerated values (enums), they can't be combined (ANDed, ORed, etc) like a bit vector. 
 77      - SOLID - draw solid. 
 78      - ADD - add to background (halo). 
 79      - ALPHA - draw with transparency. 
 80      - SUB - subtract from background. 
 81  @var EdgeFlags: The available edge flags. 
 82      - SELECT - selected. 
 83      - EDGEDRAW - edge is drawn out of edition mode. 
 84      - SEAM - edge is a seam for UV unwrapping 
 85      - FGON - edge is part of a F-Gon. 
 86  """ 
 87   
88 -def Col(col = [255, 255, 255, 255]):
89 """ 90 Get a new mesh rgba color. 91 @type col: list 92 @param col: A list [red, green, blue, alpha] of integer values in [0, 255]. 93 @rtype: NMCol 94 @return: A new NMCol (mesh rgba color) object. 95 """
96
97 -def Vert(x = 0, y = 0, z = 0):
98 """ 99 Get a new vertex object. 100 @type x: float 101 @type y: float 102 @type z: float 103 @param x: The x coordinate of the vertex. 104 @param y: The y coordinate of the vertex. 105 @param z: The z coordinate of the vertex. 106 @rtype: NMVert 107 @return: A new NMVert object. 108 """
109
110 -def Face(vertexList = None):
111 """ 112 Get a new face object. 113 @type vertexList: list 114 @param vertexList: A list of B{up to 4} NMVerts (mesh vertex 115 objects). 116 @rtype: NMFace 117 @return: A new NMFace object. 118 """
119
120 -def New(name = 'Mesh'):
121 """ 122 Create a new mesh object. 123 @type name: string 124 @param name: An optional name for the created mesh. 125 rtype: NMesh 126 @return: A new (B{empty}) NMesh object. 127 """
128
129 -def GetRaw(name = None):
130 """ 131 Get the mesh data object called I{name} from Blender. 132 @type name: string 133 @param name: The name of the mesh data object. 134 @rtype: NMesh 135 @return: It depends on the 'name' parameter: 136 - (name) - The NMesh wrapper of the mesh called I{name}, 137 None if not found. 138 - () - A new (empty) NMesh object. 139 """
140
141 -def GetNames():
142 """ 143 Get a list with the names of all available meshes in Blender. 144 @rtype: list of strings 145 @return: a list of mesh names. 146 @note: to get actual mesh data, pass a mesh name to L{GetRaw}. 147 """
148
149 -def GetRawFromObject(name):
150 """ 151 Get the raw mesh data object from the Object in Blender called I{name}.\n 152 Note: The mesh coordinates are in local space, not the world space of its Object.\n 153 For world space vertex coordinates, each vertex location must be multiplied by the object's 4x4 matrix. 154 This function support all the geometry based objects: Mesh, Text, Surface, Curve, Meta. 155 @type name: string 156 @param name: The name of an Object. 157 @rtype: NMesh 158 @return: The NMesh wrapper of the mesh data from the Object called I{name}. 159 @note: For "subsurfed" meshes, it's the B{display} level of subdivision that 160 matters, the rendering one is only processed at the rendering pre-stage 161 and is not available for scripts. This is not a problem at all, since 162 you can get and set the subdivision levels via scripting, too (see 163 L{NMesh.NMesh.getSubDivLevels}, L{NMesh.NMesh.setSubDivLevels}). 164 @note: Meshes extracted from curve based objects (Font/2D filled curves) 165 contain both the filled surfaces and the outlines of the shapes. 166 @warn: This function gets I{deformed} mesh data, already modified for 167 displaying (think "display list"). It also doesn't let you overwrite the 168 original mesh in Blender, so if you try to update it, a new mesh will 169 be created. 170 @warn: For Meta Object's, this function will only return a NMesh with some geometry 171 when called on the base element (the one with the shortest name). 172 """
173
174 -def PutRaw(nmesh, name = None, recalc_normals = 1, store_edges = 0):
175 """ 176 Put a BPython NMesh object as a mesh data object in Blender. 177 @note: if there is already a mesh with the given 'name', its contents are 178 freed and the new data is put in it. Also, if this mesh is not linked to any 179 object, a new object for it is created. Reminder: in Blender an object is 180 composed of the base object and linked object data (mesh, metaball, camera, 181 etc. etc). 182 @type nmesh: NMesh 183 @type name: string 184 @type recalc_normals: int 185 @type store_edges: int 186 @param name: The name of the mesh data object in Blender which will receive 187 this nmesh data. It can be an existing mesh data object or a new one. 188 @param recalc_normals: If non-zero, the vertex normals for the mesh will 189 be recalculated. 190 @param store_edges: deprecated, edges are always stored now. 191 @rtype: None or Object 192 @return: It depends on the 'name' parameter: 193 - I{name} refers to an existing mesh data obj already linked to an 194 object: return None. 195 - I{name} refers to a new mesh data obj or an unlinked (no users) one: 196 return the created Blender Object wrapper. 197 """
198
199 -class NMCol:
200 """ 201 The NMCol object 202 ================ 203 This object is a list of ints: [r, g, b, a] representing an 204 rgba color. 205 @ivar r: The Red component in [0, 255]. 206 @ivar g: The Green component in [0, 255]. 207 @ivar b: The Blue component in [0, 255]. 208 @ivar a: The Alpha (transparency) component in [0, 255]. 209 """
210
211 -class NMVert:
212 """ 213 The NMVert object 214 ================= 215 This object holds mesh vertex data. 216 @type co: 3D Vector object. (WRAPPED DATA) 217 @ivar co: The vertex coordinates (x, y, z). 218 @type no: 3D Vector object. (unit length) (WRAPPED DATA) 219 @ivar no: The vertex normal vector (x, y, z). 220 @type uvco: 3D Vector object. (WRAPPED DATA) 221 @ivar uvco: The vertex texture "sticky" coordinates. The Z value of the Vector is ignored. 222 @type index: int 223 @ivar index: The vertex index, if owned by a mesh. 224 @type sel: int 225 @ivar sel: The selection state (selected:1, unselected:0) of this vertex.\n 226 Note: An NMesh will return the selection state of the mesh when EditMod was last exited. A python script operating in EditMode must exit edit mode, before getting the current selection state of the mesh. 227 @warn: There are two kinds of uv texture coordinates in Blender: per vertex 228 ("sticky") and per face vertex (uv in L{NMFace}). In the first, there's 229 only one uv pair of coordinates for each vertex in the mesh. In the 230 second, for each face it belongs to, a vertex can have different uv 231 coordinates. This makes the per face option more flexible, since two 232 adjacent faces won't have to be mapped to a continuous region in an image: 233 each face can be independently mapped to any part of its texture. 234 """
235
236 -class NMEdge:
237 """ 238 The NMEdge object 239 ================= 240 This object holds mesh edge data. 241 @type v1: NMVert 242 @ivar v1: The first vertex of the edge. 243 @type v2: NMVert 244 @ivar v2: The second vertex of the edge. 245 @type crease: int 246 @ivar crease: The crease value of the edge. It is in the range [0,255]. 247 @type flag: int 248 @ivar flag: The bitmask describing edge properties. See L{NMesh.EdgeFlags<EdgeFlags>}. 249 """
250
251 -class NMFace:
252 """ 253 The NMFace object 254 ================= 255 This object holds mesh face data. 256 257 Example:: 258 import Blender 259 from Blender import NMesh, Window 260 261 in_emode = Window.EditMode() 262 if in_emode: Window.EditMode(0) 263 264 me = NMesh.GetRaw("Mesh") 265 faces = me.faces 266 267 ## Example for editmode faces selection: 268 selected_faces = [] 269 for f in faces: 270 if f.sel: 271 selected_faces.append(f) 272 # ... unselect selected and select all the others: 273 for f in faces: 274 f.sel = 1 - f.sel # 1 becomes 0, 0 becomes 1 275 276 ## Example for uv textured faces selection: 277 selected_faces = [] 278 SEL = NMesh.FaceFlags['SELECT'] 279 # get selected faces: 280 for f in faces: 281 if f.flag & SEL: 282 selected_faces.append(f) 283 # ... unselect selected and select all the others: 284 for f in faces: 285 if f.flag & SEL: 286 f.flag &=~SEL # unselect these 287 else: f.flag |= SEL # and select these 288 289 me.update() 290 if in_emode: Window.EditMode(1) 291 Blender.Redraw() 292 293 @type v: list 294 @ivar v: The list of face vertices (B{up to 4}). 295 @type sel: bool 296 @ivar sel: The selection state (1: selected, 0: unselected) of this NMesh's 297 faces *in edit mode*. This is not the same as the selection state of 298 the textured faces (see L{flag}). 299 @type hide: bool 300 @ivar hide: The visibility state (1: hidden, 0: visible) of this NMesh's 301 faces *in edit mode*. This is not the same as the visibility state of 302 the textured faces (see L{flag}). 303 @ivar col: The list of vertex colors. 304 @ivar mat: Same as I{materialIndex} below. 305 @ivar materialIndex: The index of this face's material in its NMesh materials 306 list. 307 @ivar smooth: If non-zero, the vertex normals are averaged to make this 308 face look smooth. 309 @ivar image: The Image used as a texture for this face. 310 @ivar mode: The display mode (see L{Mesh.FaceModes<FaceModes>}) 311 @ivar flag: Bit vector specifying selection / visibility flags for uv 312 textured faces (visible in Face Select mode, see 313 L{NMesh.FaceFlags<FaceFlags>}). 314 @ivar transp: Transparency mode bit vector 315 (see L{NMesh.FaceTranspModes<FaceTranspModes>}). 316 @ivar uv: List of per-face UV coordinates: [(u0, v0), (u1, v1), ...]. 317 @ivar normal: (or just B{no}) The normal vector for this face: [x,y,z]. 318 @note: there are normal faces and textured faces in Blender, both currently 319 with their own selection and visibility states, due to a mix of old and new 320 code. To (un)select or (un)hide normal faces (visible in editmode), use 321 L{sel} and L{hide} variables. For textured faces (Face Select 322 mode in Blender) use the old L{flag} bitflag. Also check the 323 example above and note L{Window.EditMode}. 324 @note: Assigning uv textures to mesh faces in Blender works like this: 325 1. Select your mesh. 326 2. Enter face select mode (press f) and select at least some face(s). 327 3. In the UV/Image Editor window, load / select an image. 328 4. Play in both windows (better split the screen to see both at the same 329 time) until the uv coordinates are where you want them. Hint: in the 330 3d window, the 'u' key opens a menu of default uv choices and the 'r' 331 key lets you rotate the uv coordinates. 332 5. Leave face select mode (press f). 333 """ 334
335 - def append(vertex):
336 """ 337 Append a vertex to this face's vertex list. 338 @type vertex: NMVert 339 @param vertex: An NMVert object. 340 """
341 342 from IDProp import IDGroup, IDArray
343 -class NMesh:
344 """ 345 The NMesh Data object 346 ===================== 347 This object gives access to mesh data in Blender. We refer to mesh as the 348 object in Blender and NMesh as its Python counterpart. 349 @ivar properties: Returns an L{IDGroup<IDProp.IDGroup>} reference to this 350 object's ID Properties. 351 @type properties: L{IDGroup<IDProp.IDGroup>} 352 @ivar name: The NMesh name. It's common to use this field to store extra 353 data about the mesh (to be exported to another program, for example). 354 @ivar materials: The list of materials used by this NMesh. See 355 L{getMaterials} for important details. 356 @ivar verts: The list of NMesh vertices (NMVerts). 357 @ivar users: The number of Objects using (linked to) this mesh. 358 @ivar faces: The list of NMesh faces (NMFaces). 359 @ivar edges: A list of L{NMEdge} edges. 360 @ivar mode: The mode flags for this mesh. See L{setMode}. 361 @ivar subDivLevels: The [display, rendering] subdivision levels in [1, 6]. 362 @ivar maxSmoothAngle: The max angle for auto smoothing. See L{setMode}. 363 @cvar key: The L{Key.Key} object attached to this mesh, if any. 364 """ 365
366 - def addEdge(v1, v2):
367 """ 368 Create an edge between two vertices. 369 If an edge already exists between those vertices, it is returned. 370 Created edge is automatically added to edges list. 371 You can only call this method if mesh has edge data. 372 @note: In Blender only zero or one edge can link two vertices. 373 @type v1: NMVert 374 @param v1: the first vertex of the edge. 375 @type v2: NMVert 376 @param v2: the second vertex of the edge. 377 @rtype: NMEdge 378 @return: The created or already existing edge. 379 """
380
381 - def findEdge(v1, v2):
382 """ 383 Try to find an edge between two vertices. 384 If no edge exists between v1 and v2, None is returned. 385 You can only call this method if mesh has edge data. 386 @type v1: NMVert 387 @param v1: the first vertex of the edge. 388 @type v2: NMVert 389 @param v2: the second vertex of the edge. 390 @rtype: NMEdge 391 @return: The found edge. None if no edge was found. 392 """
393
394 - def removeEdge(v1, v2):
395 """ 396 Remove an edge between two vertices. 397 All faces using this edge are removed from faces list. 398 You can only call this method if mesh has edge data. 399 @type v1: NMVert 400 @param v1: the first vertex of the edge. 401 @type v2: NMVert 402 @param v2: the second vertex of the edge. 403 """
404
405 - def addFace(face):
406 """ 407 Add a face to face list and add to edge list (if edge data exists) necessary edges. 408 @type face: NMFace 409 @param face: the face to add to the mesh. 410 @rtype: list of NMEdge 411 @return: If mesh has edge data, return the list of face edges. 412 """
413
414 - def removeFace(face):
415 """ 416 Remove a face for face list and remove edges no more used by any other face (if edge data exists). 417 @type face: NMFace 418 @param face: the face to add to the mesh. 419 """
420
421 - def addMaterial(material):
422 """ 423 Add a new material to this NMesh's list of materials. This method is the 424 slower but safer way to add materials, since it checks if the argument 425 given is really a material, imposes a limit of 16 materials and only adds 426 the material if it wasn't already in the list. 427 @type material: Blender Material 428 @param material: A Blender Material. 429 """
430
431 - def getMaterials(what = -1):
432 """ 433 Get this NMesh's list of materials. 434 @type what: int 435 @param what: determines the list's contents: 436 - -1: return the current NMesh's list; 437 - 0: retrieve a fresh list from the Blender mesh -- eventual 438 modifications made by the script not included, unless 439 L{update} is called before this method; 440 - 1: like 0, but empty slots are not ignored, they are returned as 441 None's. 442 @note: what >= 0 also updates nmesh.materials attribute. 443 @rtype: list of materials 444 @return: the requested list of materials. 445 @note: if a user goes to the material buttons window and removes some 446 mesh's link to a material, that material slot becomes empty. 447 Previously such materials were ignored. 448 @note: L{Object.colbits<Object.Object.colbits>} needs to be set correctly 449 for each object in order for these materials to be used instead of 450 the object's materials. 451 """
452
453 - def setMaterials(matlist):
454 """ 455 Set this NMesh's list of materials. This method checks the consistency of 456 the passed list: must only have materials or None's and can't contain more 457 than 16 entries. 458 @type matlist: list of materials 459 @param matlist: a list with materials, None's also accepted (they become 460 empty material slots in Blender. 461 @note: L{Object.colbits<Object.Object.colbits>} needs to be set correctly 462 for each object in order for these materials to be used instead of 463 the object's materials. 464 """
465
466 - def hasVertexColours(flag = None):
467 """ 468 Get (and optionally set) if this NMesh has vertex colors. 469 @type flag: int 470 @param flag: If given and non-zero, the "vertex color" flag for this NMesh 471 is turned I{on}. 472 @rtype: bool 473 @return: The current value of the "vertex color" flag. 474 @warn: If a mesh has both vertex colors and textured faces, this function 475 will return False. This is due to the way Blender deals internally with 476 the vertex colors array (if there are textured faces, it is copied to 477 the textured face structure and the original array is freed/deleted). 478 If you want to know if a mesh has both textured faces and vertex 479 colors, set *in Blender* the "VCol Paint" flag for each material that 480 covers an area that was also vertex painted and then check in your 481 Python script if that material flag is set. Of course also tell others 482 who use your script to do the same. The "VCol Paint" material mode flag 483 is the way to tell Blender itself to render with vertex colors, too, so 484 it's a natural solution. 485 """
486
487 - def hasFaceUV(flag = None):
488 """ 489 Get (and optionally set) if this NMesh has UV-mapped textured faces. 490 @type flag: int 491 @param flag: If given and non-zero, the "textured faces" flag for this 492 NMesh is turned I{on}. 493 @rtype: bool 494 @return: The current value of the "textured faces" flag. 495 """
496
497 - def hasVertexUV(flag = None):
498 """ 499 Get (and optionally set) the "sticky" flag that controls if a mesh has 500 per vertex UV coordinates. 501 @type flag: int 502 @param flag: If given and non-zero, the "sticky" flag for this NMesh is 503 turned I{on}. 504 @rtype: bool 505 @return: The current value of the "sticky" flag. 506 """
507
508 - def getActiveFace():
509 """ 510 Get the index of the active face. 511 @rtype: int 512 @return: The index of the active face. 513 """
514
515 - def getSelectedFaces(flag = None):
516 """ 517 Get list of selected faces. 518 @type flag: int 519 @param flag: If given and non-zero, the list will have indices instead of 520 the NMFace objects themselves. 521 @rtype: list 522 @return: It depends on the I{flag} parameter: 523 - if None or zero: List of NMFace objects. 524 - if non-zero: List of indices to NMFace objects. 525 @warn: this method exists to speed up retrieving of selected faces from 526 the actual mesh in Blender. So, if you make changes to the nmesh, you 527 need to L{update} it before using this method. 528 """
529
530 - def getVertexInfluences(index):
531 """ 532 Get influences of bones in a specific vertex. 533 @type index: int 534 @param index: The index of a vertex. 535 @rtype: list of lists 536 @return: List of pairs (name, weight), where name is the bone name (string) 537 and its weight is a float value. 538 """
539
540 - def getKey():
541 """ 542 Get the Key object representing the Vertex Keys (absolute or 543 relative) assigned to this mesh. 544 @rtype: L{Key.Key} object or None 545 """
546
547 - def insertKey(frame = None, type = 'relative'):
548 """ 549 Insert a mesh key at the given frame. Remember to L{update} the nmesh 550 before doing this, or changes in the vertices won't be updated in the 551 Blender mesh. 552 @type frame: int 553 @type type: string 554 @param frame: The Scene frame where the mesh key should be inserted. If 555 None, the current frame is used. 556 @param type: The mesh key type: 'relative' or 'absolute'. This is only 557 relevant on the first call to insertKey for each nmesh (and after all 558 keys were removed with L{removeAllKeys}, of course). 559 @warn: This and L{removeAllKeys} were included in this release only to 560 make accessing vertex keys possible, but may not be a proper solution 561 and may be substituted by something better later. For example, it 562 seems that 'frame' should be kept in the range [1, 100] 563 (the curves can be manually tweaked in the Ipo Curve Editor window in 564 Blender itself later). 565 """
566
567 - def removeAllKeys():
568 """ 569 Remove all mesh keys stored in this mesh. 570 @rtype: bool 571 @return: True if successful or False if this NMesh wasn't linked to a real 572 Blender Mesh yet (or was, but the Mesh had no keys). 573 @warn: Currently the mesh keys from meshes that are grabbed with 574 NMesh.GetRaw() or .GetRawFromObject() are preserved, so if you want to 575 clear them or don't want them at all, remember to call this method. Of 576 course NMeshes created with NMesh.New() don't have mesh keys until you 577 add them. 578 """
579
580 - def update(recalc_normals = 0, store_edges = 0, vertex_shade = 0):
581 """ 582 Update the mesh in Blender. The changes made are put back to the mesh in 583 Blender, if available, or put in a newly created mesh if this NMesh wasn't 584 already linked to one. 585 @type recalc_normals: int (bool) 586 @param recalc_normals: if nonzero the vertex normals are recalculated. 587 @type store_edges: int (bool) 588 @param store_edges: deprecated, edges are always stored now. 589 @type vertex_shade: int (bool) 590 @param vertex_shade: if nonzero vertices are colored based on the 591 current lighting setup, like when there are no vertex colors and no 592 textured faces and a user enters Vertex Paint Mode in Blender (only 593 lamps in visible layers account). To use this functionality, be out of 594 edit mode or else an error will be returned. 595 @warn: edit mesh and normal mesh are two different structures in Blender, 596 synchronized upon leaving or entering edit mode. Always remember to 597 leave edit mode (L{Window.EditMode}) before calling this update 598 method, or your changes will be lost. Even better: for the same reason 599 programmers should leave EditMode B{before} getting a mesh, or changes 600 made to the editmesh in Blender may not be visible to your script 601 (check the example at the top of NMesh module doc). 602 @warn: unlike the L{PutRaw} function, this method doesn't check validity of 603 vertex, face and material lists, because it is meant to be as fast as 604 possible (and already performs many tasks). So programmers should make 605 sure they only feed proper data to the nmesh -- a good general 606 recommendation, of course. It's also trivial to write code to check 607 all data before updating, for example by comparing each item's type 608 with the actual L{Types}, if you need to. 609 @note: this method also redraws the 3d view and -- if 'vertex_shade' is 610 nonzero -- the edit buttons window. 611 @note: if your mesh disappears after it's updated, try 612 L{Object.Object.makeDisplayList}. 'Subsurf' meshes (see L{getMode}, 613 L{setMode}) need their display lists updated, too. 614 """
615
616 - def transform(matrix, recalc_normals = False):
617 """ 618 Transforms the mesh by the specified 4x4 matrix, as returned by 619 L{Object.Object.getMatrix}, though this will work with any invertible 4x4 620 matrix type. Ideal usage for this is exporting to an external file where 621 global vertex locations are required for each object. 622 Sometimes external renderers or file formats do not use vertex normals. 623 In this case, you can skip transforming the vertex normals by leaving 624 the optional parameter recalc_normals as False or 0 ( the default value ). 625 626 Example:: 627 # This script outputs deformed meshes worldspace vertex locations 628 # for a selected object 629 import Blender 630 from Blender import NMesh, Object 631 632 ob = Object.GetSelected()[0] # Get the first selected object 633 me = NMesh.GetRawFromObject(ob.name) # Get the objects deformed mesh data 634 me.transform(ob.matrix) 635 636 for v in me.verts: 637 print 'worldspace vert', v.co 638 639 @type matrix: Py_Matrix 640 @param matrix: 4x4 Matrix which can contain location, scale and rotation. 641 @type recalc_normals: int (bool) 642 @param recalc_normals: if True or 1, transform normals as well as vertex coordinates. 643 @warn: if you call this method and later L{update} the mesh, the new 644 vertex positions will be passed back to Blender, but the object 645 matrix of each object linked to this mesh won't be automatically 646 updated. You need to set the object transformations (rotation, 647 translation and scaling) to identities, then, or the mesh data will 648 be changed ("transformed twice"). 649 """
650
651 - def getMode():
652 """ 653 Get this mesh's mode flags. 654 @rtype: int 655 @return: ORed value. See L{Modes}. 656 """
657
658 - def setMode(m=None, m1=None, m2=None):
659 """ 660 Set the mode flags for this mesh. Given mode strings turn the mode "on". 661 Modes not passed in are turned "off", so setMode() (without arguments) 662 unsets all mode flags. 663 @type m: string or int (bitflag) 664 @param m: mode string or int. An int (see L{Modes}) or from none to 3 665 strings can be given: 666 - "NoVNormalsFlip" 667 - "TwoSided" 668 - "AutoSmooth" 669 """
670
671 - def addVertGroup(group):
672 """ 673 Add a named and empty vertex (deform) group to the object this nmesh is 674 linked to. If this nmesh was newly created or accessed with GetRaw, it must 675 first be linked to an object (with object.link or NMesh.PutRaw) so the 676 method knows which object to update.\n 677 This is because vertex groups in Blender are stored in I{the object} -- 678 not in the mesh, which may be linked to more than one object. For this 679 reason, it's better to use "mesh = object.getData()" than 680 "mesh = NMesh.GetRaw(meshName)" to access an existing mesh. 681 @type group: string 682 @param group: the name for the new group. 683 """
684
685 - def removeVertGroup(group):
686 """ 687 Remove a named vertex (deform) group from the object linked to this nmesh. 688 All vertices assigned to the group will be removed (just from the group, 689 not deleted from the mesh), if any. If this nmesh was newly created, it 690 must first be linked to an object (read the comment in L{addVertGroup} for 691 more info). 692 @type group: string 693 @param group: the name of a vertex group. 694 """
695
696 - def assignVertsToGroup(group, vertList, weight, assignmode = 'replace'):
697 """ 698 Adds an array (a python list) of vertex points to a named vertex group 699 associated with a mesh. The vertex list is a list of vertex indices from 700 the mesh. You should assign vertex points to groups only when the mesh has 701 all its vertex points added to it and is already linked to an object. 702 703 I{B{Example:}} 704 The example here adds a new set of vertex indices to a sphere primitive:: 705 import Blender 706 sphere = Blender.Object.Get('Sphere') 707 mesh = sphere.getData() 708 mesh.addVertGroup('firstGroup') 709 vertList = [] 710 for x in range(300): 711 if x % 3 == 0: 712 vertList.append(x) 713 mesh.assignVertsToGroup('firstGroup', vertList, 0.5, 'add') 714 715 @type group: string 716 @param group: the name of the group. 717 @type vertList: list of ints 718 @param vertList: a list of vertex indices. 719 @type weight: float 720 @param weight: the deform weight for (which means: the amount of influence 721 the group has over) the given vertices. It should be in the range 722 [0.0, 1.0]. If weight <= 0, the given vertices are removed from the 723 group. If weight > 1, it is clamped. 724 @type assignmode: string 725 @param assignmode: Three choices: 726 - 'add' 727 - 'subtract' 728 - 'replace'\n 729 730 'B{add}': if the vertex in the list is not assigned to the group 731 already, this creates a new association between this vertex and the 732 group with the weight specified, otherwise the weight given is added to 733 the current weight of an existing association between the vertex and 734 group.\n 735 'B{subtract}' will attempt to subtract the weight passed from a vertex 736 already associated with a group, else it does nothing.\n 737 'B{replace}' attempts to replace a weight with the new weight value 738 for an already associated vertex/group, else it does nothing. 739 """
740
741 - def removeVertsFromGroup(group, vertList = None):
742 """ 743 Remove a list of vertices from the given group. If this nmesh was newly 744 created, it must first be linked to an object (check L{addVertGroup}). 745 @type group: string 746 @param group: the name of a vertex group 747 @type vertList: list of ints 748 @param vertList: a list of vertex indices to be removed from the given 749 'group'. If None, all vertices are removed -- the group is emptied. 750 """
751
752 - def getVertsFromGroup(group, weightsFlag = 0, vertList = None):
753 """ 754 Return a list of vertex indices associated with the passed group. This 755 method can be used to test whether a vertex index is part of a group and 756 if so, what its weight is. 757 758 I{B{Example:}} 759 Append this to the example from L{assignVertsToGroup}:: 760 # ... 761 print "Vertex indices from group %s :" % groupName 762 print mesh.getVertsFromGroup('firstGroup') 763 print "Again, with weights:" 764 print mesh.getVertsFromGroup('firstGroup',1) 765 print "Again, with weights and restricted to the given indices:" 766 print mesh.getVertsFromGroup('firstGroup',1,[1,2,3,4,5,6]) 767 768 @type group: string 769 @param group: the group name. 770 @type weightsFlag: bool 771 @param weightsFlag: if 1, the weight is returned along with the index. 772 @type vertList: list of ints 773 @param vertList: if given, only those vertex points that are both in the 774 list and group passed in are returned. 775 """
776
777 - def renameVertGroup(groupName, newName):
778 """ 779 Renames a vertex group. 780 @type groupName: string 781 @param groupName: the vertex group name to be renamed. 782 @type newName: string 783 @param newName: the name to replace the old name. 784 """
785
786 - def getVertGroupNames():
787 """ 788 Return a list of all vertex group names. 789 @rtype: list of strings 790 @return: returns a list of strings representing all vertex group 791 associated with the mesh's object 792 """
793
794 - def getMaxSmoothAngle():
795 """ 796 Get the max angle for auto smoothing. 797 Note: This will only affect smoothing generated at render time. 798 Smoothing can also be set per face which is visible in Blenders 3D View. 799 @return: The value in degrees. 800 """
801
802 - def setMaxSmoothAngle(angle):
803 """ 804 Set the max angle for auto smoothing. 805 @type angle: int 806 @param angle: The new value in degrees -- it's clamped to [1, 80]. 807 """
808
809 - def getSubDivLevels():
810 """ 811 Get the mesh subdivision levels for realtime display and rendering. 812 @return: list of ints: [display, render]. 813 """
814
815 - def setSubDivLevels(subdiv):
816 """ 817 Set the mesh subdivision levels for realtime display and rendering. 818 @type subdiv: list of 2 ints 819 @param subdiv: new subdiv levels: [display, render]. Both are clamped to 820 lie in the range [1, 6]. 821 """
822