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.

Method Summary
	`addVertGroup(group)` Add a named and empty vertex (deform) group to the object this mesh 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.
	`calcNormals()` Recalculates the vertex normals using face data.
	`fill()` Scan fill a closed selected edge loop.
int, None or list	`findEdges(edges)` Quickly search for the location of an edges.
	`flipNormals()` Toggles the direction of selected face's normals.
	`getFromObject(name, cage)` Replace the mesh's existing data with the raw mesh data from a Blender Object.
list of lists	`getVertexInfluences(index)` Get the bone influences for 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.
	`quadToTriangle(mode)` Convert selected quads to triangles.
	`recalcNormals(direction)` Recalculates inside or outside normals for selected faces.
int	`remDoubles(limit)` Removes duplicates from selected vertices.
	`removeVertGroup(group)` Remove a named vertex (deform) group from the object linked to this mesh.
	`removeVertsFromGroup(group, vertList)` Remove a list of vertices from the given group.
	`renameVertGroup(groupName, newName)` Renames a vertex group.
	`smooth()` Flattens angle of selected faces.
	`subdivide(beauty)` Subdivide selected edges in a mesh.
	`toSphere()` Moves selected vertices outward in a spherical shape.
	`transform(matrix, recalc_normals)` Transforms the mesh by the specified 4x4 matrix (such as returned by `Object.Object.getMatrix`).
	`triangleToQuad()` Convert selected triangles to quads.
	`update()` Update display lists after changes to mesh.
	`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).

Instance Variable Summary
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.
int	`degr`: The max angle for auto smoothing in [1,80].
sequence of MEdges	`edges`: The mesh's edges.
sequence of MFaces	`faces`: The mesh's faces.
bool	`faceUV`: The mesh contains UV-mapped textured faces.
boolean	`hide`: Sets hidden status for all vertices, edges and faces in the mesh (write only).
list of Materials	`materials`: The mesh's materials.
	`maxSmoothAngle`: Same as `degr`.
int	`mode`: The mesh's mode bitfield.
str	`name`: The Mesh name.
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].
int	`users`: The number of Objects using (linked to) this mesh.
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

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

assignVertsToGroup(group, vertList, weight, assignmode=1)

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

calcNormals()

Recalculates the vertex normals using face data.

fill()

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

Notes:

In some cases the selected edge loop may not be filled. because of its shape or edges that cross. Make sure you account for this in your script.
For large meshes this will be slow because this function toggles editmode. Similar functionality is provided by Geometry.PolyFill

findEdges(edges)

Quickly search for the location of an edges.

Parameters:: edges - 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.
(type=sequence(s) of ints or MVerts)

Returns:: if an edge is found, its index is returned; otherwise None is returned. If a sequence of edges is passed, a list is returned.
(type=int, None or list)

flipNormals()

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

getFromObject(name, cage=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:: name - name of the Blender object which contains the geometry data.
(type=string); cage - determines whether the original vertices or derived vertices (for objects with modifiers) are used. The default is derived vertices.
(type=int)

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

getVertexInfluences(index)

Get the bone influences for 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 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)

quadToTriangle(mode=0)

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

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

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 - specifies outward (0) or inward (1) normals. Outward is the default. Value must be in the range [0,1].
(type=int)

remDoubles(limit)

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

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

Returns:: the number of vertices deleted
(type=int)

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

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 - the name of a vertex group
(type=string); vertList - a list of vertex indices to be removed from 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)

smooth()

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

subdivide(beauty=0)

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

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

toSphere()

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

transform(matrix, recalc_normals=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, Scene

scn= Scene.GetCurrent()      # Get the current scene
ob = scn.getActiveObject()   # Get the active 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 - 4x4 Matrix which can contain location, scale and rotation.
(type=Py_Matrix); recalc_normals - if True or 1, also transform vertex normals.
(type=int)

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

triangleToQuad()

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

update()

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.

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 - The Blender Object linked to the mesh.
(type=Object)

Instance Variable Details

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

degr

The max angle for auto smoothing in [1,80].

Type:: int

edges

The mesh's edges.

Type:: sequence of MEdges

faces

The mesh's faces.

Type:: sequence of MFaces

faceUV

The mesh contains UV-mapped textured faces. Enabling faceUV does not initialize the face colors like the Blender UI does; this must be done in the script. Note: if faceUV is set, vertexColors cannot be set. Furthermore, if vertexColors is already set when faceUV is set, vertexColors is cleared. This is because the vertex color information is stored with UV faces, so enabling faceUV implies enabling vertexColors. In addition, faceUV cannot be set when the mesh has no faces defined (this is the same behavior as the UI). Attempting to do so will throw a RuntimeError exception.

Type:: bool

hide

Sets hidden status for all vertices, edges and faces in the mesh (write only).

Type:: boolean

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 faces material indicies, take care when using the faces material indices to reference a material in the materials list. Note: The the list thats returned is not linked to the original mesh. mesh.materials.append(material) wont 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

name

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

Type:: str

sel

Sets selection status for all vertices, edges and faces in the mesh (write only).

Type:: boolean

subDivLevels

The [display, rendering] subdivision levels in [1, 6].

Type:: list of 2 ints

users

The number of Objects using (linked to) this mesh.

Type:: int

vertexColors

The mesh contains vertex colors. See faceUV for the use of vertex colors when UV-mapped texture faces are enabled.

Type:: bool

vertexUV

The mesh contains "sticky" per-vertex UV coordinates.

Type:: bool

verts

The mesh's vertices.

Type:: sequence of MVerts

Generated by Epydoc 2.1 on Thu Jul 13 16:50:05 2006

http://epydoc.sf.net