## MakeArm

### Introduced

v4.0

### Description

Creates a two bone arm and an up vector control object. The arm bones are created from a collection of guide objects, which should contain objects for shoulder, elbow, and hand positions respectively. A bicep bone will connect the shoulder and elbow objects, and a forearm bone will connect the elbow and hand objects.
MakeArm can optionally add roll divisions to the bicep and forearm. Divisions are used to distribute the roll difference between adjacent bones over 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. Roll divisions can also be added separately using the MakeBicepRoll and MakeForearmRoll commands. If using forearm roll, create the hand before calling MakeArm so that the hand root can be passed as an argument.
Optionally a shadow rig can be attached to the arm. Shadow objects will be created for each chain element in the arm, and shadow arm bones will be pose constrained to the acutal arm bones. Shadow rigs can be used to plot animation off of a rig.

### Scripting Syntax

    oArm = MakeArm( ArmParent, GuideObjectCollection, [Prefix], [ArmRootConstrainingObj], [NbForearmDivisions], [NbBicepDivisions], [ShadowType], [ShadowParent], [HandRoot], [NegativeScale] );

### Return Value

Returns an Arm JScript.

### Parameters

Parameter | Type | Description
--- | --- | ---
ArmParent | String | The object to which the new arm will be parented.
GuideObjectCollection | String | A collection of three guide objects for the shoulder, elbow, and hand respectively.
Prefix | String | The prefix used to name new objects when making the new arm. Example "L", "R"
ArmRootConstrainingObj | String | Object to which the arm root will be position-constrained. If not specified, no constraint is applied to the arm root.
NbForearmDivisions | Integer | The number of forearm roll divisions (see the MakeForearmRoll command). If the value is zero there is no forearm roll Default Value: 0
NbBicepDivisions | Integer | The number of bicep roll divisions (see the MakeBicepRoll command). If the value is zero there is no bicep roll. Default Value: 0
ShadowType | Integer | The type of shadow rig to attach to the arm. Shadow rigs can be used to transfer or remap animation. Default Value: 0
Possible Values: | Description:
0 | No shadow
1 | SI|3D Skeleton shadow rig
2 | XSI Skeleton shadow rig
3 | Null shadow rig
4 | Box shadow rig
ShadowParent | String | Parent of the shadow rig hiearchy. If empty, no shadow rig is generated.
HandRoot | String | Object acting as hand root, required for forearm roll division. This object must be a chain element(root,bone,effector). If empty, forearm roll division will not be applied, but bicep roll will.
NegativeScale | Boolean | Negative scaling on the chain. Negative scaling is useful for manipulating the left and right arms symmetrically. Default Value: False

### Examples

#### JScript Example

    /*
            This script creates two arms, left and right
            Left arm also has a hand bone and roll divisions.
    */
    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(GetPrim("Null", "RArmParent"), guidecoll, "R",null, 0,0,0,null ,null, 0);
    Logmessage("Right RArm");
    DumpArm(RArm);
    /*
            Left 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 lPosStart = XSIMath.CreateVector3();
    var lPosEnd = XSIMath.CreateVector3();
    lPosStart.Set(-8,0,0);
    lPosEnd.Set(-9,0,0);
    var HandChain = ActiveSceneRoot.Add2DChain(lPosStart, lPosEnd);
    var LArm = MakeArm(GetPrim("Null", "LArmParent"), guidecoll, "L",null, 4,4,0,ActiveSceneRoot,HandChain, 0);
    Logmessage("Left Arm");
    DumpArm(LArm);
    function DumpArm(inArm)
    {
            logmessage ("Data in the returned arm object:");
            logmessage ("-------------------------------");
            logmessage ("Bind Null : " + inArm.Root);
            logmessage ("Top  Null : " + inArm.Eff);
            logmessage ("Base Null : " + inArm.UpVParent);
            logmessage ("#ForeDiv  : " + inArm.ForearmDivisions);
            if(inArm.BicepDivisions > 0)
            {
                    for(var b=0;b<inArm.ForeArmRoll.Divisions.count;b++)
                    {logmessage ("  RollDif" + b + ": " + inArm.ForeArmRoll.Divisions(b));}
            }
            logmessage ("#BicepDiv : " + inArm.BicepDivisions);
            if(inArm.BicepDivisions > 0)
            {
                    for(var b=0;b<inArm.BicepRoll.Divisions.count;b++)
                    {logmessage ("  RollDif" + b + ": " + inArm.BicepRoll.Divisions(b));}
            }
            logmessage ("Upvector  : " + inArm.UpV);
            logmessage ("Hidden    : " + inArm.Hidden);
            logmessage ("Envelope  : " + inArm.Envelope);
            logmessage ("Shadows   : " + inArm.Shadows);
    }
    //results of running this script
    //INFO : "Right RArm"
    //INFO : "Data in the returned arm object:"
    //INFO : "-------------------------------"
    //INFO : "Bind Null : RRoot"
    //INFO : "Top  Null : RArmEff"
    //INFO : "Base Null : undefined"
    //INFO : "#ForeDiv  : 0"
    //INFO : "#BicepDiv : 0"
    //INFO : "Upvector  : RArmUpV"
    //INFO : "Hidden    : RRoot"
    //INFO : "Envelope  : RBicep,RForearm"
    //INFO : "Shadows   : undefined"
    //INFO : "Left Arm"
    //INFO : "Data in the returned arm object:"
    //INFO : "-------------------------------"
    //INFO : "Bind Null : LRoot"
    //INFO : "Top  Null : LArmEff"
    //INFO : "Base Null : undefined"
    //INFO : "#ForeDiv  : 4"
    //INFO : "  RollDif0: LElbow"
    //INFO : "  RollDif1: LForearmRoll"
    //INFO : "  RollDif2: LForearmRoll1"
    //INFO : "  RollDif3: LForearmRoll2"
    //INFO : "#BicepDiv : 4"
    //INFO : "  RollDif0: LBicepRoll1"
    //INFO : "  RollDif1: LBicepRoll2"
    //INFO : "  RollDif2: LBicepRoll3"
    //INFO : "  RollDif3: LBicepRoll4"
    //INFO : "  RollDif4: LBicepRoll_5"
    //INFO : "Upvector  : LArmUpV"
    //INFO : "Hidden    : LRoot"
    //INFO : "Envelope  : LBicepRoll1,LBicepRoll2,LBicepRoll3,LBicepRoll4,LBicepRoll_5,LElbow,LForearmRoll,LForearmRoll1,LForearmRoll2"
    //INFO : "Shadows   : undefined"
    //

### See Also

MakeForearmRoll MakeBicepRoll MakeHand MakeJointCompression