Module NMesh :: Class NMesh

Class NMesh

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.

Method Summary
	`addMaterial(material)` Add a new material to this NMesh's list of materials.
	`addVertGroup(group)` Add a named and empty vertex (deform) group to the object this nmesh is linked to.
	`assignVertsToGroup(group, vertList, weight, assignmode)` Adds an array (a python list) of vertex points to a named vertex group associated with a mesh.
int	`getActiveFace()` Get the index of the active face.
list of materials	`getMaterials(what)` Get this NMesh's list of materials.
	`getMaxSmoothAngle()` Get the max angle for auto smoothing.
int	`getMode()` Get this mesh's mode flags.
list	`getSelectedFaces(flag)` Get list of selected faces.
	`getSubDivLevels()` Get the mesh subdivision levels for realtime display and rendering.
list of lists	`getVertexInfluences(index)` Get influences of bones in a specific vertex.
list of strings	`getVertGroupNames()` Return a list of all vertex group names.
	`getVertsFromGroup(group, weightsFlag, vertList)` Return a list of vertex indices associated with the passed group.
bool	`hasFaceUV(flag)` Get (and optionally set) if this NMesh has UV-mapped textured faces.
bool	`hasVertexColours(flag)` Get (and optionally set) if this NMesh has vertex colours.
bool	`hasVertexUV(flag)` Get (and optionally set) the "sticky" flag that controls if a mesh has per vertex UV coordinates.
	`insertKey(frame, type)` Insert a mesh key at the given frame.
bool	`removeAllKeys()` Remove all mesh keys stored in this mesh.
	`removeVertGroup(group)` Remove a named vertex (deform) group from the object linked to this nmesh.
	`removeVertsFromGroup(group, vertList)` Remove a list of vertices from the given group.
	`renameVertGroup(groupName, newName)` Renames a vertex group.
	`setMaterials(matlist)` Set this NMesh's list of materials.
	`setMaxSmoothAngle(angle)` Set the max angle for auto smoothing.
	`setMode(m, m1, m2, m3)` Set the mode flags for this mesh.
	`setSubDivLevels(subdiv)` Set the mesh subdivision levels for realtime display and rendering.
	`update(recalc_normals)` Update the mesh in Blender.

Class Variable Summary
	`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.
	`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

addMaterial(material)

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 - A Blender Material.
(type=Blender Material)

addVertGroup(group)

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 - the name for the new group.
(type=string)

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

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 - the name of the group.
(type=string)

vertList - a list of vertex indices.
(type=list of ints)

weight - 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.
(type=float)

assignmode - Three choices:

'add'
'substract'
'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.

(type=string)

getActiveFace()

Get the index of the active face.

Returns:: The index of the active face.
(type=int)

getMaterials(what=-1)

Get this NMesh's list of materials.

Parameters:

what - 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 NMesh.updated is called before this method;
1: like 0, but empty slots are not ignored, they are returned as None's.

(type=int)

Returns:: the requested list of materials.
(type=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.

getMaxSmoothAngle()

Get the max angle for auto smoothing.

Returns:: The value in degrees.

getMode()

Get this mesh's mode flags.

Returns:: Or'ed value. See Modes.
(type=int)

getSelectedFaces(flag=None)

Get list of selected faces.

Parameters:: flag - If given and non-zero, the list will have indices instead of the NMFace objects themselves.
(type=int)

Returns:

It depends on the flag parameter:

if None or zero: List of NMFace objects.
if non-zero: List of indices to NMFace objects.

(type=list)

getSubDivLevels()

Get the mesh subdivision levels for realtime display and rendering.

Returns:: list of ints: [display, render].

getVertexInfluences(index)

Get influences of bones in a specific vertex.

Parameters:: index - The index of a vertex.
(type=int)

Returns:: List of pairs (name, weight), where name is the bone name (string) and its weight is a float value.
(type=list of lists)

getVertGroupNames()

Return a list of all vertex group names.

Returns:: returns a list of strings representing all vertex group associated with the mesh's object
(type=list of strings)

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

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 - the group name.
(type=string); weightsFlag - if 1, the weight is returned along with the index.
(type=bool); vertList - if given, only those vertex points that are both in the list and group passed in are returned.
(type=list of ints)

hasFaceUV(flag=None)

Get (and optionally set) if this NMesh has UV-mapped textured faces.

Parameters:: flag - If given and non-zero, the "textured faces" flag for this NMesh is turned on.
(type=int)

Returns:: The current value of the "textured faces" flag.
(type=bool)

hasVertexColours(flag=None)

Get (and optionally set) if this NMesh has vertex colours.

Parameters:: flag - If given and non-zero, the "vertex colour" flag for this NMesh is turned on.
(type=int)

Returns:: The current value of the "vertex colour" flag.
(type=bool)

Warning: If a mesh has both vertex colours and textured faces, this function will return False. This is due to the way Blender deals internally with the vertex colours 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 colours, 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 colours, too, so it's a natural solution.

hasVertexUV(flag=None)

Get (and optionally set) the "sticky" flag that controls if a mesh has per vertex UV coordinates.

Parameters:: flag - If given and non-zero, the "sticky" flag for this NMesh is turned on.
(type=int)

Returns:: The current value of the "sticky" flag.
(type=bool)

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

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 - The Scene frame where the mesh key should be inserted. If None, the current frame is used.
(type=int); type - 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).
(type=string)

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()

Remove all mesh keys stored in this mesh.

Returns:: 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).
(type=bool)

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.

removeVertGroup(group)

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 - the name of a vertex group.
(type=string)

removeVertsFromGroup(group, vertList=None)

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 - the name of a vertex group
(type=string); vertList - a list of vertex indices to be removed from the given 'group'. If None, all vertices are removed -- the group is emptied.
(type=list of ints)

renameVertGroup(groupName, newName)

Renames a vertex group.

Parameters:: groupName - the vertex group name to be renamed.
(type=string); newName - the name to replace the old name.
(type=string)

setMaterials(matlist)

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 - a list with materials, None's also accepted (they become empty material slots in Blender.
(type=list of materials)

setMaxSmoothAngle(angle)

Set the max angle for auto smoothing.

Parameters:: angle - The new value in degrees -- it's clamped to [1, 80].
(type=int)

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

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 - mode string. From none to 5 can be given:

"NoVNormalsFlip"
"TwoSided"
"AutoSmooth"
"SubSurf"
"Optimal"

(type=string)

setSubDivLevels(subdiv)

Set the mesh subdivision levels for realtime display and rendering.

Parameters:: subdiv - new subdiv levels: [display, render]. Both are clamped to lie in the range [1, 6].
(type=list of 2 ints)

update(recalc_normals=0)

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 object if this NMesh wasn't already linked to one.

Parameters:: recalc_normals - If given and equal to 1, the vertex normals are recalculated.
(type=int)

Note: if your mesh disappears after it's updated, try Object.Object.makeDisplayList. 'Subsurf' meshes (see getMode, setMode) need their display lists updated, too.

Class Variable Details

faces

The list of NMesh faces (NMFaces).

materials

The list of materials used by this NMesh. See NMesh.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).

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).

Generated by Epydoc 2.1 on Thu Aug 12 21:47:30 2004

http://epydoc.sf.net