Structure

Blendshape Rig is a structure based on blendshapes, that can generate a geometry using a number of semantical weights called control values. Generating geometry from a Blendshape Rig involves blending blendshape vertices, but the blending method is more sophisticated than that used in the Blendshapes node.

A Blendshape Rig includes two distinct types of blendshapes with different blending behaviors: heroshapes and corrective blendshapes. Additionally, it incorporates relaxation vertex masks, and a rig configuration file, both of which influence the blending process.

Naming

Correct naming is essential to ensure the Blendshape Rig integrates properly into Wrap4D.

Component Names

Each component name consists of:

1. Expression name: Defines the expression type for a heroshape (JawOpen, LipsTogether, Gaze). The expression name should always be placed at the beginning of a heroshape name.

2. Suffixes: Provide additional semantic details. A heroshape name can have multiple suffixes, which can be loaded into Wrap4D even without specifying them. Some suffixes modify blending behavior, as explained in the *Control values*section. While optional, suffixes help refine the Blendshape Rig’s behavior.

Note

Wrap4D Gallery Blendshape Rig uses two types of suffixes:

Region Suffixes: Indicate the deformation region (e.g., L for left, R for right, B for bottom, T for top). Combinations like “L_B” represent regions such as “left bottom”.

Direction Suffixes: Define the deformation direction (e.g., Left, Right, Up, Down, In, Out). These are often used for gaze direction.

3. Attribute separator: Separates the Expression name and Suffixes usually with an underscore (“_”). For example: ExpressionName1_Suffix1.

4. Separator: Separates heroshape names in corrective blendshapes and relaxation masks, typically with a hyphen (“-“). For example: ExpressionName1_Suffix1-ExpressionName2_Suffix2.

Naming examples

Here are some examples of heroshape, corrective blendshape, and relaxation mask names, along with their interpretations.

1. Gaze_L_Right: Left eye gaze direction to the right;

2. Funnel_B_R: Bottom right part of the funnel expression;

3. Jaw_Left: Moving jaw to the left side;

4. UpperLipRaise_L: Raising of the left part of the upper lip;

5. UpperLipRaise_L-NoseWrinkle_L: Corrective blendshape or relaxation mask for left parts of UpperLipRaise and NoseWrinkle expressions.

Note

In Wrap4D, the order of suffixes in heroshape and control names does not affect their interpretation. For example, Funnel_B_R and Funnel_R_B represent the same heroshape.

Blendshape Rig Components

Neutral

The neutral geometry is the base geometry of the Blendshape Rig. All blendshape deltas of the rig are computed relative to this neutral geometry. All blendshapes and vertex masks must have the same topology and number of vertices as the neutral geometry.

Heroshapes

As mentioned earlier, a Blendshape Rig consists of two types of blendshapes with different blending behaviors: heroshapes and corrective blendshapes. A heroshape is a blendshape, that has its own blending weight (control value). This blending weight can be set by user. A Blendshape Rig consisting solely of heroshapes functions similarly to the Blendshapes node. Each heroshape name follows a specific structure: it begins with the Expression name followed by optional suffixes, separated by Attribute separator. For example: NeckStretch_L - for stretching the left part of the neck, CornerPull_R - heroshape for smiling with the right side of the face.

You can see the blending example of the JawOpen and BrowRaise heroshapes below..

Corrective Blendshapes

A Corrective Blendshape is a blendshape that overrides the result of a corresponding heroshapes blending. The name of a Corrective Blendshape consists of multiple heroshape names with overriden blending combination, separated by a Separator. For example: JawOpen-UpperLipRaise-MouthStretch: A corrective blendshape that overrides the blending results of the JawOpen, UpperLipRaise and MouthStretch.

Corrective Blendshapes should have a clear semantic meaning. For example, when blending JawOpen and LipsTogether in a Blendshape Rig, the expected result an opened jaw and a closed mouth. However, using only heroshapes might still leave the mouth partially open. To fix this, you should add a JawOpen-LipsTogether corrective blendshape with open jaw and a fully closed mouth.

Each Corrective Blendshape has its own blending weight. However, unlike heroshapes, the blending weight of a corrective blendshape cannot be manually set by user. nstead, it is calculated as the product of the corresponding heroshape weights. For example:

If the JawOpen heroshape weight is 0.5,

The UpperLipRaise heroshape weight is 0.4,

The MouthStretch heroshape weight is 0.3,

Then JawOpen-UpperLipRaise-MouthStretch corrective blendshape weight will be calculated as:

0.5 * 0.4 * 0.3 = 0.06.

To override the result of a blendshapes blending, we compute the delta between the corrective blendshape and the corresponding heroshapes blending combination (including corrective blendshapes of lower levels). While blending heroshapes and corrective blendshapes, as corrective delta we use this pre-computed delta as the corrective delta, rather than the delta between the corrective blendshape vertices and the neutral geometry.

An example of heroshape and corrective blendshape blending computation is provided at the end of this page. You can also see the difference between blending the JawOpen and LipsTogehter heroshapes without and with the corrective blendshape below.

Relaxation Masks

A Relaxation Mask is a vertex mask used to soften the effect of heroshape deltas. Similar to corrective blendshapes, the purpose of a Relaxation Masks is to improve heroshape combinations. However, unlike corrective blendshappes Relaxation Mask do not have semantical meaning. They are typically added when the blending result of two heroshapes produces undesirable effects, and the deltas of one heroshape need to be relaxed to resolve the issue. Relaxation Masks enhance the robustness of the Blendshape Rig but add a slight computational overhead.

Naming

The name of Relaxation Mask consists of two heroshape names, separated by a Separator.

1. The first heroshape name specifies the heroshape whose deltas will be relaxed.

2. The second heroshape name specifies the heroshape whose activation will trigger the relaxation of first heroshape’s deltas.

For example:

Dimple-CornerPull : When the weight of the CornerPull heroshape weight is more than 0, the deltas of the Dimple heroshape will be relaxed. When the weight is 1, the deltas will be relaxed the most.

Relaxation mask values define the relaxation weight for each vertex: A weight of 0 means the vertex delta is relaxed to zero. Higher weights correspond to a less pronounced relaxation

Relaxation Masks make the Blendshape Rig more resilient to problematic combinations but may slightly increase computational complexity.

Below, you can see:

The difference between blending the CornerPull and Dimple heroshapes without and with Dimple-CornerPull Relaxation Mask.

The Relaxation mask Dimple-CornerPull itself.

Control Names, Values and Ranges

As was mentioned before, Blendshape Rig can generate a geometry using a number of semantical weights, called Control Values. Each Control is allocated with a Control Name. By default, the Control Names in the Blendshape Rig correspond to the names of its heroshapes. The range of each control is initially set to 0 to 1. In the example below, you will see how to create new controls by combining existing ones.

Example Setup

Consider a Blendshape Rig with four heroshapes:

1. Jaw_L_Left

2. Jaw_L_Right

3. Jaw_R_Left

4. Jaw_R_Right

The default control names and values are visualized in the Blendshape Rig node’s editor.

Control Merging

In Wrap4D, controls can be modified by merging them into a single control. This is achieved in two ways, each serving a distinct purpose. These methods rely on suffix specifications defined in the Rig Configuration File, which also imposes naming restrictions.

Synchronized Suffixes

Synchronized Suffixes merge multiple controls into one. This is useful when controls must always activate together.

1. Specification: Define pairs of suffixes (e.g., L and R) and the expression names to merge.

2. Result: Controls with synchronized suffixes are replaced by a single control, maintaining a range of 0 to 1.

Example:

With synchronized suffixes L and R, controls Jaw_L_Left and Jaw_R_Left are combined into Jaw_Left. Similarly, Jaw_L_Right and Jaw_R_Right are combined into Jaw_Right.

You can see the result of applying Synchronized Suffixes to the initial Blendshape Rig below. The heroshapes remain unchanged, but:

1. Jaw_L_Left and Jaw_R_Left controls are combined into Jaw_Left.

2. Jaw_L_Right and Jaw_R_Right controls are combined into Jaw_Right.

Note

By default Wrap4D defines the following Synchronized Suffixes pairs: L and R, B and T.

Mirror Suffixes

Mirror Suffixes merge two controls with opposite semantics into one. This is useful when controls cannot activate simultaneously.

1. Specification: Define pairs of suffixes (e.g., Left and Right) and a result suffix to replace them.

2. Result: The new control has a range of -1 to 1, where: 1 activates the first suffix (e.g., Left). -1 activates the second suffix (e.g., Right).

You can see the result of applying Mirror Suffixes to the initial Blendshape Rig below. The heroshapes remain unchanged, but: 1. Jaw_L_Left and Jaw_L_Right controls are combined into Jaw_L_Side. 2. Jaw_R_Left and Jaw_R_Right controls are combined into Jaw_R_Side.

Note

By default, Wrap4D defines the following mirror suffix pairs: Left and Right and result suffix: Side Up and Down and result suffix: Vertical Out and In result suffix: InOut

You can see the result of applying Mirror Suffixes and Synchronized Suffixes to the initial Blendshape Rig below. The heroshapes remain unchanged, all control values are merged into a single control, Jaw_Side.

You can also see the result of using the Blendshape Rig with four heroshapes and one control value.

Attention

Restrictions for Synchronized Suffixes: If you define a pair of Synchronized Suffixes (e.g., L and R), it becomes invalid to use both suffixes in the same heroshape name. Example: If you set Synchronized Suffixes as L and R, a heroshape named JawOpen_L_R will no longer be allowed.

Attention

Restrictions for Mirror Suffixes: When using Mirror Suffixes, you must ensure symmetry between heroshapes. This means if a heroshape includes one suffix of a mirror pair, the corresponding heroshape with the other suffix must also exist. Example: If you define Left and Right as Mirror Suffixes and have a heroshape named Jaw_Left, you must also have a heroshape named Jaw_Right.

Rig Configuration File Structure

The Rig Configuration File is a JSON file with specified Synchronized Suffixes and Mirror Suffixes.

By default, the Rig Configuration File contains no predefined suffixes. Below is an example of the basic structure:

{
    "version": 2,
    "SynchronizedSuffixes": []
    "MirrorSuffixes": []
}

Adding Synchronized Suffixes

To add Synchronized Suffixes, include the suffixes and the associated heroshape expressions. The example below demonstrates how to add L and R suffixes for the JawOpen and JawOpenExtreme heroshapes:

{
    "version": 2,
    "SynchronizedSuffixes": [
    {
        "Suffixes": ["L", "R"],
        "Blendshapes": ["JawOpen", "JawOpenExtreme"]
    }
    ]
    "MirrorSuffixes": []
}

Adding Mirror Suffixes

To define Mirror Suffixes, specify the suffix pair and the resulting combined suffix. For instance, the following example adds Left and Right as mirror suffixes with the resulting suffix Side:

{
    "version": 2,
    "SynchronizedSuffixes": [],
    "MirrorSuffixes": [
    {
        "FirstSuffix": "Left",
        "SecondSuffix": "Right",
        "ResultSuffix": "Side"
    }
    ]
}

Below you can see the example of Wrap4D default Rig Configuration File.

{
    "version": 2,
    "SynchronizedSuffixes": [
    {
        "Suffixes": ["L", "R"],
        "Blendshapes": []
    },
    {
        "Suffixes": ["T", "B"],
        "Blendshapes": []
    }
    ],
    "MirrorSuffixes": [
    {
        "FirstSuffix": "Left",
        "SecondSuffix": "Right",
        "ResultSuffix": "Side"
    },
    {
        "FirstSuffix": "Up",
        "SecondSuffix": "Down",
        "ResultSuffix": "Vertical"
    },
    {
        "FirstSuffix": "Out",
        "SecondSuffix": "In",
        "ResultSuffix": "InOut"
    }
    ]
}

Blendshape Rig Controls File Structure

The Blendshape Rig Controls File is a JSON fa JSON file that defines the control names and their corresponding values for a Blendshape Rig. This file allows you to explicitly specify the controls used in the rig and their initial or default values.

Example of a Blendshape Rig Controls File

Below is an example of a Blendshape Rig Controls File for a rig containing four controls Funnel_L_B, Jaw_Left_R, Jaw_Right_R, Gaze_L_Vertical.

{
    "controlValues": {
        "Funnel_L_B": 0.4,
        "Jaw_Left_R": 1.0,
        "Jaw_Right_R": 0.0,
        "Gaze_L_Vertical" : -0.3,
    },
    "formatVersion": 1
}

Heroshapes, Corrective Blendshapes and Relaxations Masks blending computing examples

Below are examples demonstrating how heroshapes, corrective blendshapes, and relaxation masks are blended in a Blendshape Rig. These examples use a simplified rig with a single vertex for clarity.

Default Blendshape Rig Setup

The default Blendshape Rig includes:

1. Neutral geometry: Vertex at (1, 0, 0)

2. JawOpen heroshape: Vertex at (1, 1, 0)

3. LipsTogether heroshape: Vertex at (1, 0, 1)

Heroshapes Blending

Let’s explore a simple example of blending heroshapes without the use of corrective blendshapes or relaxation masks. For this, we will use the default Blendshape Rig without any modifications.

To compute JawOpen blending delta, subtract neutral vertices from JawOpen heroshape vertices:

(1, 1, 0) - (1, 0, 0) = (0, 1, 0).

To compute LipsTogether blending delta, subtract neutral vertices from LipsTogether heroshape vertices:

(1, 0, 1) - (1, 0, 0) = (0, 0, 1).

Calculate the blending result of heroshapes with heroshape weights 1:

(1, 0, 0) + 1 * (0, 1, 0) + 1 * (0, 0, 1) = (1, 1, 1).

Heroshapes and Corrective Blendshapes Blending

Example 1: JawOpen-LipsTogether Corrective Blendshape.

Initial Setup

We start with the following Blendshape Rig setup:

1. Neutral geometry: Vertex at (1, 0, 0)

2. JawOpen heroshape: Vertex at (1, 1, 0)

3. LipsTogether heroshape: Vertex at (1, 0, 1)

Step 1: Calculate Heroshape Blending Deltas

To calculate the deltas for each heroshape, subtract the neutral vertex from the corresponding heroshape vertex:

JawOpen blending delta:

(1, 1, 0) − (1, 0, 0) = (0, 1, 0)

LipTogether blending delta:

(1, 0, 1) − (1, 0, 0) = (0, 0, 1)

Step 2: Compute the Blending Result of Heroshapes

Combine the neutral vertex with the JawOpen and LipsTogether deltas to compute their blending result:

(1, 0, 0) + (0, 1, 0) + (0, 0, 1) = (1, 1, 1).

Step 3: Calculate Corrective Blendshape Delta

To calculate the JawOpen-LipsTogether corrective blendshape delta, subtract the blending result of the heroshapes from the corrective blendshape vertex:

(1, 0.5, 0.5) - (1, 1, 1) = (0, -0.5, -0.5).

Step 4: Verify Blending Combination

Now, let’s check the blending result when all weights (for JawOpen, LipsTogether, and the corrective blendshape) are set to 1:

(1, 0, 0) + 1 * (0, 1, 0) + 1 * (0, 0, 1) + 1 * 1 * (0, -0.5, -0.5) = (1, 0.5, 0.5).

The final blending result is (1, 0.5, 0.5), which matches the vertex of the JawOpen-LipsTogether corrective blendshape. This confirms that the blending computation is correct.

Example 2: Funnel-JawOpen-LipsTogether Corrective Blendshape

Initial Setup

We extend the Blendshape Rig from the first example by adding:

Funnel heroshape: (2, 0, 0)

Funnel-JawOpen-LipsTogether corrective blendshape: (2, 2, 2)

Step 1: Calculate Funnel Heroshape Blending Delta

(2, 0, 0) - (1, 0, 0) = (1, 0, 0).

Step 2: Compute the Blending Result of **JawOpen, LipsTogether and Funnel heroshapes**

Combine the neutral vertex with the deltas of JawOpen, LipsTogether, and Funnel heroshapes, as well as the JawOpen-LipsTogether corrective delta. This gives:

(1, 0, 0) + 1 * (1, 0, 0) + 1 * (0, 1, 0) + 1 * (0, 0, 1) + 1 * 1 * (0, -0.5, -0.5) = (2, 0.5, 0.5),

Here:

(0, -0.5, -0.5) is JawOpen-LipsTogether blending delta

Step 3: Calculate Funnel-JawOpen-LipsTogether Corrective Blendshape Delta

To compute the Funnel-JawOpen-LipsTogether corrective blendshape delta, subtract the blending result of JawOpen, LipsTogether, and Funnel heroshapes from the Funnel-JawOpen-LipsTogether corrective blendshape vertex:

(2, 2, 2) - (2, 0.5, 0.5) = (0, 1.5, 1.5).

Step 4: Verify Blending Combination

Finally, let’s verify the blending result when all heroshape weights (Funnel, JawOpen, LipsTogether, and the corrective blendshapes) are set to 1:

(1, 0, 0) + 1 * (1, 0, 0) + 1 * (0, 1, 0) + 1 * (0, 0, 1) + 1 * 1 * (0, -0.5, -0.5) + 1 * 1 * 1 * (0, 1.5, 1.5) = (2, 2, 2).

Conclusion The final blending result is (2, 2, 2), which matches the vertex of the Funnel-JawOpen-LipsTogether corrective blendshape. This confirms that the blending computation is accurate