Welcome to the ReveRig Documentation

ReveRig is a Blender Add-on specially designed to facilitate the facial animation process, from the creation of the face rig to the retargeting phase up to allowing precise management of the facial animation itself.

Overview

At the moment ReveRig is specially designed to manage the facial animation of characters with 52 shape keys (blendshape) provided by Apple ARKit. The presence of these shape keys is essential if you want to achieve facial motion capture with iPhone X and other Apple devices.

Motivation

Although performance capture systems are very good, the captured data is not always up to the required result (especially if the desired result must be Pixar-style). Reverig has been developed to offer the artist a set of tools essential to be able to manage the animation process on Blender in a simple, fast, and precise way.

Index

1. Installation
   1. Update
2. Important Reads
   1. ARKit shape keys
   2. How to create the 52 ARKit shape keys
   3. Pupil control
3. How does ReveRig work?
4. Facial Rigging
   1. What to do if your character has more than 5 meshes or if it has meshes other than those indicated by ReveRig?
   2. The Rig Interface
5. Animation Retargeting
6. Drivers Manager
7. Support

Installation

Like most Blender Add-ons, you install ReveRig in the User Preferences.
Edit > Preferences > Add-ons > Install 

ReveRig comes in a .Zip folder.  You must unpack it (extract the folder contents). Once unpacked, navigate to your addon preferences (Edit>Preferences>Addons), click the Install button and browse the filepath to wherever you saved your ReveRig copy and select the .py file (ReveRig.py).
Afterwards you will need to enable the Add-on by clicking the enable checkbox. Watch the quick tutorial on Youtube.

How to install it

If you don’t see the addon in Blender’s Preferences, the causes could be the following:

• during the installation you selected the compressed folder (.zip).
  You don’t have to install the zip file
• you have extracted the compressed file but during the installation you selected the folder and not the python file (ReveRig.py).

If you are in one of these situations try installing the add-on again in the correct way.

To verify that everything has been run correctly, we recommend that you open the folder C:\Users{user name}\AppData\Roaming\Blender Foundation\Blender\2.92{Blender version}\scripts\addons\ containing all the installed addons and verify that ReveRig appears as a single python file (.py) and not as a folder.

Update

To update, simply follow the installation steps and overwrite the current installation. (It might be necessary to restart Blender for an Update to take effect.)

Install or Update the Add-on 

Enable the Add-on 

Find the add-on in the 3D View. (REVERIG panel) 

Important Reads

ReveRig was developed to significantly facilitate facial animation work.   In particular, it is designed to integrate perfectly with the animation based on the 52 shape keys (blendshapes) defined by ARKit.

ARKit Shape Keys (Blendshapes)

The 52 ARKit shape keys are a prerequisite if you want to perform facial motion capture with the iPhoneX and other apple devices with True Depth Camera.

• Phone X, XR, XS, XS Max, 11, 11 Pro, 11 Pro Max
• iPad Pro 3rd or 4th generation.

Note! You cannot use other hardware than these devices.

Each Shape Key stores a distinctive micro expression, such as mouthRollUpper, eyeBlinkLeft or mouthDimpleRight etc. Only the combination of these 52 micro expressions will result in good looking animation. 

Note! ReveRig is not used to create the 52 shape keys but offers the animator a series of useful tools to be able to manage them in the best way. 

The correct functioning of ReveRig is mainly based on the correctness of the 52 shape keys both in terms of deformations applied and in terms of nomenclature used.  Therefore before using ReveRig it is necessary to make sure that the model of the character you want to animate is correctly set.

To make sure that the shape keys produce the desired expressions you can refer to what is indicated on the official  Apple Developer website. (The shape keys are called blendshape ).  On the same site, you can check the correct nomenclature to use on your character, for convenience, we report it below.

• Brows: browOuterUpRight, browDownRight, browInnerUp, browDownLeft, browOuterUpLeft.
• Eyes: eyeBlinkLeft, eyeLookDownLeft, eyeLookInLeft, eyeLookOutLeft, eyeLookUpLeft, eyeSquintLeft, eyeWideLeft, eyeBlinkRight, eyeLookDownRight, eyeLookInRight, eyeLookOutRight, eyeLookUpRight, eyeSquintRight, eyeWideRight.
• Cheeks&Nose: cheekPuff, cheekSquintLeft, cheekSquintRight, noseSneerLeft, noseSneerRight.
• Mouth: mouthFunnel, mouthPucker, mouthLeft, mouthRight, mouthRollUpper, mouthRollLower, mouthShrugUpper, mouthShrugLower, mouthClose, mouthSmileLeft, mouthSmileRight, mouthFrownLeft, mouthFrownRight, mouthDimpleLeft, mouthDimpleRight, mouthUpperUpLeft, mouthUpperUpRight, mouthLowerDownLeft, mouthLowerDownRight, mouthPressLeft, mouthPressRight, mouthStretchLeft, mouthStretchRight.
• Jaw: jawForward, jawLeft, jawRight, jawOpen.
• Tongue: tongueOut.

How to create the 52 ARKit shape keys

If your character is not yet equipped with the necessary 52 shape keys then, before you can use the tools offered by ReveRig it is essential to go and generate them.

The main approaches that can be adopted are 3:

• You can manually create each of the 52 required shape keys. This approach is only recommended for medium / highly experienced modelers. The whole process could take several hours if not days, but if you are a skilled modeler and don't have time problems then this is a good approach because you have total control over the final result.
• A second approach is to turn to external paid services such as  Polywink. This service offers the possibility of having the model with the desired shape keys within 24 hours, however, the cost of the operation is quite high therefore not recommended for independent productions.
• The approach that most of all we go so far as to recommend is to use the Blender add-on Faceit. Thanks to this add-on it is possible to create the 52 shape keys required in less than a day of work, and the user also has control over the entire creation process.
• Another approach is to download or purchase 3D models already equipped with the necessary 52 shape keys. A  popular online shop is  Daz.
• Since version 3.4 CC3 (Character Creator) has also added the 52 ARKit blendshape to its character creation process (note that you will need to rename them correctly).

If you are aware of other possible approaches not yet listed above, feel free to write them to us under Ask a Question to always keep the documentation up to date.

Note! It is not mandatory to have all 52 ARKit blendhshapes,  theoretically ReveRig allows you to control even just one of the shape keys mentioned above,  however as ReveRig works mainly on these, the best results will be obtained where the greatest number of facial expressions will be present.

Pupil Control

ReveRig also offers the possibility to manage four additional shape keys not included among the 52 of ARKit. These 4 blendshapes are designed for pupil control (expansion and contraction) in order to make the character even more expressive.  These are totally optional and a lack of them will not affect the functioning of the add-on. 

These shape keys must be named: eyePupilDilateRight, eyePupilContractRight, eyePupilDilateLeft, eyePupilContractLeft.  (ReveRig is case sensitive)

How does ReveRig Work?

Reverig is divided mainly into three tasks: 

• Automates the creation of the facial rig equipped with all the necessary controls for proper animation of the 56 shape keys (52 ARKit + 4 pupil).
• Offers interface and tools to carry out retargeting operation quickly and easily. 
• It offers an interface and a facial rig specially designed to facilitate the work of the animator. Through a series of controls, it is possible to precisely manage the entire facial animation process.

For each of these tasks, a special panel has been created.

Facial Rigging

The first panel includes all the main tools to create the facial rig and tie it to the desired character. The creation of the facial rig is a mandatory step for the proper functioning of ReveRig. It must therefore be the first operation to be carried out.

If the character you want to animate has the prerequisites indicated previously in Important Reads (ie the 52 shape Keys of ARKit) you can proceed with the first step that involves the use of ReveRig. The creation of the facial rig.

 Initial Interface 

The first screen that will be shown will be like the one shown above. The only tool available to the user is the button Create Facial Rig Armature. If in the scene is selected or active armature of any type, then the interface shown will be the following.

Interface if an Armature object is selected/active. 

The first operation to do is to click on the Create Facial Rig Armature button to create the actual facial rig. This is an armor-type object, where each slider consists of at least two bones. The rig creation is fully automatic so just press the button and wait for the Armature to appear on screen in the 3D Viewport. The entire process should take a few seconds, however, it is possible that in projects with very complex scenes it is necessary to wait a few more moments. The newly created facial rig is named GUI_Char_SK. This way you can replace Char with the name of the character maintaining a global convention (ex GUI_Nadya_SK).

Once the rig is created it is likely to be necessary to perform some scaling and translation operation to place it next to the face of the character that you want to animate.

Create Facial Rig 

NOTE! To avoid possible problems, disable the Auto Keying before proceeding with the repositioning of the rig.

Now the Armature of the facial rig has been created but is not yet linked to any object so it is not yet able to control the animation of the character. You can check to be in this situation simply by selecting the rig and entering Pose Mode and trying to move some slider. This will not produce any deformation on the face of the character.

The next step is to go to join the facial rig just created with the character you want to animate. ReveRig offers tools to automatically create drivers to control each of the 52+ ARKit shape keys. This saves you a lot of time and effort.

IMPORTANT: Since Reverig allows you to manage shape keys through drivers these shape keys mustn't be associated with other drivers. Therefore, before proceeding it is recommended to check carefully the presence of possible drivers and if present delete them. A very quick way to check if a shape key is guided by driver is: select the Mesh > Properties > Object Data Properties > Shape Keys. If a driver is present the value field of the shape key will be colored in purple. 

Driver presence is marked in purple 

When we are sure that there are no pre-existing drivers for the 52+ ARKit shape keys it is possible to proceed with the skinning phase.

IMPORTANT: To proceed you must select and have active the facial rig created previously.  It is essential to select the correct facial rig! For this reason renaming each rig based on the character you want to animate is important. When the facial rig is selected the interface shown will be the following:

Five fields to fill are shown (Face, Eyes, Tongue, Upper Teeth, and Lower Teeth). Each of these refers to a particular mesh that could be present in the 3D model of the character’s face. 

The only mesh that is mandatory to insert is the one related to the real Face of the character, which is the main mesh. The other fields are optional and should only be used if the character is subdivided into different geometries. The most common situation is to have one mesh per face (where tongue and teeth are included) and one for the eyes. In this case, you will also need to indicate the mesh related to the Eyes field and so on. To facilitate the selection operation the picker tool is provided.

VIDEO TUTORIAL: A quick video tutorial on how to use ReveRig with characters with only one mesh. Link to the Video.

When you have indicated all the necessary meshes the button Create Shape Keys Drivers will appear. You can now press the button and proceed with creating the necessary drivers.

For each mesh indicated, the result should be as follows. In addition to any additional shape keys, the 52 ARKit blendshape are all marked with purple.

Now the facial rig created with ReveRig is connected via driver to the 52 shape keys of the character related to facial expressions. It then becomes possible to go and check the facial rig to generate the desired facial animation. 

In case you do not want to retarget any animation, you can use the Drivers Manager panel to precisely manage the facial animation you want to create.

To check the correct operation of the facial rig and get familiar with the tool you can select the rig, enter Pose Mode, and try the operation of the various sliders.

What to do if your character has more than 5 meshes or if it has meshes other than those indicated by ReveRig?

You may find yourself in the situation where your character's face is composed of more than 5 meshes or that it is equipped with additional meshes to those indicated by ReveRig (Face, Eyes, Tongue, Upper&Lower Teeth).

VIDEO TUTORIAL: A quick video tutorial on how to use ReveRig with characters made up of different meshes. Link to the Video.

A very common situation is having a character with separate eyelashes mesh.

One solution would be to JOIN the eyelashes to the main face mesh (Ctrl+J ). Joining the secondary meshes to the main one, in addition to solving the problem posed, is also very useful for simplifying the character.

In case you don't want or cannot join secondary meshes to the main one of the face then the procedure to follow is the following:

The main mesh of the face must be entered in the Face field. If there is a separate mesh for the eyes then this must be entered in the Eyes field. ReveRig also provides three other fields (Tongue, Upper Teeth, Lower Teeth). For these three, unlike the Eyes field, the name used serves only as a guideline for the user but it is possible to insert any type of mesh (obviously equipped with the necessary shape keys).

For example, if your character has 2 meshes: face (including eyes) and eyelashes, then what you will need to do is enter the main mesh in the Face field, and the eyelashes mesh in one of the last three fields (i.e Tongue)

.

## More than 5 meshes

A rarer but still possible situation occurs when the character's face is divided into more than 5 meshes, which is more than the fields provided by ReveRig.

In this case, the procedure to follow is the following: 

For each field provided by ReveRig, the corresponding mesh is inserted (Face, Eyes, Tongue, Upper, and Lower Teeth) and proceed with the creation of the drivers by clicking on the button as usual.

After that, repeat the operation for any remaining meshes. The first field to be filled in, because it is mandatory, is the Face field.

NOTE!: This time in the Face field you will no longer have to enter the main Mesh (because it has already been linked to the rig in the previous phase) but one of the remaining ones.

You can then insert additional meshes in the Tongue, Lower and Upper Teeth fields and proceed with the creation of the drivers by clicking on the button as usual. While the Eyes field must be left blank (only the eye mesh should be entered in this field) .

The Rig Interface

A quick guide to start using Reverig’s facial rig.

First of all, sliders can be distinguished by color:

• Red for sliders acting on the right side;
• Blu for sliders acting on the left side;
• The default color for sliders that do not act on a particular side of the face.

After that you can split the interface into 6 main sections:

1. The higher one encloses the sliders to animate the eyebrows
2. Eye sliders are divided into two groups: The first encloses sliders to manage the movement of the eyelids (open, close, left, right...). The second includes sliders to manage the real movement of the eyes and two sliders to control dilation/ compression of the pupils. The movement of eyes and eyelids has been separated to allow the animator to realize more complex facial expressions.
3. Under the eye group, there are sliders to animate the nose and cheeks.
4. The largest group concerns the control of the shape key related to the mouth. In addition to dividing the left and right sides, the sliders are arranged in such a way as to suggest the action they will accomplish. Initially, it might seem complicated to remember the action of each slider but with a little experience, it becomes all more natural.
5. The lower group has controls to manage the movement of the jaw (open, close, left, right, forward).
6. The last group encloses the slider for tongue control (tongueOut), typically poorly used.

TIP! Each slider has a mark that indicates the rest position of each shape keys that is, the point where the value will be zero.

The small circle represents the zero point

Animation Retargeting

The second ReveRig panel contains all the tools you need to retarget the facial animation. Retargeting is an optional operation so you can proceed with facial animation without retargeting and without having to use this panel. Otherwise, Reverig offers you a series of very powerful tools to quickly and easily transfer facial animation from the source to the facial rig of your character.

The interface that is shown is the following:

There are two mandatory fields to fill, the first one relative to the source Mesh from which to copy the animation and the second one relative to the rig to use as a target. The source must be Mesh type and the target must be the facial rig created with ReveRig related to the character you want to animate (Armature type).

Note! The source mesh must contain all 52 ARKit shape keys with the correct nomenclature. If you use applications like bannaflak’s FaceCap the generated fbx object contains a mesh named head which contains all the data needed for facial animation.

Only after selecting the correct source and target will be shown the button with which you can start the retargeting operation. It also shows the offset tool that serves to indicate the from which to start to copy the animation, corresponds to the current frame.

When you are ready you can press the Re-Target Animation button and start the retargeting operation. This is the longest operation planned by ReveRig. The time required to complete the operation depends highly on the number of keyframes that make up the facial animation and the hardware used.

UPDATES: With version 1.10 ReveRig automatically renames FaceCap shape Keys according to ARKit. This operation no longer has to be done manually

The operation can go from a few seconds to a couple of minutes. It is advisable to wait patiently for the operation to be completed before performing other actions.

Known Issue: In some rare cases it may happen that the animation copied on the facial rig has some problems such as the sudden variation of the values of successive keyframes. If you are in this situation simply delete all the animation keyframes just transferred and carry out the retargeting operation again.

If there are no imperfections in the animation then the retargeting operation is successfully concluded. Now you can switch to the Drivers Manager panel and the facial rig to change the newly transferred animation as desired.

Drivers Manager

This is the last ReveRig panel and probably the one that will be used the most because it is within this panel that you find the main tools to precisely manage the entire facial animation.

Drivers Manager is a window-based representation of the facial rig interface, In addition to precise control over rig sliders, it offers the ability to set the amplitude of each shape key. Thanks to this property it is possible to create very expressive animations, typical of stylized products (Pixar Style).

The interface is divided into two main sections:

1. The first section shows the name of the selected facial rig so that the animator is always in control of the situation. It also offers two tools: the first called frame (very similar to the Offset tool seen before) serves to set the current frame practically. The second tool is the Insert Rest Position keyFrame button that serves to insert a keyframe for all the shape keys that brings the character back to the Rest Position. This allows the animator to save a lot of time.

1. The second section includes all the tools to precisely control the animation of all 52+ shape keys. To increase the usability of ReveRig the various commands have been divided according to the main areas of the face (brows, eyelids, eyes and pupil, cheeks&nose, mouth, jaw, tongue). So you can easily find the slider related to the shape key that interests you. The division is as seen in The Rig Interface chapter.

Drivers Manager panel 

Drivers Manager tools and interface. (ex borws). 

For each area of the face a corresponding sub panel has been created, the interface is like the one shown in the picture above.

In general, for each shape key there are three tools: 

• A slider with the same name as the reference shape key (ex browOuterUpRight). The indicated value is the value applied to the shape key in case Amp Value is equal to 1. By default, this value is limited to the range 0-1. Values less than 0 or greater than 1 are not valid. The slider will stick to the same convention used within Blender: No color if no keyframe is present, Yellow if there is a keyframe in the current frame, Green if at least one keyframe is present before the current frame (interpolated value).
• A button marked with a dot. It serves to insert a new keyframe or replace one already present, relative to the value set by the slider of the shape key.

NOTE! It is preferable to insert the necessary keyframes through the appropriate button seen above or manually enter the single keyframe (Insert Single Keyframe command). It is not recommended to insert keyframes with the keyboard shortcut I because they would be created for each slider 3 keyframes (for the three axes of translation: x,y,z) but we only care about one axis (typically y). Inserting unnecessary axis keyframes can complicate any work in the Graph Editor.

• A slider named Amp Value with default value of 1. The value set in the Amp Value will be multiplied with that present in the slider relative to the shepe key, in order to obtain the desired expression. This property has been added to allow you to create more expressive animations and to give space to your creativity.

How Amp Value works.

To improve the facial rig interface some shape keys are controlled by a single slider (eyeLookDown/Up (right and left), eyeLookOut/in (right and left), jawRight/Left). For these shape keys then the interface present in the Drivers Manager panel is slightly different (see figure below).

Two shape keys controlled by one slider. [-1, 1] 

In these cases you have a slider that on a single axis of translation control the two shape keys. Unlike before, the range is no longer [0, 1] but [-1, 1]. Then negative values will activate one shape key and positive values will activate another shape key (typically with opposite action). However each shape key retains the Amp Value property, in fact in these cases you will have two Amp Value sliders.  To guide you in using we have inserted for each slider the name of the shepe key as reference.

Support

I hope the documentation has been helpful, if you have not found an answer to your problems you can check if there is something in the FAQ.

We worked a lot at ReveRig so if you had any question, problem or suggestion please feel free to contact us  here at BlenderMarket under Ask a Question. We will answer as soon as possible. 

If ReveRig was useful to you and you enjoyed using it we invite you to leave a review to help the community. Your feedback is very important to us!

If you want to report a bug or encounter problems with ReveRig, please reach out here at BlenderMarket under Ask a Question.

Bug Reports

• Blender version + ReveRig version
• what is the problem and how can we reproduce it?
• If possible, please share the Blendfile. That makes everything way easier