Scripting: MakeForearmRoll

MakeForearmRoll

Introduced

v4.0

Description

Creates roll nulls along the length of a bone. When used as deformers on an envelope they evenly distribute twist along the length of a bone giving a more natural skin deformation.

The start and end rotations are determined differently for a forearm roll and bicep roll (MakeBicepRoll). In forearm roll, the starting rotation is the forearm's rotation minus any spin, calculated using the bicep's rotation. The end rotation is the next bone's rotation (wrist) with spin. Roll division rotations are then interpolated between the start and end. In the case of bicep roll the bicep bone is used for both start and end rotations. The start rotation is the bone's rotation minus spin, the end rotation is its rotation with spin.

Scripting Syntax

oForeArmRoll = MakeForearmRoll( Bicep, Forearm, ArmEff, HandEff, HandBone, [Prefix], [NbDivisions], [RollOffset] );

Return Value

Returns a ForeArmRoll JScript object.

Parameters

Parameter	Type	Description
Bicep	String	The chain element before the forearm, used to calculate the unspun forearm rotation.
Forearm	String	The object to which the roll nulls will be parented.
ArmEff	String	Effector of the chain that contains the bicep and forearm.
HandEff	String	The effector of the wrist chain.
HandBone	String	The wrist or hand bone, used to calculate the end rotation.
Prefix	String	Prefix added to the name of the new dividers.
NbDivisions	Integer	The number of roll divisions. If the value is zero no roll is created. Default Value: 3
RollOffset	Double	Offset in degrees to roll the forearm. The roll has a range of -180 to 180 and this lets you place the seam of that roll. The value is driving a custom parameter that will be placed under the Hand Bone to interactively control this value. Default Value: 0

Examples

JScript Example

/*
        This script creates an arm, then puts roll division
        on the forearm.
*/
var guidecoll = new ActiveXObject("XSI.Collection");
guidecoll.Add( GetPrim("Null", "ShoulderGuide") ); 
guidecoll.Add( GetPrim("Null", "ElbowGuide") ); 
guidecoll.Add( GetPrim("Null", "HandGuide") ); 
var lXfm = guidecoll(0).Kinematics.Global.Transform
var lPos = XSIMath.CreateVector3();
/*
        Right Arm
*/
lXfm.SetTranslationFromValues(0,0,0);
guidecoll(0).Kinematics.Global.Transform = lXfm;
lXfm.SetTranslationFromValues(4,0,-2);
guidecoll(1).Kinematics.Global.Transform = lXfm;
lXfm.SetTranslationFromValues(8,0,0);
guidecoll(2).Kinematics.Global.Transform = lXfm;
var RArm = MakeArm(ActiveSceneRoot, guidecoll, "R",null, 0,0,0,null ,null, 0);
/*
        Add a Hand
*/
var lPosStart = XSIMath.CreateVector3();
var lPosEnd = XSIMath.CreateVector3();
lPosStart.Set(8,0,0);
lPosEnd.Set(9,0,0);
var HandChain = ActiveSceneRoot.Add2DChain(lPosStart, lPosEnd);
var ForeArmRoll = MakeForearmRoll(      RArm.Root.Bones(0),     //bicep
                                        RArm.Root.Bones(1),     //forearm
                                        RArm.Eff,               //arm effector
                                        HandChain.Effector,     //hand effector
                                        HandChain.Bones(0),     //hand
                                        "R");                   //new object name prefix
DumpForearmRoll(ForeArmRoll );
function DumpForearmRoll(inForeArmRoll )
{
        logmessage ("Data in the returned arm object:");
        logmessage ("-------------------------------");
        logmessage ("Sliders   : " + inForeArmRoll.Sliders);
        logmessage ("RollOffset: " + inForeArmRoll.RollOffset.value);
        logmessage ("#Divisions: " + inForeArmRoll.Nb);
        for(var b=0;b<ForeArmRoll.Divisions.count;b++)
                {logmessage ("  RollDif" + b + ": " + inForeArmRoll.Divisions(b));}
}
//results of running this script:
//INFO : "Data in the returned arm object:"
//INFO : "-------------------------------"
//INFO : "Sliders   : bone.Roll_Compensation"
//INFO : "RollOffset: 0"
//INFO : "#Divisions: 3"
//INFO : "  RollDif0: RElbow"
//INFO : "  RollDif1: RForearmRoll"
//INFO : "  RollDif2: RForearmRoll1"
//