rig::MultiBoneIK

Positions and orients joints from a root position, goal, and twist position using inverse kinematics.

On this page	Solvers IK Solver IK with Constraints Solver Joint Properties Inputs Outputs
Since	20.0

Positions and orients joints from a root position, goal, and twist position using inverse kinematics.

Solvers ¶

In the input port, solver, you can specify the solver to use for computing the IK solution - the default IK Solver (solver = 0) or the IK with Constraints Solver (solver = 1).

IK Solver ¶

This solver produces a reasonably stable solution. When usetwist is set to true, the solution is aligned with the twist pole vector.

IK with Constraints Solver ¶

This solver allows you to specify per-joint rotation limits, and per-joint damping (which helps to prioritize the rotation of the individual joints). This solver does not use the twist pole vector since it isn’t meaningful in the presence of rotation limits.

You can provide the joint configurations through the dictionary in the properties port, where each dictionary entry configures the properties for a single joint. See the descriptions of the joint properties below. The dictionary has the following format:

{
    "<joint_in_port_name>" : {
        "rotation_upper_limits" : Vector3(M_PI, M_PI, M_PI),
        "rotation_lower_limits" : Vector3(-M_PI, -M_PI, -M_PI),
        "restangle" : Vector3(0, 0, 0),
        "damp" : Float(0.5)
        "dampangle" : Vector3(0, 0, 0),
        "damprolloff" : Vector3(1, 1, 1),
    }
}

The dictionary entry’s key must match the name of the in subport, which provides the joint’s matrix. The example below is a configuration for a joint named “base”:

{
    "base" : {
        "rotation_upper_limits" : Vector3(M_PI, M_PI, M_PI),
        "rotation_lower_limits" : Vector3(-M_PI, -M_PI, -M_PI),
        "restangle" : Vector3(0, 0, 0),
        "damp" : Float(0.5)
        "dampangle" : Vector3(0, 0, 0),
        "damprolloff" : Vector3(1, 1, 1),
    }
}

Alternatively, the dictionary entry’s key can also be the index of an in subport. For example, a key of "0" applies the configuration to the first joint, a key of "1" applies the configuration to the second subport, and so on. The example below is a configuration for the first joint:

{
    "0" : {
        "rotation_upper_limits" : Vector3(M_PI, M_PI, M_PI),
        "rotation_lower_limits" : Vector3(-M_PI, -M_PI, -M_PI),
        "restangle" : Vector3(0, 0, 0),
        "damp" : Float(0.5)
        "dampangle" : Vector3(0, 0, 0),
        "damprolloff" : Vector3(1, 1, 1),
    }
}

The dictionary is sparse, and joints that are not in the dictionary have their default values set to those in the above examples.

Joint Properties ¶

property	Description
rotation_upper_limits	Upper Rotation Limit A set of XYZ angles (in radians with XYZ rotation order) that defines the upper rotation limit. The maximum rotation value is π radians.
rotation_lower_limits	Lower Rotation Limit A set of XYZ angles (in radians with XYZ rotation order) that defines the lower rotation limit. The minimum rotation value is -π radians.
restangle	Rest Angle This adds a pre-rotation to the rest orientation of the joint (in radians with XYZ rotation order). The rotation limits are applied with respect to the rest orientation.
damp	Joint Damping This is a multiplier that adjusts the damping applied to the joint. A value of zero represents complete damping, while a value of 1 represents no damping. A highly damped joint may have less motion than a joint that is able to move freely.
dampangle	Damp Angle A set of XYZ angle offsets (in radians with XYZ rotation order), from the upper and lower rotation limits, at which to apply additional damping. For example, if the X upper rotation limit is 60 degrees and the X damp angle is 20 degrees, the additional damping is applied to the solution after the X angle reaches 40 degrees. This is an additional damping that is applied after the initial joint damping has taken effect.
damprolloff	Damp Angle Rolloff This is a multiplier that adjusts the additional damping to apply once the damp angle has been reached. A value of zero represents complete damping, while a value of 1 represents no damping.

Inputs ¶


                in:
                    VariadicArg<Matrix4>

The world space transforms of all the input joints.


                rootdriver:
                    Matrix4

The world space transform to place the root joint of the output.


                twist:
                    Matrix4

The pole vector for the solver. This is only used when solver is set to 0 (default solver) and usetwist is set to True.


                goal:
                    Matrix4

The world space goal transform for the IK solve.


                stretch:
                    Float

The stretch factor. A value of 1 stretches the input joint lengths evenly to reach the goal before running the solver. A value of 0 keeps the input lengths as is. A value between 0 and 1 linearly interpolates the stretch factor.


                squash:
                    Float

The squash factor, which controls the scaling on the 2 axes orthogonal to the joints when stretching. A value of 0 leaves the scaling intact, a value of 1 compresses the scaling when stretching, and a negative value increases the scaling when stretching. A value between 0 and 1 is recommended.


                blend:
                    Float

Controls how much of the result to blend with the input transforms.


                dampen:
                    Float

Slows the convergence to the IK solution. A value of 0 represent no damping, while a value of 1 represents maximum damping. This is only used when solver is set to 0 (default solver). The IK with Constraints Solver (solver = 1) uses per-joint damping.


                trackingthreshold:
                    Float

The accuracy threshold. Use smaller values for more accurate solutions at the expense of more computation time. Use larger values to save computation time at the expense of getting less accurate solutions. This is only used when solver is set to 0 (default solver).


                twistoffset:
                    Float

An additional twist rotation, in degrees, to apply post-solve.


                usetwist:
                    Bool

If set to True, applies a twist using the twist matrix.


                resiststraight:
                    Bool

If set to False, the IK chain completely straightens out in the direction of the goal if the IK goal is farther away than the length of the joint chain (with a tolerance of the trackingthreshold). If set to True, no attempt is made to further straighten the IK solution. By default, resiststraight is set to True because it improves the speed of the solve. This is only used when solver is set to 0 (default solver).


                keeproot:
                    Bool

If set to True, keeps the original transform from the rootdriver. If set to False, uses the root returned by the IK solver.


                keepscales:
                    Bool

If set to True, the output joints keep the same scaling as the input joints. If set to False, the output joints have unit scaling.


                usegoalrot:
                    Bool

If set to True, the last output joint has the same rotation as the goal. If set to False, the last output joint has the same local rotation as the last input joint.


                solver:
                    Int

The solver used to compute the IK solutions. 0 is the default IK Solver and 1 is the IK with Constraints Solver. See solvers for more information.


                properties:
                    Dict

When solver is set to 1 (IK with Constraints Solver), this dictionary holds per-joint IK configuration values.

Outputs ¶


                out:
                    VariadicArg<Matrix4>

The world space transforms of all the output joints.