rig::MultiBoneIK

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

On this page	Solvers Joint Configuration Joint Properties Inputs Outputs
Since	20.0

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

Solvers ¶

solver	Solver
0	IK Solver This solver produces a reasonably stable solution. When usetwist is set to true, the solution is aligned with the twist pole vector.
1	IK with Constraints Solver This solver is capable of using 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. The joint configuration must be provided to the node through the properties port. Each dictionary entry provides the configuration for a single joint.

solver

Solver

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 is capable of using 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. The joint configuration must be provided to the node through the properties port. Each dictionary entry provides the configuration for a single joint.

Joint Configuration ¶

The IK with Constraints solver is configured by the properties port using a Dict with 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),
    }
}

Each dictionary entry configures the properties of a single joint. The entry’s key must match the name of the in subport which provides the joint’s matrix. Alternatively, a key with the index of an in subport also applies the configuration to the joint. For example, a key of "0" applies the configuration to the first joint, and a key of "1" applies the configuration to the second subport, and so on. The dictionary is sparse, and joints which are not represented in the dictionary have default values equivalent to above dictionary.

Joint Properties ¶

property	Property
rotation_upper_limits	Upper Rotation Limit A set of XYZ angles (in radians with XYZ rotation order) defining 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) defining 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 which adjusts the damping applied to the joint. A value of zero represents complete damping, while a value of 1 represents no damping. Damping may help to adjust the priority that a joint takes when finding a solution. 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 equivalent to 60 degrees, and the X damp angle is equivalent to 20 degrees, then the additional damping will be applied to the solution after the X angle reaches 40 degrees. This is an additional damping applied after the initial joint damping has taken effect.
damprolloff	Damp Angle Rolloff This is the multiplier which 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 by the default IK solver. It is enabled if 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 bone 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 bones 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 by the default solver (the IK with Constraints solver uses per-bone 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 by the 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 bone 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 by the 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

Sets the solver used to compute the IK solutions. 0 is the default IK solver. 1 is the IK with Constraints solver.


                properties:
                    Dict

When the IK with Constraints solver is active, this dictionary holds per-joint IK configuration values.

Outputs ¶


                out:
                    VariadicArg<Matrix4>

The world space transforms of all the output joints.

Solvers ¶

Joint Configuration ¶

Joint Properties ¶

Inputs ¶

Outputs ¶

APEX nodes