smoothWeights

Smooth Weights can be found in:

3D View Side Panel The Tool tab contains a folder with the name Smooth Weights.

It’s possible to customize the location of the tool from the add-on preferences. An alternative placement is a custom Smooth Weights tab in the 3D View Side Panel.

Object Menu The add-on adds new menu items to 3D View (Object Mode) > Object > Smooth Weights.

Weights Menu The add-on adds new menu items to 3D View (Weight Paint Mode) > Weights > Smooth Weights.

The object needs to be in Object or Weight Paint mode in order for the tool to show.

Symmetry Map can be found in:

Mesh Properties Panel

The mesh needs to have at least two vertex groups for the panel and menu items to show. There is no need to smooth weights for only one vertex group.

Standard Brush Display
When smoothing the mesh in Blender’s Weight Paint mode the standard brush will be displayed along with the Smooth Weights brush because the standard brush display cannot be disabled when another tool is active.

Paint Position Precision
When painting on a currently deformed mesh smoothing weights will affect the position of the vertices. The deformed position is stored at the beginning of the stroke and is used for the duration of the stroke. If the position of a vertex changes too much over the course of the stroke the precision of the brush will gradually be reduced. To again improve the precision end the stroke and start a new one. Ending a stroke will trigger re-evaluation of the deformed points. This is a known limitation because Blender needs to evaluate the deformed mesh to get the current point position which reduces performance during the current brush stroke.

Brush Undo
Undoing a stroke while Smooth Weights is active can be slow depending on the number of affected vertices. It’s recommended to only undo with smaller groups or vertices. If broader changes need to be undone it’s usually best to cancel the tool which resets the mesh before the tool has been entered.

Paint

1. Select the mesh in Object or Weight Paint mode. There is no need to explicitly enter Weight Paint mode.
2. From the side panel in the 3D view choose the Tool tab.
3. Open the folder Smooth Weights.
4. Press Brush.
5. All settings can either be adjusted from the side panel before entering the tool or via keymaps while the tool is active. The current settings are displayed via an in-view info in the lower left corner of the 3D view.
6. LMB paint over the mesh to smooth the weights.
7. Press Enter to finish the tool or Esc/RMB to cancel.
8. To undo the last stroke while the tool is active use the default key for undo, without any modifiers.

Flood

1. Select the mesh in Object or Weight Paint mode. There is no need to explicitly enter Weight Paint mode.
2. From the side panel in the 3D view choose the Tool tab.
3. Open the folder Smooth Weights.
4. Adjust the settings for flooding from the side panel.
5. Press Flood.
6. Adjust the flood properties from the redo panel.

The default keymaps are:

B: Brush size
Hold B while dragging the cursor left/right to adjust the size. Hold Shift for faster adjustment and Ctrl for slower. Make sure to hover over the mesh.

S: Brush strength
Hold S while dragging the cursor left/right to adjust the strength. Hold Shift for faster adjustment and Ctrl for slower. Make sure to hover over the mesh.

1/2/3/4: Brush Curve Falloff
The numbers correspond in order to: None, Linear, Smooth, Narrow.

Q: Use Selection

W: Toggle Select Mode

E: Toggle Deselect Mode

C: Clear Selection

A: Affect Selected

X: Ignore Backside

L: Ignore Lock

I: Use Islands

N: Normalize

O: Oversampling
Hold O while pressing + or – to increase or decrease the oversampling value.

V: Volume (off for surface smoothing)

R: Volume Range
Hold R while dragging the cursor left/right to adjust the range. Hold Shift for faster adjustment and Ctrl for slower. Make sure to hover over the mesh.

G: Groups
Hold G while pressing + or – to increase or decrease the number of vertex groups. Zero ignores any group limit.

D: Vertex Group (Type) Hold D while pressing + or – to define which vertex group type is affected: Deformation, Non-Deformation or All.

J: Blend Border

T: Use Symmetry

F: Flood

Shift + RMB: Frame Change
Change the current frame by dragging the mouse left or right.

Y: Pie menu

All keymaps, except the frame change, are customizable from the add-on preferences.

Radius
The brush radius in generic Blender units.

Strength
The strength of the smoothing effect. A value of 1 defines a full averaging with neighbouring weights.

Curve
The brush falloff curve. The further away from the brush center a vertex is the less the smoothing effect will be. Vertices close to the brush center will be affected most.

Use Selection
If enabled, Affect Selected is evaluated to smooth either selected or unselected vertices. If disabled, all vertices will be affected, regardless their selection state.

Affect Selected
Smoothes only the selected vertices. When off only unselected vertices are affected.

Ignore Backside
If enabled, all faces viewed from the back will be ignored for painting.

Ignore Lock
Smooth the weights of vertex groups even if these are locked.

Use Islands
Extends the smoothing across an island boundary by trying to find an equivalent vertex on a neighbouring island boundary. This can help maintain mesh continuity during the deformation.

Normalize
Normalize the averaged weights to a sum of 1.

Oversampling
The number of iterations for the smoothing. If set to 1 only one smoothing pass is performed. The strength of each pass is divided by the oversampling value to avoid oversmoothing.

Use Volume
Enables the Volume mode where weights are smoothed based on the vertex distance. Since it’s volume based the weights can also spread across islands and nearby surfaces. When off the weights are smoothed based on the connected neighbours in Surface mode.

Volume Range
The fraction of the brush size in which neighbouring vertices are considered for smoothing for each vertex in volume mode. This is equivalent to connected vertices in Surface mode. The range factor acts as a multiplier for the Radius value.

Max Groups
The maximum number of vertex groups a vertex can be assigned to. If set to zero limiting of the maximum number of vertex groups is disabled.

Vertex Groups
This option allows to define which type of vertex group is affected by the smoothing.

• All Smooth all vertices regardless of the vertex group type – deforming or non-deforming.
• Deform Only vertex groups which belong to deforming bones will be affected by the smoothing.
• Other Only vertex groups which don’t belong to deforming bones will be affected by the smoothing.

Blend Border
Blend open vertex group borders with the surrounding vertices which are not affected by any vertex group. This property is available with Vertex Group Type Other. When off, the border of a vertex group will not directly be affected.

Use Symmetry
Enables symmetrical smoothing if a symmetry exists and is defined for the affected vertices. Active symmetry does not also mirror the brush circle.

Symmetry map is a utility tool designed to make processing of any type of symmetrical meshes easier. It supports position-based symmetry as well as topological symmetry across multiple islands of the same mesh. The advantage is that the mapping only needs to be performed once and can then be reliably reused for various operations. It provides gains in accuracy, because once a vertex has been mapped it will never fail, as well as speed, because symmetrical points don’t need to be found for every operation over and over.

Operators

Symmetry Map is found in the Mesh Properties panel, which is divided into two sections:

Mapping

This section contains the operators for creating, editing and deleting the symmetry map. It also provides a status information about the current mapping at the top.

Axis
Defines the axis of symmetry.

Tolerance
The tolerance value for finding symmetrical points. Lower values mean stricter accuracy while higher values might cause false assignments. For topological symmetry this is used to find a base center edge while for partial symmetry it’s used to find matching point positions. If set to 0 (default) an automatic, internal value is calculated based on edge-length. For topological symmetry it’s best to to leave the value at 0 while for partial symmetry a small tolerance should be set. When adding partial symmetry a selection of two vertices can be used to set the tolerance automatically if the property is left at 0.

Verbose
This writes the mapping process results to the command output. Only used for debugging purposes.

Create Map
Starts the automatic mapping process and evaluates the mesh. All verified islands will be mapped and the stored in the symmetry map on the mesh. If the mesh is in Object mode all islands will be mapped automatically. If the mesh is in Edit mode the currently selected edge will be used as the user defined edge of symmetry to map the related island. Only one edge selection is supported.

Add To Map This allows to add islands to the symmetry map which failed during the automatic mapping process. There are three types of mesh islands which can be mapped like following:

• Spanning Island The island has topological symmetry but the center edge is too far off the center of the mesh. Select the edge to be used as the center edge and press Add To Map.
• Spanning Island – no center An island might have topological symmetry but misses a center edge loop. In this case two matching edges to either side of the mesh need to be selected before running the operator.
• Island Pair Two islands which are symmetrical to each other on both sides of the mesh. Select two matching edges, one from each island, and run the operator.

Add Partial Symmetry
Partial symmetrical meshes usually lack topological symmetry; they are different, in parts, to either side of the mesh. Processing and mapping these islands is only possible by matching point positions. They also lack the ability to be completely mappable, due to the nature of asymmetry. The mapping process tries to find matching symmetrical vertices based on the position and a tolerance value. A lower tolerance value might miss a matching pair whereas a higher value finds too many matches, which results in a failed mapping. The usable approach is try various tolerance values and compare the results.

Partial mapping is also additive; this means that once vertices have been mapped they will be ignored in the next pass. This allows to perform several consecutive operations with different settings.

To further improve the workflow of partial mapping it’s possible to guide the matching process with a semi-automatic tolerance value. This is done by selecting two matching vertices from both sides of the mesh, i.e. from the side view. The position can be slighly offset. This relative offset will then be used to set the tolerance value for the next operation only. This way it’s possible to extend the map by mapping vertices with increasing tolerance values.

Select Mapped
This puts the mesh into Edit mode and selects all vertices which have been successfully mapped.

Select Unmapped
This puts the mesh into Edit mode and selects all vertices which have no assigned sibling on the other side of the mesh.

Select Sibling
Takes the current vertex selection and additionally selects the related sibling vertices on the other side of the mesh.

Delete Map
Removes the symmetry map from the mesh.

Mirroring

This section contains the tools which take advantage of an existing symmetry map. Currently the use is limited to the Smooth Weights brush and the Mirror Weights tool below. Since the symmetry map is stored in a custom property of the mesh it can be easily accessed and used.

Direction From
Defines in which direction the mirroring will be applied. The axis of the mirroring is set in the Mapping section of the panel. Positive means that the weights from the positive side of the mesh will be copied to the negative side and Negative will copy to the positive side.

Mirror Weights
Copies all vertex weights and vertex group assignments from one side of the mesh to the other. If the mesh is in Object mode all weights will be copied. If the mesh is in Editmode only the current selection will be used. All side-related vertex group names will be swapped and various naming conventions are supported (left/right, lt/rt, lft/rgt, lf/rg, l/r; all in upper-/lower-case).

Python Access

The symmetry map can be retrieved from the mesh using the following Python code

import bpy

# Get the symmetry map.
symMap = bpy.context.active_object.data['br_symmetry_map']

# Get the sibling index.
index = 5
sibling_index = symMap[index]

print(f"The sibling of vertex {index} is vertex {sibling_index}")

The map is an array of integers. The position of a value indicates the vertex index on one side and the value the sibling vertex on the other side. Unmapped vertices are marked with -1.

Smooth Weights offers a wide range of customizable options, available in the add-on preferences. These include setting preferred keymaps for favourite properties, colors and an individual layout for the pie menu.

Since the level of customization can be quite high it’s possible to save the current configuration in case a fresh installation of Blender is required. The current setup is saved as a file with the name config.json in the folder of the add-on. Save the file to a backup location and copy it back once the new setup is installed and running.