FaceFX Support

FaceFX Documentation and support

FaceFX Commands - bonepose

The bonepose command is used to create multi-stage bone poses, transfer bone poses between characters, export the rest pose from the Ogre bind pose, and perform simple add/subtract operations on existing bone poses.

Command Syntax

Flag LongFlag Arg Description
-cm -constructmega Yes The name of a the mega bone pose to construct.
-mci ‑megaconstructioninfo Yes A pipe character (“|”) separated string with the following format: value1|name1|value2|name2|value3|name3… where value3 > value2 > value1.  Used in conjunction with the -cm flag.
-dm -deconstructmega Yes The name of the mega bone pose to deconstruct.
-tr -transfer No Specifies that the command should run in transfer mode.  Must specify -src and -dst flags.
-src -source Yes Path to source actor.  All bone poses will be copied from this actor.
-dst -destination Yes Path to destination actor.  All bone poses from the source actor will be created in destination actor, overwriting existing bone poses if necessary.
-rp -restpose No Use instead of the -name flag to specify that the operation should be performed on the rest pose.
-rcf -replacewithcurrentframe No Replaces the specified bone pose or rest pose with the contents of the current frame.  If the -restpose flag is used, all Ogre skeleton bones will be added to the reference pose.  Then you can prune unwanted bones with -remove flag.  Requires a rendersystem is initialized.
-add -add Yes Puts the command in add mode.  Use the -lhs and -rhs flags.  Takes the new bone pose name as input.
-sub -subtract Yes Puts the command in subtract mode.  Use the -lhs and -rhs flags.  Takes the new bone pose name as input.
-lhs -lhs Yes Specifies the bone pose to use on the left hand side of the add or subtract operation.
-rhs -rhs Yes Specifies the bone pose to use on the right hand side of the add or subtract operation.
-ab -addbone Yes Adds a bone to a bone pose.  Use with the -name flag.  Takes an array with 11 pipe-character ( | ) separated Arguments as input:  bonename|pos.x|pos.y|pos.z|rot.w|rot.x|rot.y|rot.z|scale.x|scale.y|scale.z
-rb -removebones Yes Removes bone(s) from a bone pose.  Used with the -name flag .  Takes a pipe-character ( | ) separated string array of bone names.  Pass in “all” to remove all bones.
-n -name Yes Specifies the bone pose node to operate on for the addbone and removebone flags.


%bonepose -cm "TH" -mci ".85|step1|1.0|step2";

%bonepose -dm "TH";

%bonepose -transfer -src "C:\male.facefx" -dst "C:\female.facefx";

%bonepose -restpose -replacewithcurrentframe;

%bonepose -restpose -removebones "bone1|bone2|bone3|bone4";

%bonepose -add "sum_of_A_and_B" -lhs "A_bonepose" -rhs "B_bonepose";

%bonepose -subtract "A_with_B_removed" -lhs "A_bonepose" -rhs "B_bonepose";

%bonepose -removebones "BN_Head" -name "Blink";

%bonepose -addbone "BN_Head|0|0|0|1|0|0|0|1|1|1" -name "Blink";

Using an Ogre Animation to Define a Character (Blender Support)

Using the bonepose command and the getSkeletonFrame python function, it is possible to completely define a a character’s rest pose and bone poses with nothing but an Ogre asset with a skeleton animation that defines the bone poses.  This allows FaceFX to work with animation packages like Blender that have Ogre exporters, but not native FaceFX Exporters. 

Transferring bone poses

Let’s say you have a male and a female character that share the same facial bone rig.  The male has a larger face, and the bones in the rest pose are further apart than the female character’s bones.  The male character has a rest pose and all bone poses, but the female character has only the rest pose. The bonepose command lets you transfer bone poses from the male to the female character (or visa versa).  The rest pose is subtracted from the bone poses first, so only the changes from the rest pose are taken into account for the transfer.  You may still need to tweak the created bone poses, but at least there is a good starting point to work from.

%bonepose -transfer -src "C:\male.facefx" -dst "C:\female.facefx" ;

Multi-stage bone poses

Let’s say for example that you are trying to fix a problem like below:

When your character says the TH sound, the tongue needs to curl around the teeth, but when the TH target is driven to 85%, the tongue is going through the teeth.  The bonepose command lets you create a node that traverses through two stages: one that gets the tongue sticking out below and beyond the teeth (we’ll call it step1), and a second bone pose that curls the tongue around the teeth (we’ll call it step2).  When TH is at 85% you want the character to look like step1, then when TH goes to 100% it should looks like step2. Doing this with the bonepose comand would look like this:

%bonepose -constructmega "TH" -megaconstructioninfo ".85|step1|1.0|step2";

Doing so will create 2 new bone poses called TH_step1 and TH_step2, and a new combiner node called TH.  The TH combiner node will have the expected behavior. Some things to note:

Exporting the Rest Pose

Exporting the rest pose from the Ogre bind pose was exposed so that Ogre content and audio files are the only required input for creating talking character movies from FaceFX Studio.  The ogre content is loaded, the rest pose is exported, bone poses are transferred, the audio is analyzed, and the movie is rendered!