RigState Class Reference

The RigState JavaScript class. Represents the state of a rig for a given pose. More...

Public Slots

NodeState getNodeState (int index)
 Get a copy of the NodeState contained in the current RigState object at the specified index. More...
 
RigState interpolate (float a, RigState b)
 Create a new RigState, by linearly interpolating the current one with the other one given in argument. More...
 
RigState interpolate2d (float u, float v, RigState b, RigState c, RigState d)
 Create a new RigState, by performing a bilinear interpolation of the current one with the 3 other ones given in argument. More...
 
int nodeCount ()
 Get the node count contained in this RigState. More...
 
void addNodeAttrList (String &sNodePath, QScriptValue sAttrArray, int frameNo)
 Add node attributes to the current RigState snapshot. More...
 
void applyState (int frameNo)
 Apply the values of the current snapshot to the scene, at the specified frame. More...
 
String toString (String &sRelativePath)
 Generate a string representation of the current RigState data. More...
 
int loadFromString (String &sData, int nPos, String &sRelativePath)
 Restore a RigState from a previously generated RigState string representation. More...
 

Public Member Functions

 RigState (String stateName, int frameNo, String nodeQualifiedName)
 Create a new RigState. More...
 
 ~RigState ()
 

Properties

String stateName
 The given name of the current RigState snapshot. More...
 
int frameNo
 The source frame number associated to the current RigState snapshot, at creation. Note : interpolated states have no source frame number. More...
 

Detailed Description

The RigState JavaScript class. Represents the state of a rig for a given pose.

A RigState is a snapshot of a part of the node network. It can store all attributes values associated to a rig state, such as position, color, effects parameters, scale, deformation, drawings, etc. These snapshots, or RigStates, can be stored, blended, and applied to a rig. It aims at making it easier to manipulate rig data by offering a simple, high-level interface to represent the state of a rig. Internally, a RigState object contains a list of nodes and attributes with their values for a given pose.

//Create a snapshot of "head_neck" group nodes at frame 15
var angryPose = new RigState("Angry", 15, "Top/CH001_Beaver/head_neck");
//Create a snapshot of "head_neck" group nodes at frame 11
var happyPose = new RigState("Happy", 11, "Top/CH001_Beaver/head_neck");
//Generate a new pose by blending the 2 poses above,
//using .25 weight factor (25% happy, 75% angry)
var blendedPose = angryPose.interpolate(0.25, happyPose);
scene.beginUndoRedoAccum("Pose API test");
//Apply the blended pose changes on the rig, at the current frame.
blendedPose.applyState(frame.current());

Constructor & Destructor Documentation

◆ RigState()

RigState::RigState ( String  stateName,
int  frameNo,
String  nodeQualifiedName 
)

Create a new RigState.

The example below transfers a head pose from frame 15 to frame 20.

var angryHeadPose = new RigState("Angry", 15, "Top/CH001_Beaver/head_neck");
angryHeadPose.applyState(20);
Parameters
stateName: The identifier given to this new state
frameNo: The frame index used to create the state snapshot
nodeQualifiedName: The qualified name of the root group under which all sub-node attribute values will be captured in the snapshot.
Returns
Returns a new RigState, containing a snapshot of the given group node properties.

◆ ~RigState()

RigState::~RigState ( )

Member Function Documentation

◆ addNodeAttrList

void RigState::addNodeAttrList ( String &  sNodePath,
QScriptValue  sAttrArray,
int  frameNo 
)
slot

Add node attributes to the current RigState snapshot.

This example creates an empty RigState and then adds the POSITION attribute for the Master-P node.

var masterPegState = new RigState("Master-Peg", 15);
masterPegState.addNodeAttrList("Top/CH001_Beaver/master-P", ["POSITION"], 15);
Parameters
sNodePath: The node qualified name to add.
sAttrArray: An array of attribute names to add.
frameNo: The frame number to use while fetching attribute values.

◆ applyState

void RigState::applyState ( int  frameNo)
slot

Apply the values of the current snapshot to the scene, at the specified frame.

The example below transfers the properties of all nodes under the group "Top/CH001_Beaver/head_neck" from frame 15 to frame 20.

var headPose = new RigState("myHeadPose", 15, "Top/CH001_Beaver/head_neck");
headPose.applyState(20);
Parameters
frameNo: The destination frame number, where the RigState snapshot values are applied.

◆ getNodeState

NodeState RigState::getNodeState ( int  index)
slot

Get a copy of the NodeState contained in the current RigState object at the specified index.

This example iterates all node states.

var headState = new RigState("headState", 15, "Top/CH001_Beaver/head_neck");
for(var i=0; i < headState.nodeCount(); ++i)
{
var nodeStateCopy = headState.getNodeState(i);
MessageLog.trace("Node State ["+i+"]: " + nodeStateCopy.sNodePath);
}
Parameters
index: The index of the node state to retrieve. Must be within [0-nodeCount[.
Returns
A Copy of the NodeState contained within this RigState at the specified index.

◆ interpolate

RigState RigState::interpolate ( float  a,
RigState  b 
)
slot

Create a new RigState, by linearly interpolating the current one with the other one given in argument.

The example below interpolates poseA with poseB, giving a weight of 75% to pose A and 25% to poseB.

var poseA = new RigState("A", 15, "Top/CH001_Beaver/head_neck");
var poseB = new RigState("B", 16, "Top/CH001_Beaver/head_neck");
var interpolatedPose = poseA.interpolate(0.25, poseB);
Parameters
a: The normalized weight given to pose b.
b: The pose to interpolate the current one with
Returns
A new interpolated RigState

◆ interpolate2d

RigState RigState::interpolate2d ( float  u,
float  v,
RigState  b,
RigState  c,
RigState  d 
)
slot

Create a new RigState, by performing a bilinear interpolation of the current one with the 3 other ones given in argument.

The example below illustrates the long and short way to perform a bilinear interpolation.

var u = 0.3;
var v = 0.8;
var poseA = new RigState("A", 15, "Top/CH001_Beaver/head_neck");
var poseB = new RigState("B", 16, "Top/CH001_Beaver/head_neck");
var poseC = new RigState("C", 17, "Top/CH001_Beaver/head_neck");
var poseD = new RigState("D", 18, "Top/CH001_Beaver/head_neck");
//Long version
var interpolatedPoseAB = poseA.interpolate(u, poseB);
var interpolatedPoseCD = poseC.interpolate(u, poseD);
var interpolatedPoseABCD_long = interpolatedPoseAB.interpolate(v, interpolatedPoseCD);
//Shorter version
var interpolatedPoseABCD_quick = poseA.interpolate2d(u,v,poseB,poseC,poseD);
interpolatedPoseABCD_quick.applyState(frame.current());
Parameters
u: First axis interpolation weight
v: Second axis interpolation weight
b: The second pose of the bilinear interpolation
c: The third pose of the bilinear interpolation
d: The fourth pose of the bilinear interpolation
Returns
A new bilinearly interpolated RigState

◆ loadFromString

int RigState::loadFromString ( String &  sData,
int  nPos,
String &  sRelativePath 
)
slot

Restore a RigState from a previously generated RigState string representation.

This example loads a string representation from a saved file and restores the original RigState.

var file = new File(scene.currentProjectPath()+"/scripts/test.txt");
file.open(1); //1=FileAccess.ReadOnly Flag
var dataString = file.read();
file.close();
var restoredState = new RigState(); //Create a new empty state
restoredState.loadFromString(dataString,0,"Top/CH001_Beaver");
Parameters
sData: The string containing the pose data.
nPos: The start index in the string
sRelativePath: The qualified name of the root character group (optional). When provided, this argument makes it possible to adjust data generated from a character group that was renamed.
Returns
the index of the last character read in the data string

◆ nodeCount

int RigState::nodeCount ( )
slot

Get the node count contained in this RigState.

This example creates a RigState from a given group node qualified path and returns the number of nodes included in the pose snapshot.

var headState = new RigState("Head Snapshot", 15, "Top/CH001_Beaver/head_neck");
var nCount = headState.nodeCount();
MessageLog.trace("This RigState contains information about "+nCount+" nodes.");
Returns
The number of nodes contained in this RigState.

◆ toString

String RigState::toString ( String &  sRelativePath)
slot

Generate a string representation of the current RigState data.

This example creates a new state, generates the string representation and saves the data to a file.

var angryPose = new RigState("AngryState", 15, "Top/CH001_Beaver/head_neck");
var dataString = angryPose.toString("Top/CH001_Beaver");
var file = new File(scene.currentProjectPath()+"/scripts/test.txt");
file.open(2); //2=Write File Access Flag
file.write(dataString);
file.close();
Parameters
sRelativePath(optional) : The qualified name of the root character group (optional). When provided, node paths are stored relative to this group, making it possible to rename or move the character group node without invalidating the data.
Returns
A string containing the pose data.

Property Documentation

◆ frameNo

int RigState::frameNo
readwrite

The source frame number associated to the current RigState snapshot, at creation. Note : interpolated states have no source frame number.

◆ stateName

String RigState::stateName
readwrite

The given name of the current RigState snapshot.