Module Mesh :: Class Mesh

Class Mesh

The Mesh Data object

This object gives access to mesh data in Blender.

Note: the verts, edges and faces attributes are implemented as sequences. The operator[] and len() are defined for these sequences. You cannot assign to an item in the sequence, but you can assign to most of the attributes of individual items.

Instance Methods

getFromObject(object, cage=0, render=0)
Replace the mesh's existing data with the raw mesh data from a Blender Object.

calcNormals()
Recalculates the vertex normals using face data.

pointInside(point, selected_only=False)

getTangents()
Calculates tangents for this mesh, returning a list of tuples, each with 3 or 4 tangent vectors, these are alligned with the meshes faces.

transform(matrix, recalc_normals=False, selected_only=False)
Transforms the mesh by the specified 4x4 matrix (such as returned by Object.Object.getMatrix).

vertexShade(object)
Colors vertices 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).

update(key=None)
Update display lists after changes to mesh.

int, None or list

findEdges(edges)
Quickly search for the location of an edges.

addVertGroup(group)
Add a named and empty vertex (deform) group to the object this mesh is linked to.

removeVertGroup(group)
Remove a named vertex (deform) group from the object linked to this mesh.

assignVertsToGroup(group, vertList, weight, assignmode)
Adds an array (a Python list) of vertex points to a named vertex group associated with a mesh.

removeVertsFromGroup(group, vertList=None)
Remove a list of vertices from the given group.

getVertsFromGroup(group, weightsFlag=0, vertList=None)
Return a list of vertex indices associated with the passed group.

renameVertGroup(groupName, newName)
Renames a vertex group.

list of strings

getVertGroupNames()
Return a list of all vertex group names.

list of strings

getUVLayerNames()
Return a list of all UV layer names

list of strings

getColorLayerNames()
Return a list of all color layer names

list of lists

getVertexInfluences(index)
Get the bone influences for a specific vertex.

bool

removeAllKeys()
Remove all mesh keys stored in this mesh.

insertKey(frame=None, type='relative')
Insert a mesh key at the given frame.

addUVLayer(name)
Adds a new UV/Image layer to this mesh, it will always be the last layer but not made active.

addColorLayer(name)
Adds a new Vertex Color layer to this mesh, it will always be the last layer but not made active.

addMultiresLevel(levels=1, type='catmull-clark')
Adds multires levels to this mesh.

removeUVLayer(name)
Removes the active UV/Image layer.

removeColorLayer(name)
Removes the active Vertex Color layer.

renameUVLayer(name, newname)
Renames the UV layer called name to newname.

renameColorLayer(name, newname)
Renames the color layer called name to newname.

smooth()
Flattens angle of selected faces.

flipNormals()
Toggles the direction of selected face's normals.

toSphere()
Moves selected vertices outward in a spherical shape.

fill()
Scan fill a closed selected edge loop.

triangleToQuad()
Convert selected triangles to quads.

quadToTriangle(mode=0)
Convert selected quads to triangles.

subdivide(beauty=0)
Subdivide selected edges in a mesh.

int

remDoubles(limit)
Removes duplicates from selected vertices.

recalcNormals(direction=0)
Recalculates inside or outside normals for selected faces.

Mesh

__copy__()
Make a copy of this mesh

Instance Variables
string	activeColorLayer The mesh's active Vertex Color layer.
int	activeFace Index of the mesh's active face in UV Face Select and Paint modes.
string or None	activeGroup The mesh's active vertex group.
string	activeUVLayer The mesh's active UV/Image layer.
int	degr The max angle for auto smoothing in [1,80].
sequence of MEdges	edges The mesh's edges.
bool	faceUV The mesh contains UV-mapped textured faces.
sequence of MFaces	faces The mesh's faces.
bool	fakeUser When set to True, this datablock wont be removed, even if nothing is using it.
boolean	hide Sets hidden status for all vertices, edges and faces in the mesh (write only).
Key or None	key The Key object containing the keyframes for this mesh, if any.
string or None	lib path to the blend file this datablock is stored in (readonly).
list of Materials	materials The mesh's materials.
	maxSmoothAngle Same as degr.
int	mode The mesh's mode bitfield.
bool	multires The mesh has multires data, set True to add multires data.
int	multiresDrawLevel The multires level to display in the 3dview in [1 - multiresLevelCount].
int	multiresEdgeLevel The multires level edge display in the 3dview [1 - multiresLevelCount].
int	multiresLevelCount The mesh has multires data.
int	multiresPinLevel The multires pin level, used for applying modifiers [1 - multiresLevelCount].
int	multiresRenderLevel The multires level to render [1 - multiresLevelCount].
string	name unique name within each blend file.
IDGroup	properties Returns an IDGroup reference to this datablocks's ID Properties.
string	renderColorLayer The mesh's rendered Vertex Color layer.
string	renderUVLayer The mesh's rendered UV/Image layer.
boolean	sel Sets selection status for all vertices, edges and faces in the mesh (write only).
list of 2 ints	subDivLevels The [display, rendering] subdivision levels in [1, 6].
bool	tag A temporary tag that to flag data as being used within a loop.
Mesh or None	texMesh The mesh's texMesh setting, used so coordinates from another mesh can be used for rendering textures.
int	users The number of users this datablock has.
bool	vertexColors The mesh contains vertex colors.
bool	vertexUV The mesh contains "sticky" per-vertex UV coordinates.
sequence of MVerts	verts The mesh's vertices.

Method Details

getFromObject(object, cage=0, render=0)

Replace the mesh's existing data with the raw mesh data from a Blender Object. This method supports all the geometry based objects (mesh, text, curve, surface, and meta). If the object has modifiers, they will be applied before to the object before extracting the vertex data unless the cage parameter is 1.

Parameters:

object (blender object or string) - The Blender object or its name, which contains the geometry data.
cage (int) - determines whether the original vertices or derived vertices
render (int) - determines whether the render setting for modifiers will be used or not. (for objects with modifiers) are used. The default is derived vertices.

Notes:

The mesh coordinates are in local space, not the world space of its object. For world space vertex coordinates, each vertex location must be multiplied by the object's 4x4 transform matrix (see transform).
The objects materials will not be copied into the existing mesh, however the face material indices will match the material list of the original data.

pointInside(point, selected_only=False)

Parameters:

point (vector) - Test if this point is inside the mesh
selected_only (bool) - if True or 1, only the selected faces are taken into account. Returns true if vector is inside the mesh.

Notes:

Only returns a valid result for mesh data that has no holes.
Bubbles in the mesh work as expect.

getTangents()

Calculates tangents for this mesh, returning a list of tuples, each with 3 or 4 tangent vectors, these are alligned with the meshes faces.

Example:

       # Display the tangents as edges over a the active mesh object
       from Blender import *
       sce = Scene.GetCurrent()
       ob = sce.objects.active
       
       me = ob.getData(mesh=1)
       ts = me.getTangents()
       me_disp = Mesh.New()
       
       verts = []
       edges = []
       for i, f in enumerate(me.faces):
               ft = ts[i]
               for j, v in enumerate(f):
                       tan = ft[j]
                       print tan
                       co = v.co
                       
                       verts.append(co)
                       verts.append(co+tan)
                       
                       i = len(verts)
                       edges.append((i-1, i-2))
       
       me_disp.verts.extend( verts )
       me_disp.edges.extend( edges )
       
       sce.objects.new( me_disp )

Note: The tangents are computed using the active UV layer, if there are no UV layers, orco coords are used.

transform(matrix, recalc_normals=False, selected_only=False)

Transforms the mesh by the specified 4x4 matrix (such as returned by Object.Object.getMatrix). The matrix should be invertible. 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 without changing the object
       import Blender
       from Blender import Mesh, Object
       
       ob = Object.GetSelected()[0] # Get the first selected object
       me = Mesh.New()              # Create a new mesh
       me.getFromObject(ob.name)    # Get the object's mesh data
       verts = me.verts[:]          # Save a copy of the vertices
       me.transform(ob.matrix)      # Convert verts to world space
       for v in me.verts:
               print 'worldspace vert', v.co
       me.verts = verts             # Restore the original verts

Parameters:

matrix (Py_Matrix) - 4x4 Matrix which can contain location, scale and rotation.
recalc_normals (int) - if True or 1, also transform vertex normals.
selected_only (bool) - if True or 1, only the selected verts will be transformed.

Warning: unlike NMesh.transform(), this method will immediately modify the mesh data when it is used. If you transform the mesh using the object's matrix to get the vertices' world positions, the result will be a "double transform". To avoid this you either need to set the object's matrix to the identity matrix, perform the inverse transform after outputting the transformed vertices, or make a copy of the vertices prior to using this method and restore them after outputting the transformed vertices (as shown in the example).

vertexShade(object)

Colors vertices 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). An exception is thrown if called while in EditMode.

Parameters:

object (Object) - The Blender Object linked to the mesh.

update(key=None)

Update display lists after changes to mesh. Note: with changes taking place for using a directed acyclic graph (DAG) for scene and object updating, this method may be only temporary and may be removed in future releases.

Parameters:

key (string) - Use this optional argument to write the current vertex locations to the a shape key. the name must match an existing shape key for this mesh See Mesh.Mesh.key and Key.Key.blocks to get a list of the named shape keys, setting the active keys is done from the object with Object.Object.pinShape, Object.Object.activeShape.

Warning: Since Blender 2.42 this function has changed; now it won't recalculate vertex normals (seen when faces are smooth). See Mesh.calcNormals().

findEdges(edges)

Quickly search for the location of an edges.

Parameters:

edges (sequence(s) of ints or MVerts) - can be tuples of MVerts or integer indexes (note: will not work with PVerts) or a sequence (list or tuple) containing two or more sequences.

Returns: int, None or list

if an edge is found, its index is returned; otherwise None is returned. If a sequence of edges is passed, a list is returned.

addVertGroup(group)

Add a named and empty vertex (deform) group to the object this mesh is linked to. The mesh must first be linked to an object (with object.link() or object.getData() ) 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.

Parameters:

group (string) - the name for the new group.

removeVertGroup(group)

Remove a named vertex (deform) group from the object linked to this mesh. All vertices assigned to the group will be removed (just from the group, not deleted from the mesh), if any. If this mesh 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)

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')
       replace = Blender.Mesh.AssignModes.REPLACE
       mesh = sphere.getData(mesh=True)
       mesh.addVertGroup('firstGroup')
       vertList = []
       for x in range(300):
               if x % 3 == 0:
                       vertList.append(x)
       mesh.assignVertsToGroup('firstGroup', vertList, 0.5, replace)

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 (module constant) - Three choices: REPLACE, ADD or SUBTRACT. See AssignModes for a complete description.

removeVertsFromGroup(group, vertList=None)

Remove a list of vertices from the given group. If this mesh 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 group. If None, all vertices are removed -- the group is emptied.

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 (string) - the group name.
weightsFlag (bool) - if 1, each item in the list returned contains a tuple pair (index, weight), the weight is a float between 0.0 and 1.0.
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)

Renames a vertex group.

Parameters:

groupName (string) - the vertex group name to be renamed.
newName (string) - the name to replace the old name.

getVertGroupNames()

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

getUVLayerNames()

Return a list of all UV layer names

Returns: list of strings: returns a list of strings representing all UV layers associated with the mesh's object

getColorLayerNames()

Return a list of all color layer names

Returns: list of strings: returns a list of strings representing all color layers associated with the mesh's object

getVertexInfluences(index)

Get the bone influences for 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 weight is a float value.

removeAllKeys()

Remove all mesh keys stored in this mesh.

Returns: bool: True if successful or False if the Mesh has no keys.

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

Insert a mesh key at the given frame.

Parameters:

frame (int) - The Scene frame where the mesh key should be inserted. If None or the arg is not given, the current frame is used.
type (string) - The mesh key type: 'relative' or 'absolute'. This is only relevant on meshes with no keys.

Warnings:

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).
Will throw an error if the mesh has multires. use multires to check.

addUVLayer(name)

Adds a new UV/Image layer to this mesh, it will always be the last layer but not made active.

Parameters:

name (string) - The name of the new UV layer, 31 characters max.

addColorLayer(name)

Adds a new Vertex Color layer to this mesh, it will always be the last layer but not made active.

Parameters:

name (string) - The name of the new Color layer, 31 characters max.

addMultiresLevel(levels=1, type=`'catmull-clark'`)

Adds multires levels to this mesh.

Parameters:

levels (int) - The number of levels to add
type (string) - The type of multires level, 'catmull-clark' or 'simple'.

removeUVLayer(name)

Removes the active UV/Image layer.

Parameters:

name (string) - The name of the UV layer to remove.

removeColorLayer(name)

Removes the active Vertex Color layer.

Parameters:

name (string) - The name of the Color layer to remove.

renameUVLayer(name, newname)

Renames the UV layer called name to newname.

Parameters:

name (string) - The UV layer to rename.
newname (string) - The new name of the UV layer, will be made unique.

renameColorLayer(name, newname)

Renames the color layer called name to newname.

Parameters:

name (string) - The Color layer to rename.
newname (string) - The new name of the Color layer, will be made unique.

smooth()

Flattens angle of selected faces. Experimental mesh tool. An exception is thrown if called while in EditMode.

flipNormals()

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

toSphere()

Moves selected vertices outward in a spherical shape. Experimental mesh tool. An exception is thrown if called while in EditMode.

fill()

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

triangleToQuad()

Convert selected triangles to quads. Experimental mesh tool. An exception is thrown if called while in EditMode.

quadToTriangle(mode=0)

Convert selected quads to triangles. Experimental mesh tool. An exception is thrown if called while in EditMode.

Parameters:

mode (int) - specifies whether a to add the new edge between the closest (=0) or farthest(=1) vertices.

subdivide(beauty=0)

Subdivide selected edges in a mesh. Experimental mesh tool. An exception is thrown if called while in EditMode.

Parameters:

beauty (int) - specifies whether a "beauty" subdivide should be enabled (disabled is default). Value must be in the range [0,1].

remDoubles(limit)

Removes duplicates from selected vertices. Experimental mesh tool. An exception is thrown if called while in EditMode.

Parameters:

limit (float) - specifies the maximum distance considered for vertices to be "doubles". Value is clamped to the range [0.0,1.0].

Returns: int

the number of vertices deleted

recalcNormals(direction=0)

Recalculates inside or outside normals for selected faces. Experimental mesh tool. An exception is thrown if called while in EditMode.

Parameters:

direction (int) - specifies outward (0) or inward (1) normals. Outward is the default. Value must be in the range [0,1].

copy()

Make a copy of this mesh

Returns: Mesh: a copy of this mesh

Instance Variable Details

activeColorLayer

The mesh's active Vertex Color layer. None if there is no UV/Image layers.

Note: After setting this value, call update so the result can be seen the the 3d view.

Type:: string

activeFace

Index of the mesh's active face in UV Face Select and Paint modes. Only one face can be active at a time. Note that this is independent of the selected faces in Face Select and Edit modes. Will throw an exception if the mesh does not have UV faces; use faceUV to test.

Type:: int

activeGroup

The mesh's active vertex group. The mesh must be linked to an object (read the comment in addVertGroup for more info).

Type:: string or None

activeUVLayer

The mesh's active UV/Image layer. None if there is no UV/Image layers.

Note: After setting this value, call update so the result can be seen the the 3d view.

Type:: string

fakeUser

When set to True, this datablock wont be removed, even if nothing is using it. All data has this disabled by default except for Actions.

Type:: bool

lib

path to the blend file this datablock is stored in (readonly).

lib will be None unless you are using external blend files with (File, Append/Link)

Note: the path may be relative, to get the full path use Blender.sys.expandpath

Type:: string or None

materials

The mesh's materials. Each mesh can reference up to 16 materials. Empty slots in the mesh's list are represented by None. 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. Note: Making the material list shorter does not change the face's material indices. Take care when using the face's material indices to reference a material in this list. Note: The list that's returned is not linked to the original mesh. mesh.materials.append(material) won't do anything. Use mesh.materials += [material] instead.

Type:: list of Materials

maxSmoothAngle

Same as degr. This attribute is only for compatibility with NMesh scripts and will probably be deprecated in the future.

mode

The mesh's mode bitfield. See Modes.

Type:: int

multires

The mesh has multires data, set True to add multires data. Will throw an exception if the mesh has shape keys; use key to test.

Type:: bool

multiresLevelCount

The mesh has multires data. (read only)

Type:: int

name

unique name within each blend file.

The name is case sensitive and 21 characters maximum length.

Note: a blend file may have naming collisions when external library data is used, be sure to check the value of lib.

Note: Setting a value longer then 21 characters will be shortened

Type:: string

renderColorLayer

The mesh's rendered Vertex Color layer. None if there is no UV/Image layers.

Type:: string

renderUVLayer

The mesh's rendered UV/Image layer. None if there is no UV/Image layers.

Type:: string

users

The number of users this datablock has. (readonly) Zero user datablocks are de-allocated after reloading and saving.

Type:: int

vertexColors

The mesh contains vertex colors. Set True to add vertex colors.

Type:: bool

Class Mesh

The Mesh Data object

getFromObject(object, cage=0, render=0)

pointInside(point, selected_only=False)

getTangents()

transform(matrix, recalc_normals=False, selected_only=False)

vertexShade(object)

update(key=None)

findEdges(edges)

addVertGroup(group)

removeVertGroup(group)

assignVertsToGroup(group, vertList, weight, assignmode)

removeVertsFromGroup(group, vertList=None)

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

renameVertGroup(groupName, newName)

getVertGroupNames()

getUVLayerNames()

getColorLayerNames()

getVertexInfluences(index)

removeAllKeys()

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

addUVLayer(name)

addColorLayer(name)

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

removeUVLayer(name)

removeColorLayer(name)

renameUVLayer(name, newname)

renameColorLayer(name, newname)

smooth()

flipNormals()

toSphere()

fill()

triangleToQuad()

quadToTriangle(mode=0)

subdivide(beauty=0)

remDoubles(limit)

recalcNormals(direction=0)

__copy__()

activeColorLayer

activeFace

activeGroup

activeUVLayer

fakeUser

lib

materials

maxSmoothAngle

mode

multires

multiresLevelCount

name

renderColorLayer

renderUVLayer

tag

users

vertexColors

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

addMultiresLevel(levels=1, type=`'catmull-clark'`)

copy()