Vertex groups are a way to organize collections of vertices within a mesh. A mesh may have any number of vertex groups and any vertex within a mesh may be a member of more than one vertex group or may belong to no vertex group at all. A newly created Mesh object does not have any vertex groups defined.

In their basic form, vertex groups are a valuable tool in identifying distinct parts of a complex mesh. By assigning vertices to vertex groups, the modeler eventually provides people, such as the rigger or the people who texture a model, with the means to easily identify and select the parts of the model they want to work on.

The use of vertex groups goes far beyond simple identification though. Many mesh modifiers restrict their influence to a designated vertex group and an armature can be configured to deform a mesh by linking the influence of each bone to a single vertex group. We will see examples of that later.

A vertex group is not merely a collection of vertices. Each vertex of a vertex group may have an associated weight (between zero and one) that many modifiers use to fine-tune their influence. A vertex may have a different weight associated with it in each vertex group it belongs to.

The bugs we create with creepycrawlies.py are an excellent example of a rather complex mesh with many distinct parts that would benefit greatly from defining vertex groups. Not only to make it simpler to select a part by name, for instance the head, but also to make life easier for ourselves if we want to rig the model.

Our primary tools in creating vertex groups are the methods of Mesh objects listed in the following table:

The important concept to grasp here is that creating a vertex group and assigning vertices to it are two separate actions. Creating a new empty vertex group is done by calling the addVertGroup() method of your Mesh object. It takes a single string as an argument and that will be the name of the vertex group. If there is already a vertex group with the same name, the name will have a numerical suffix added to prevent a name clash, so for example: TailSegment may become TailSegment.001.

Adding vertices to an existing vertex group is done by calling the assignVertsToGroup() method of your mesh. This method will take four mandatory arguments—the name of the vertex group to assign the vertices to, a list of vertex indices, a weight, and an assign mode. If the vertex group does not exist, or one of the vertex indices points to a nonexistent vertex, an exception is raised.

The weight must be a value between 0.0 and 1.0; any weight larger than 1.0 is clamped to 1.0. A weight smaller or equal to 0.0 will remove a vertex from the vertex group. If you want to assign different weights to vertices in the same vertex group, you have to assign them to the group with separate calls to assignVertsToGroup().

The assign mode comes in three flavors: ADD, REPLACE, and SUBTRACT. ADD will add new vertices to the vertex group and will associate the given weight with them. If any of the vertices in the list already exist they get the weight added to them. REPLACE will replace the weight associated with the indices in the list if they are members of the vertex group or do nothing otherwise. SUBTRACT will try to subtract the weight from the vertices in the list and again do nothing if they are not members of the vertex group. Most often when adding completely new vertex groups to a mesh you will use the ADD mode.

A weighty issue

For our first example we will add two new vertex groups to an existing mesh object—one that will contain all vertices that have a positive x-coordinate and one that will contain the vertices with a negative x-coordinate. We will name these groups Right and Left respectively.

Additionally, we will give each vertex in these groups a weight depending on its distance from its object center with larger weights for vertices that are farther away from the center.

Code outline: leftright.py

Schematically we will take the following steps:

1. Get the active object.
2. Verify that it is a mesh and get the mesh data.
3. Add two new vertex groups to the object—Left and Right.
4. For all vertices in the mesh:
   1. Calculate the weight
   2. If the x-coordinate > 0:
   3. Add vertex index and weight to vertex group right
   4. If the x-coordinate < 0:
   5. Add vertex index and weight to vertex group left

In order to make certain that a new vertex group is empty we check if the group already exists and remove it if that is the case. This checking is highlighted in the code:

def leftright(me,maximum=1.0):
center=vec(0,0,0)
left =[]
right=[]
for v in me.verts:
weight = (v.co-center).length/maximum
if v.co.x > 0.0 :
right.append((v.index, weight))
elif v.co.x > 0.0 :
left.append((v.index, weight))
return left,right
if __name__ == "__main__":
try:
ob = Blender.Scene.GetCurrent().objects.active
me = ob.getData(mesh=True)
vgroups = me.getVertGroupNames()
if 'Left' in vgroups:
me.removeVertsFromGroup('Left')
else:
me.addVertGroup('Left')
if 'Right' in vgroups:
me.removeVertsFromGroup('Right')
else:
me.addVertGroup('Right')
left,right = leftright(me,vec(ob.getSize()).length)
for v,w in left:
me.assignVertsToGroup('Left',[v], w,Blender.Mesh.AssignModes.ADD)
for v,w in right:
me.assignVertsToGroup('Right',[v],w, Blender.Mesh.AssignModes.ADD)
Blender.Window.Redraw()
except Exception as e:
Blender.Draw.PupMenu('Error%t|'+str(e)[:80])

The full script is available as leftright.py. The formula to calculate the weight may need some explanation: in order to assign a maximum weight of 1.0 to the points lying at the greatest distance from the center of the object we have to scale by the maximum distance possible. We could loop over all vertices to determine that maximum first, but here we choose to approximate this maximum by the root mean square of the size. This will exaggerate the maximum distance so the maximum weight assigned to any vertex will probably be less than 1.0. However, getting the size is much faster than calculating the exact maximum for large meshes. Also, note that we calculate the distance to the object center (the object center from the point of view of the vertices in a mesh is always at (0, 0, 0)).

This may be completely different from what may be perceived by the user as the center of the mesh. (The object center is normally displayed as a pink dot in Blender and may be changed to lie at the average position of all vertices by selecting Object | Transform | Center new.)

The resulting weights for a mesh might looks like this: