Module NMesh :: Class NMesh

Class NMesh

source code

The NMesh Data object

This object gives access to mesh data in Blender. We refer to mesh as the object in Blender and NMesh as its Python counterpart.

Instance Methods
NMEdge
addEdge(v1, v2)
Create an edge between two vertices.
source code
NMEdge
findEdge(v1, v2)
Try to find an edge between two vertices.
source code
 
removeEdge(v1, v2)
Remove an edge between two vertices.
source code
list of NMEdge
addFace(face)
Add a face to face list and add to edge list (if edge data exists) necessary edges.
source code
 
removeFace(face)
Remove a face for face list and remove edges no more used by any other face (if edge data exists).
source code
 
addMaterial(material)
Add a new material to this NMesh's list of materials.
source code
list of materials
getMaterials(what=-1)
Get this NMesh's list of materials.
source code
 
setMaterials(matlist)
Set this NMesh's list of materials.
source code
bool
hasVertexColours(flag=None)
Get (and optionally set) if this NMesh has vertex colors.
source code
bool
hasFaceUV(flag=None)
Get (and optionally set) if this NMesh has UV-mapped textured faces.
source code
bool
hasVertexUV(flag=None)
Get (and optionally set) the "sticky" flag that controls if a mesh has per vertex UV coordinates.
source code
int
getActiveFace()
Get the index of the active face.
source code
list
getSelectedFaces(flag=None)
Get list of selected faces.
source code
list of lists
getVertexInfluences(index)
Get influences of bones in a specific vertex.
source code
Key.Key object or None
getKey()
Get the Key object representing the Vertex Keys (absolute or relative) assigned to this mesh.
source code
 
insertKey(frame=None, type='relative')
Insert a mesh key at the given frame.
source code
bool
removeAllKeys()
Remove all mesh keys stored in this mesh.
source code
 
update(recalc_normals=0, store_edges=0, vertex_shade=0)
Update the mesh in Blender.
source code
 
transform(matrix, recalc_normals=False)
Transforms the mesh by the specified 4x4 matrix, as returned by Object.Object.getMatrix, though this will work with any invertible 4x4 matrix type.
source code
int
getMode()
Get this mesh's mode flags.
source code
 
setMode(m=None, m1=None, m2=None)
Set the mode flags for this mesh.
source code
 
addVertGroup(group)
Add a named and empty vertex (deform) group to the object this nmesh is linked to.
source code
 
removeVertGroup(group)
Remove a named vertex (deform) group from the object linked to this nmesh.
source code
 
assignVertsToGroup(group, vertList, weight, assignmode='replace')
Adds an array (a python list) of vertex points to a named vertex group associated with a mesh.
source code
 
removeVertsFromGroup(group, vertList=None)
Remove a list of vertices from the given group.
source code
 
getVertsFromGroup(group, weightsFlag=0, vertList=None)
Return a list of vertex indices associated with the passed group.
source code
 
renameVertGroup(groupName, newName)
Renames a vertex group.
source code
list of strings
getVertGroupNames()
Return a list of all vertex group names.
source code
 
getMaxSmoothAngle()
Get the max angle for auto smoothing.
source code
 
setMaxSmoothAngle(angle)
Set the max angle for auto smoothing.
source code
 
getSubDivLevels()
Get the mesh subdivision levels for realtime display and rendering.
source code
 
setSubDivLevels(subdiv)
Set the mesh subdivision levels for realtime display and rendering.
source code
Class Variables
  key
The Key.Key object attached to this mesh, if any.
Instance Variables
  edges
A list of NMEdge edges.
  faces
The list of NMesh faces (NMFaces).
  materials
The list of materials used by this NMesh.
  maxSmoothAngle
The max angle for auto smoothing.
  mode
The mode flags for this mesh.
  name
The NMesh name.
IDGroup properties
Returns an IDGroup reference to this object's ID Properties.
  subDivLevels
The [display, rendering] subdivision levels in [1, 6].
  users
The number of Objects using (linked to) this mesh.
  verts
The list of NMesh vertices (NMVerts).
Method Details

addEdge(v1, v2)

source code 
Create an edge between two vertices. If an edge already exists between those vertices, it is returned. Created edge is automatically added to edges list. You can only call this method if mesh has edge data.
Parameters:
  • v1 (NMVert) - the first vertex of the edge.
  • v2 (NMVert) - the second vertex of the edge.
Returns: NMEdge
The created or already existing edge.

Note: In Blender only zero or one edge can link two vertices.

findEdge(v1, v2)

source code 
Try to find an edge between two vertices. If no edge exists between v1 and v2, None is returned. You can only call this method if mesh has edge data.
Parameters:
  • v1 (NMVert) - the first vertex of the edge.
  • v2 (NMVert) - the second vertex of the edge.
Returns: NMEdge
The found edge. None if no edge was found.

removeEdge(v1, v2)

source code 
Remove an edge between two vertices. All faces using this edge are removed from faces list. You can only call this method if mesh has edge data.
Parameters:
  • v1 (NMVert) - the first vertex of the edge.
  • v2 (NMVert) - the second vertex of the edge.

addFace(face)

source code 
Add a face to face list and add to edge list (if edge data exists) necessary edges.
Parameters:
  • face (NMFace) - the face to add to the mesh.
Returns: list of NMEdge
If mesh has edge data, return the list of face edges.

removeFace(face)

source code 
Remove a face for face list and remove edges no more used by any other face (if edge data exists).
Parameters:
  • face (NMFace) - the face to add to the mesh.

addMaterial(material)

source code 
Add a new material to this NMesh's list of materials. This method is the slower but safer way to add materials, since it checks if the argument given is really a material, imposes a limit of 16 materials and only adds the material if it wasn't already in the list.
Parameters:
  • material (Blender Material) - A Blender Material.

getMaterials(what=-1)

source code 
Get this NMesh's list of materials.
Parameters:
  • what (int) - determines the list's contents:
    • -1: return the current NMesh's list;
    • 0: retrieve a fresh list from the Blender mesh -- eventual modifications made by the script not included, unless update is called before this method;
    • 1: like 0, but empty slots are not ignored, they are returned as None's.
Returns: list of materials
the requested list of materials.
Notes:
  • what >= 0 also updates nmesh.materials attribute.
  • if a user goes to the material buttons window and removes some mesh's link to a material, that material slot becomes empty. Previously such materials were ignored.
  • Object.colbits needs to be set correctly for each object in order for these materials to be used instead of the object's materials.

setMaterials(matlist)

source code 
Set this NMesh's list of materials. This method checks the consistency of the passed list: must only have materials or None's and can't contain more than 16 entries.
Parameters:
  • matlist (list of materials) - a list with materials, None's also accepted (they become empty material slots in Blender.

Note: Object.colbits needs to be set correctly for each object in order for these materials to be used instead of the object's materials.

hasVertexColours(flag=None)

source code 
Get (and optionally set) if this NMesh has vertex colors.
Parameters:
  • flag (int) - If given and non-zero, the "vertex color" flag for this NMesh is turned on.
Returns: bool
The current value of the "vertex color" flag.

Warning: If a mesh has both vertex colors and textured faces, this function will return False. This is due to the way Blender deals internally with the vertex colors array (if there are textured faces, it is copied to the textured face structure and the original array is freed/deleted). If you want to know if a mesh has both textured faces and vertex colors, set *in Blender* the "VCol Paint" flag for each material that covers an area that was also vertex painted and then check in your Python script if that material flag is set. Of course also tell others who use your script to do the same. The "VCol Paint" material mode flag is the way to tell Blender itself to render with vertex colors, too, so it's a natural solution.

hasFaceUV(flag=None)

source code 
Get (and optionally set) if this NMesh has UV-mapped textured faces.
Parameters:
  • flag (int) - If given and non-zero, the "textured faces" flag for this NMesh is turned on.
Returns: bool
The current value of the "textured faces" flag.

hasVertexUV(flag=None)

source code 
Get (and optionally set) the "sticky" flag that controls if a mesh has per vertex UV coordinates.
Parameters:
  • flag (int) - If given and non-zero, the "sticky" flag for this NMesh is turned on.
Returns: bool
The current value of the "sticky" flag.

getActiveFace()

source code 
Get the index of the active face.
Returns: int
The index of the active face.

getSelectedFaces(flag=None)

source code 
Get list of selected faces.
Parameters:
  • flag (int) - If given and non-zero, the list will have indices instead of the NMFace objects themselves.
Returns: list
It depends on the flag parameter:
  • if None or zero: List of NMFace objects.
  • if non-zero: List of indices to NMFace objects.

Warning: this method exists to speed up retrieving of selected faces from the actual mesh in Blender. So, if you make changes to the nmesh, you need to update it before using this method.

getVertexInfluences(index)

source code 
Get influences of bones in a specific vertex.
Parameters:
  • index (int) - The index of a vertex.
Returns: list of lists
List of pairs (name, weight), where name is the bone name (string) and its weight is a float value.

insertKey(frame=None, type='relative')

source code 
Insert a mesh key at the given frame. Remember to update the nmesh before doing this, or changes in the vertices won't be updated in the Blender mesh.
Parameters:
  • frame (int) - The Scene frame where the mesh key should be inserted. If None, the current frame is used.
  • type (string) - The mesh key type: 'relative' or 'absolute'. This is only relevant on the first call to insertKey for each nmesh (and after all keys were removed with removeAllKeys, of course).

Warning: This and removeAllKeys were included in this release only to make accessing vertex keys possible, but may not be a proper solution and may be substituted by something better later. For example, it seems that 'frame' should be kept in the range [1, 100] (the curves can be manually tweaked in the Ipo Curve Editor window in Blender itself later).

removeAllKeys()

source code 
Remove all mesh keys stored in this mesh.
Returns: bool
True if successful or False if this NMesh wasn't linked to a real Blender Mesh yet (or was, but the Mesh had no keys).

Warning: Currently the mesh keys from meshes that are grabbed with NMesh.GetRaw() or .GetRawFromObject() are preserved, so if you want to clear them or don't want them at all, remember to call this method. Of course NMeshes created with NMesh.New() don't have mesh keys until you add them.

update(recalc_normals=0, store_edges=0, vertex_shade=0)

source code 
Update the mesh in Blender. The changes made are put back to the mesh in Blender, if available, or put in a newly created mesh if this NMesh wasn't already linked to one.
Parameters:
  • recalc_normals (int (bool)) - if nonzero the vertex normals are recalculated.
  • store_edges (int (bool)) - deprecated, edges are always stored now.
  • vertex_shade (int (bool)) - if nonzero vertices are colored based on the current lighting setup, like when there are no vertex colors and no textured faces and a user enters Vertex Paint Mode in Blender (only lamps in visible layers account). To use this functionality, be out of edit mode or else an error will be returned.
Warnings:
  • edit mesh and normal mesh are two different structures in Blender, synchronized upon leaving or entering edit mode. Always remember to leave edit mode (Window.EditMode) before calling this update method, or your changes will be lost. Even better: for the same reason programmers should leave EditMode before getting a mesh, or changes made to the editmesh in Blender may not be visible to your script (check the example at the top of NMesh module doc).
  • unlike the PutRaw function, this method doesn't check validity of vertex, face and material lists, because it is meant to be as fast as possible (and already performs many tasks). So programmers should make sure they only feed proper data to the nmesh -- a good general recommendation, of course. It's also trivial to write code to check all data before updating, for example by comparing each item's type with the actual Types, if you need to.
Notes:
  • this method also redraws the 3d view and -- if 'vertex_shade' is nonzero -- the edit buttons window.
  • if your mesh disappears after it's updated, try Object.Object.makeDisplayList. 'Subsurf' meshes (see getMode, setMode) need their display lists updated, too.

transform(matrix, recalc_normals=False)

source code 

Transforms the mesh by the specified 4x4 matrix, as returned by Object.Object.getMatrix, though this will work with any invertible 4x4 matrix type. Ideal usage for this is exporting to an external file where global vertex locations are required for each object. Sometimes external renderers or file formats do not use vertex normals. In this case, you can skip transforming the vertex normals by leaving the optional parameter recalc_normals as False or 0 ( the default value ).

Example:
# This script outputs deformed meshes worldspace vertex locations
# for a selected object
import Blender
from Blender import NMesh, Object

ob = Object.GetSelected()[0] # Get the first selected object
me = NMesh.GetRawFromObject(ob.name) # Get the objects deformed mesh data
me.transform(ob.matrix)

for v in me.verts:
  print 'worldspace vert', v.co
Parameters:
  • matrix (Py_Matrix) - 4x4 Matrix which can contain location, scale and rotation.
  • recalc_normals (int (bool)) - if True or 1, transform normals as well as vertex coordinates.

Warning: if you call this method and later update the mesh, the new vertex positions will be passed back to Blender, but the object matrix of each object linked to this mesh won't be automatically updated. You need to set the object transformations (rotation, translation and scaling) to identities, then, or the mesh data will be changed ("transformed twice").

getMode()

source code 
Get this mesh's mode flags.
Returns: int
ORed value. See Modes.

setMode(m=None, m1=None, m2=None)

source code 
Set the mode flags for this mesh. Given mode strings turn the mode "on". Modes not passed in are turned "off", so setMode() (without arguments) unsets all mode flags.
Parameters:
  • m (string or int (bitflag)) - mode string or int. An int (see Modes) or from none to 3 strings can be given:
    • "NoVNormalsFlip"
    • "TwoSided"
    • "AutoSmooth"

addVertGroup(group)

source code 

Add a named and empty vertex (deform) group to the object this nmesh is linked to. If this nmesh was newly created or accessed with GetRaw, it must first be linked to an object (with object.link or NMesh.PutRaw) so the method knows which object to update.

This is because vertex groups in Blender are stored in the object -- not in the mesh, which may be linked to more than one object. For this reason, it's better to use "mesh = object.getData()" than "mesh = NMesh.GetRaw(meshName)" to access an existing mesh.
Parameters:
  • group (string) - the name for the new group.

removeVertGroup(group)

source code 
Remove a named vertex (deform) group from the object linked to this nmesh. All vertices assigned to the group will be removed (just from the group, not deleted from the mesh), if any. If this nmesh was newly created, it must first be linked to an object (read the comment in addVertGroup for more info).
Parameters:
  • group (string) - the name of a vertex group.

assignVertsToGroup(group, vertList, weight, assignmode='replace')

source code 

Adds an array (a python list) of vertex points to a named vertex group associated with a mesh. The vertex list is a list of vertex indices from the mesh. You should assign vertex points to groups only when the mesh has all its vertex points added to it and is already linked to an object.

Example: The example here adds a new set of vertex indices to a sphere primitive:
import Blender
sphere = Blender.Object.Get('Sphere')
mesh = sphere.getData()
mesh.addVertGroup('firstGroup')
vertList = []
for x in range(300):
    if x % 3 == 0:
        vertList.append(x)
mesh.assignVertsToGroup('firstGroup', vertList, 0.5, 'add')
Parameters:
  • group (string) - the name of the group.
  • vertList (list of ints) - a list of vertex indices.
  • weight (float) - the deform weight for (which means: the amount of influence the group has over) the given vertices. It should be in the range [0.0, 1.0]. If weight <= 0, the given vertices are removed from the group. If weight > 1, it is clamped.
  • assignmode (string) - Three choices:
    • 'add'
    • 'subtract'
    • 'replace'

      'add': if the vertex in the list is not assigned to the group already, this creates a new association between this vertex and the group with the weight specified, otherwise the weight given is added to the current weight of an existing association between the vertex and group.

      'subtract' will attempt to subtract the weight passed from a vertex already associated with a group, else it does nothing.

      'replace' attempts to replace a weight with the new weight value for an already associated vertex/group, else it does nothing.

removeVertsFromGroup(group, vertList=None)

source code 
Remove a list of vertices from the given group. If this nmesh was newly created, it must first be linked to an object (check addVertGroup).
Parameters:
  • group (string) - the name of a vertex group
  • vertList (list of ints) - a list of vertex indices to be removed from the given 'group'. If None, all vertices are removed -- the group is emptied.

getVertsFromGroup(group, weightsFlag=0, vertList=None)

source code 

Return a list of vertex indices associated with the passed group. This method can be used to test whether a vertex index is part of a group and if so, what its weight is.

Example: Append this to the example from assignVertsToGroup:
# ...
print "Vertex indices from group %s :" % groupName
print mesh.getVertsFromGroup('firstGroup')
print "Again, with weights:"
print mesh.getVertsFromGroup('firstGroup',1)
print "Again, with weights and restricted to the given indices:"
print mesh.getVertsFromGroup('firstGroup',1,[1,2,3,4,5,6])     
Parameters:
  • group (string) - the group name.
  • weightsFlag (bool) - if 1, the weight is returned along with the index.
  • vertList (list of ints) - if given, only those vertex points that are both in the list and group passed in are returned.

renameVertGroup(groupName, newName)

source code 
Renames a vertex group.
Parameters:
  • groupName (string) - the vertex group name to be renamed.
  • newName (string) - the name to replace the old name.

getVertGroupNames()

source code 
Return a list of all vertex group names.
Returns: list of strings
returns a list of strings representing all vertex group associated with the mesh's object

getMaxSmoothAngle()

source code 
Get the max angle for auto smoothing. Note: This will only affect smoothing generated at render time. Smoothing can also be set per face which is visible in Blenders 3D View.
Returns:
The value in degrees.

setMaxSmoothAngle(angle)

source code 
Set the max angle for auto smoothing.
Parameters:
  • angle (int) - The new value in degrees -- it's clamped to [1, 80].

getSubDivLevels()

source code 
Get the mesh subdivision levels for realtime display and rendering.
Returns:
list of ints: [display, render].

setSubDivLevels(subdiv)

source code 
Set the mesh subdivision levels for realtime display and rendering.
Parameters:
  • subdiv (list of 2 ints) - new subdiv levels: [display, render]. Both are clamped to lie in the range [1, 6].

Instance Variable Details

materials

The list of materials used by this NMesh. See getMaterials for important details.

maxSmoothAngle

The max angle for auto smoothing. See setMode.

mode

The mode flags for this mesh. See setMode.

name

The NMesh name. It's common to use this field to store extra data about the mesh (to be exported to another program, for example).