Documentation for 'Weight Paint and Bones: A Blender Toolkit'

Welcome to the documentation for 'Weight Paint and Bones: A Blender Toolkit'. This is a Blender addon that provides some extra tools for weight painting and bone editing tasks in Blender.

This documentation aims to give you a better understanding of some of the addon's features. We're not going to delve into every single feature — many of them are straightforward enough that they don't need extra explanation. But we will focus on the ones that might require a bit more understanding.

Using the Mirror Operation in 'Weight Paint and Bones: A Blender Toolkit'

The mirror operation in 'Weight Paint and Bones: A Blender Toolkit' works based on two fields: the source field and the destination field. These fields are located in the "Mirror Weights" tab of the addon's interface.

In a standard operation, you're required to specify both the source and destination groups in these fields. The addon will then mirror the weights from the source group to the destination group. This provides fine control over the operation, which is particularly useful when you're working with asymmetrical meshes or when the weight distribution didn't mirror correctly.

For example, when you're using the "Fill Missing Weights" option, the addon creates a "bounding box" from the source group and mirrors this box to the destination side. This requires that both the source and destination fields are specified.

Similarly, the "Select Missing Vertices" option operates by selecting vertices in the destination group that didn't get mirrored correctly. This can be particularly useful for quickly filling these vertices using the "Fill Only Selected Vertices" option.

On the other hand, for options like "Fill Only Selected Vertices" and "Smooth Weights", you only need to specify the destination field. These options work directly on the destination group, filling or smoothing the vertices in this group.

In contrast to the standard operation, the "Mirror Multiple Groups" option does not require you to select the source and destination fields. When you use this option, you only need to select the destination bones in your armature, and the addon will automatically mirror the weights from the corresponding source bones (with names ending in ".L" or ".R") to the destination bones. This method provides a faster way to mirror weights across multiple groups, but it doesn't allow for the use of additional controls for asymmetrical meshes or selective vertex operations. If a bone does not have a counterpart ending in ".L" or ".R", the weights are mirrored within the same group, based on the selected directions in the "Mirror Weights" tab.

Remember, the method you choose depends on the specific needs of your project. Understanding how each operation works will help you to use the addon more effectively.

In-depth: Weight Mirroring Features

In this section, we will provide a more detailed explanation of some of the key features involved in the weight mirroring process.

Auto-Select Missing Vertices

The "Select Missing Vertices" feature identifies and selects vertices in the destination group that didn't mirror correctly during the weight mirroring process. It does this by evaluating the neighboring vertices of each vertex in the group. If it determines that the vertex should have been affected by the mirroring (based on the weights of its neighbors), it marks that vertex for selection.

Please note that the use of this feature can impact performance, particularly with high-density meshes or on lower-spec machines, as it must evaluate each vertex individually. Furthermore, while the algorithm is designed to be as accurate as possible, it might occasionally select vertices that you might not want to include. Therefore, it's recommended to check the selected vertices after the operation.

This feature is particularly useful in conjunction with the "Fill Only Selected Vertices" option. After the "Select Missing Vertices" feature has identified the problematic vertices, you can use "Fill Only Selected Vertices" to specifically target and correct those vertices.

Fill Missing Weights

The "Fill Missing Weights" feature assists with weight mirroring when certain vertices on the destination side do not mirror correctly. It operates by creating a "bounding box" from the source group and using it to influence weights in the destination group. Here's how it works:

1. The addon identifies all vertices in the source group that have a weight greater than 0.
2. It calculates the minimum and maximum coordinates (x, y, z) among these vertices. This defines the bounding box of the weight-painted area in the source group.
3. During the filling process, this bounding box is replicated to the destination side. Any vertices in the destination group that fall within this mirrored bounding box are given weights based on their neighboring vertices.

To better understand how it works, consider this example:

Imagine the weight paint area in the source group has the following dimensions (what we refer to as a "bounding box"):
x: 1.0 to 3.0
y: -1.0 to 1.0
z: -1.0 to 1.0

This "bounding box" represents the spatial range where the weight paint exists on the source side. When mirroring along the x-axis without any bounding box adjustments, the mirrored destination box would have the following dimensions:
x: -3.0 to -1.0
y: -1.0 to 1.0
z: -1.0 to 1.0

However, if the user adjusts the bounding box size by a value of 1 on each axis, the dimensions of the mirrored bounding box would become:
x: -4.0 to 0.0
y: -2.0 to 2.0
z: -2.0 to 2.0

This flexibility in adjusting the mirrored bounding box size allows users to fill weights more accurately, enhancing the weight paint mirroring process.

Precise Bone Selection

The "Precise Bone Selection" feature provides a user-friendly pop-up menu for rapidly selecting, parenting, and switching active bones. This feature can be accessed using the keyboard shortcut 'CTRL+SHIFT+Q'. Here's a breakdown of its functionalities:

• Bone Selection: The pop-up menu displays a list of all currently selected bones. You can set a bone as the active bone by clicking on its name. Each bone also has an associated checkbox; when this box is checked, the bone will be selected when the operation ends. The operation concludes when you click on a bone's name, at which point all checked bones become selected, and the clicked bone becomes the active selection.
• Parenting and Unparenting Bones: The pop-up menu includes buttons for parenting and unparenting bones. These function the same way as the default parenting and unparenting buttons in Blender. They are included in this menu for the sake of convenience, putting all relevant bone selection and manipulation tools in one place.
• Swapping Active Bones: If exactly two bones are selected, you can use the 'Swap Active Bone' button to switch the active bone between the two selections.
  
  

Sequential Bone Parenting

The 'Sequential Bone Parenting' feature, located in the 'Custom Bone Tools' panel, offers a simplified and efficient way to parent bones. This tool can save significant time when setting up or modifying your rig. The panel contains three buttons: 'Start Selection', 'Keep Offset', and 'Connected'.

Here's a step-by-step guide on how to use this feature:

1. Start the selection: Click the 'Start Selection' button to begin the bone selection process.
2. Select the bones: Select the bones you wish to parent in the order you want them parented. The order of selection is crucial because the bones will be parented according to this order. The bones are added to a list in the order you select them.
3. Parent the bones: Click either the 'Keep Offset' or 'Connected' button to parent the bones. The parenting will follow the order in which you selected the bones.
   
   

Batch Constraint Assignment

The Batch Constraint Assignment feature, located in the 'Bone Constraint Generator' panel, provides a streamlined way to add the same constraint to multiple bones simultaneously, based on either their prefixes or suffixes. This feature can be a significant time-saver when setting up or modifying your rig. However, it's important to note that this feature only works with constraints that have a target setting.

Here's a guide on how to use this feature:

1. Specify the source and target prefixes or suffixes: You need to specify the source and target bone prefixes or suffixes. The source bones are the ones to which the constraint will be added, while the target bones are the ones that the constraint will reference. If you want to use suffixes instead of prefixes, check the 'Use Suffixes' option.
2. Choose the constraint: Select the type of constraint you want to add from the drop-down menu.
3. Add the constraint: Click the 'Add Bone Constrains' button to add the specified constraint to all bones with the source prefix or suffix. The constraint will reference the corresponding bone with the target prefix or suffix.

If you wish to add the constraints to only a selected bone, enable the 'Apply to Selected Bones Only' option. This ensures that the constraints are added only to the selected source bones.