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 based on blendshape vertices blending, but the way of the blendshape vertices blending is more complex than in the Blendshapes node.

Blendshape Rig consists of two different types of blendshapes with different blending behaviour, they are called heroshapes and corrective blendshapes. Blendshape Rig also contains relaxation vertex masks, rig configuration file, they are modify blending behaviour too.

Naming

Before we start talking about components of a Blendshape Rig, to make examples easier to understand, let’s talk about naming in a Blendshape Rig. The structure of a Blendshape Rig in Wrap4D depends on each Blendshape Rig component name, so you need to name your blendshapes and masks using following rules to load Blendshape Rig into Wrap4D correctly.

Name components

Each component name of a Blendshape Rig consists of the same parts. In the description below we will talk about this parts in case of heroshape names, because corrective blendshape names and relaxation mask names consist of number of heroshape names.

1. Expression name defines expression type of a heroshape. For example: JawOpen, Funnel, LipsTogether, Gaze. Expression name should be located at the beginning of a heroshape name.

2. Suffixes specify some semantical information of an expression. Heroshape name could contain any number of suffixes in any order and you can load any suffix to Wrap4D without specifying it. In Wrap4D you can specify suffixes that modify blending behaviour. You can read about them in Control values documentation part. In general, you can use Blendshape Rig in Wrap4D without suffixes at all.

Note

For example, in Wrap4D gallery Blendshape Rig there are two types of suffixes. First type is a region suffix, that specifies heroshape deformation region. We use L, R, B, T suffixes, that corresponding to the left, right, bottom and top region of the face. You can combine this suffixes to specify, for example, left bottom region of the face. Second type is a direction suffix, that specifies heroshape deformation direction. We use Left, Right, Up, Down, In, Out suffixes. Using this suffixes, we can specify, for example, Gaze direction for each eye and each direction.

3. Attribute separator separates Expression name and Suffixes in a heroshape name. By default it is “_”. For example: ExpressionName1_Suffix1.

4. Separator separates heroshape names in corrective blendshape names and relaxation mask names. By default it is “-”. For example: ExpressionName1_Suffix1-ExpressionName2_Suffix2.

Naming examples

Below are some examples of heroshape, corrective blendshape and relaxation mask names with their interpretation.

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 heroshape and control names are independent to the suffixes order. For example, Funnel_B_R and Funnel_R_B are the same heroshape.

Blendshape Rig Components

Neutral

Neutral geometry is a base geometry of the Blendshape Rig. All blendshape deltas of the rig are computing using this neutral geometry. All blendshapes and vertex masks must have the same topology and number of vertices as neutral geometry.

Heroshapes

As stated earlier, Blendshape Rig consists of two different types of blendshapes with different blending behaviour, they are called heroshapes and corrective blendshapes. Heroshape is a blendshape, than has it’s own blending weight (control value). Blendshape Rig with only heroshapes equals to the Blendshapes node. Each heroshape name consists of Expression name at the first place, and suffixes, separated by Attribute separator. For example: NeckStretch_L - heroshape with stratched left part of a neck, CornerPull_R - heroshape with smiling by the right part of a face. You can find heroshapes blending computing example at the end of this page.

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

Corrective Blendshapes

Corrective Blendshape is a blendshape, that overrides the result of a corresponding heroshapes blending. Corrective Blendshape name consists of number of heroshape names with overrided blending combination, splitted by Separator. For example, corrective blendshape with name JawOpen-UpperLiRaiser-MouthStretch overrides the blending result of JawOpen, UpperLipRaise and MouthStretch heroshapes.

Corrective Blendshapes should have semantic meaning. For example, if you are blending JawOpen and LipsTogether in a Blendshape Rig, you are expecting to get an opened jaw and closed mouth, but using only heroshapes mouth still can be opened. To fix this, you should add JawOpen-LipsTogether corrective blendshape with opened jaw and closed mouth.

Each Corrective Blendshape has it’s own blending weight, but unlike heroshape blending weight, corrective blendshape blending weight can’t be set by user. This blending weight is a product of all corresponding blendshape weights. For example, if your Blendshape Rig contains JawOpen-UpperLiRaiser-MouthStretch corrective blendshape, JawOpen heroshape weight equals to 0.5, UpperLipRaise heroshape weight equals to 0.4, MouthStretch heroshape weight equals to 0.3, then JawOpen-UpperLiRaiser-MouthStretch weight equals to 0.5 * 0.4 * 0.3 = 0.06.

To override the result of a blendshapes blending we compute delta between corrective blendshape and corresponding heroshapes blending combination (including corrective blendshapes of lower levels). While blending heroshapes and correctives, as corrective delta we use computed delta before, not the delta between corrective blendshape vertices and neutral vertices. You can find heroshapes and corrective blendshapes blending computing example at the end of this page.

You can see the the difference between blending of the JawOpen and LipsTogehter heroshapes without corrective blendshape and with it below.

Relaxation Masks

Relaxation Mask is a vertex mask relaxing heroshape deltas. The reason to use Relaxation Mask is similar to corrective blendshapes: update heroshapes combination. But unlike corrective blendshappes, Relaxation Masks don’t need to have semantical meaning. Relaxation Masks can be added in case when the blending result of two heroshapes is broken, and you need to relax blending result of this heroshapes. Every Relaxation mask makes Blendshape Rig harder to break, but makes rig computations a little bit harder.

Relaxation Mask name consists of two heroshape names, splitted by Separator. First heroshape name defines heroshape, which deltas will be relaxed, second heroshape name defines heroshape, which activation will relax first heroshape’s deltas. For example, Dimple-CornerPull relaxation mask means, that when CornerPull heroshape weight is 1, Dimple blending deltas will be relaxed. Relaxation mask value defines relaxation weight for each vertex, where weight 0 equals to making vertex delta to zero. You can find heroshapes with relaxation masks blending computing example at the end of this page.

You can see the the difference between blending of the CornerPull and Dimple heroshapes without relaxation mask Dimple-CornerPull and with it below. You can also see relaxation mask Dimple-CornerPull itself below.

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 also has it’s name, called Control Name. When you just load all heroshapes, corrective blendshapes and relaxation masks of your Blendshape Rig, control names of the Blendshape Rig will be equal to the heroshape names of this Blendshape Rig. By default, each control, generated from heroshape, has values range from 0 to 1.

As example, we will use Blendshape Rig with only four heroshapes: Jaw_L_Left, Jaw_L_Right, Jaw_R_Left, Jaw_R_Right. Any Blendshape Rig node has visual editor with visualized control values. We will use it to show the changes in Blendshape Rig with using different suffixes. You can see the initial Blendshape Rig control values below.

In Wrap4D you can modify controls by merging them into one control. This can be done in two ways, and each ways has it’s own purpose. In both cases we will specify some suffixes with updated behaviour, and heroshapes naming with this suffixes will have some restrictions. This suffixes will be specified in Rig Configuration file, we will talk about in below.

1. Using Synchronized Suffixes you can merge a number of controls into one control. You can use this suffix when you have controls that shoud be activated only together. When you specify Synchronized Suffixes, you also need to specify expression names (not heroshape names!), which should be merged using this suffixes. When controls are merging into one control, their Synchronized Suffixes will be replaced. Result control has values range from 0 to 1. For example, you can set Synchronized Suffixes as L and R, and your control value Jaw_L_left and Jaw_R_Left will always be equal to Jaw_Left control value.

Note

In default Wrap4D Blendshape Rig as Synchronized Suffixes selected pairs L and R, B and T.

You can see the result of applying Synchronized Suffixes to the initial Blendshape Rig below. Heroshapes remain unchanged, but Jaw_L_Left and Jaw_R_Left controls were combined to Jaw_Left control, Jaw_L_Right and Jaw_R_Right controls were combined to Jaw_Left control.

2. Using Mirror Suffixes you can merge two controls with semantically opposite meaning into one control. You can use this suffix when you have controls that can’t be activated together. Result control has values range from -1 to 1. Result control value 1 activates control with first suffix, result control value -1 activates control with second suffix. When you specify Mirror Suffixes, you should specify result suffix to replace MirrorSuffixes. For example, you can set Mirror Suffixes as Left, Right and result suffix as Side, then Jaw_L_Left and Jaw_L_Right control values will be combined into control value Jaw_L_Side.

Note

In default Wrap4D Blendshape Rig as Mirror Suffixes selected pairs Left, Right and result suffix Side; Up, Down and result suffix Vertical; Out, In and result suffix InOut.

You can see the result of applying Mirror Suffixes to the initial Blendshape Rig below. Heroshapes remain unchanged, but Jaw_L_Left and Jaw_L_Right controls were combined to Jaw_L_Side control, Jaw_R_Left and Jaw_R_Right controls were combined to Jaw_R_Side control.

You can see the result of applying Mirror Suffixes and Synchronized Suffixes to the initial Blendshape Rig below. Heroshapes remain unchanged, all control values were combined to Jaw_Side control.

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

Attention

When you add a new pair of suffixes to Synchronized Suffixes or Mirror Suffixes, you can no longer use both suffixes of the pair in one heroshape name. For example, if set Synchronized Suffixes as L and R, heroshape JawOpen_L_R becomes unavailable.

Attention

When you add a new pair of suffixes to Mirror Suffixes, you can no longer have heroshape with first suffix of the pair without the same heroshape with second suffix of the pair. For example, if you set Mirror Suffixes as Left, Right, if you have heroshape named “Jaw_Left”, you must have heroshape named “Jaw_Right”.

Rig Configuration File Structure

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

Example of the default Rig Configuration File without any suffix described below.

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

You can add new SynchronizedSuffixes to the default Rig Configuration File using the example below. In this example we will add L and R suffixes for JawOpen, JawOpenExtreme heroshapes.

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

You can add new MirrorSuffixes to the default Rig Configuration File using the example below. In this example we will add Left and Right suffixes and the result 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

Blendshape Rig Controls File is a JSON file with specified Blendshape Rig control names and values. Below you can see the example with Blendshape Rig Controls File, where Blendshape Rig contains 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

You can see examples of blending heroshapes and corrective blendshapes using relaxation masks below. It can help to clarify computing processes of the Blendshape Rig. In each example will be used Blendshape Rig with only one vertex. We will define default Blendshape Rig and in each experiment we may modify it.

Our default Blendshape Rig for examples contains Neutral geometry with vertex (1, 0, 0), JawOpen heroshape with vertex (1, 1, 0), LipsTogether heroshape with vertex (1, 0, 1)

Heroshapes Blending

Let’s have a look at simple heroshapes blending without corrective blendshapes and relaxation masks. We will use default Blendshape Rig without any changes. First, we need to compute JawOpen and LipsTogether heroshapes Blending deltas.

To compute JawOpen blending delta, we will substract neutral vertices from JawOpen heroshape vertices:

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

To compute LipsTogether blending delta, we will substract neutral vertices from LipsTogether heroshape vertices:

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

Let’s compute 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

First example.

Let’s add to the initial Blendshape Rig JawOpen-LipsTogether corrective blendshape with vertex (1, 0.5, 0.5). As in previous example, JawOpen blending delta equals to (0, 1, 0), LipsTogether blending delta equals to (0, 0, 1). To compute corrective blendshape blending delta we first need to compute blending result of JawOpen and LipsTogether heroshapes. It equals to

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

To compute JawOpen-LipsTogether blending delta we need to substract blending result of JawOpen and LipsTogether heroshapes from the JawOpen-LipsTogether corrective blendshape vertices:

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

Lets check blending combination, where all heroshape weights are equal 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),

and it is equals to JawOpen-LipsTogether corrective blendshape vertex.

Second example

Lets add to the Blendshape Rig from the first example Funnel heroshape with vertex (2, 0, 0) and Funnel-JawOpen-LipsTogether corrective blendshape with vertex (2, 2, 2). Funnel heroshape blending delta equals to

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

Blending result of JawOpen, LipsTogether and Funnel heroshapes equals to

(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),

where (0, -0.5, -0.5) is JawOpen-LipsTogether blending delta. Then Funnel-JawOpen-LipsTogether blending delta equals to

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

Lets check blending combination, where all heroshape weights are equal 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),

and it is equals to corrective blendshape vertex.