Go to: Synopsis. Return value. Related. Flags. Python examples.


ikHandle( object , [autoPriority=boolean], [connectEffector=boolean], [createCurve=boolean], [createRootAxis=boolean], [curve=name], [disableHandles=boolean], [enableHandles=boolean], [endEffector=string], [exists=string], [forceSolver=boolean], [freezeJoints=boolean], [jointList=boolean], [name=string], [numSpans=int], [parentCurve=boolean], [positionWeight=float], [priority=int], [rootOnCurve=boolean], [rootTwistMode=boolean], [setupForRPsolver=boolean], [simplifyCurve=boolean], [snapCurve=boolean], [snapHandleFlagToggle=boolean], [snapHandleToEffector=boolean], [solver=string], [startJoint=string], [sticky=string], [twistType=string], [weight=float])

Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.

ikHandle is undoable, queryable, and editable.

The handle command is used to create, edit, and query a handle within Maya. The standard edit (-e) and query (-q) flags are used for edit and query functions.

If there are 2 joints selected and neither -startJoint nor -endEffector flags are not specified, then the handle will be created from the selected joints.

If a single joint is selected and neither -startJoint nor -endEffector flags are specified, then the handle will be created with the selected joint as the end-effector and the start joint will be the top of the joint chain containing the end effector.

The default values of the flags are:

These attributes can be specified in creation mode, edited in edit mode (-e) or queried in query mode (-q).

Return value


In query mode, return type is based on queried flag.


connectJoint, ikHandleDisplayScale, ikSolver, ikSystem, ikSystemInfo, insertJoint, joint, jointCluster, jointDisplayScale, jointLattice, mirrorJoint, removeJoint


autoPriority, connectEffector, createCurve, createRootAxis, curve, disableHandles, enableHandles, endEffector, exists, forceSolver, freezeJoints, jointList, name, numSpans, parentCurve, positionWeight, priority, rootOnCurve, rootTwistMode, setupForRPsolver, simplifyCurve, snapCurve, snapHandleFlagToggle, snapHandleToEffector, solver, startJoint, sticky, twistType, weight
Long name (short name) Argument types Properties
name(n) string createqueryedit
Specifies the name of the handle.
startJoint(sj) string createqueryedit
Specifies the start joint of the handle's joint chain.
endEffector(ee) string createqueryedit
Specifies the end-effector of the handle's joint chain. The end effector may be specified with a joint or an end-effector. If a joint is specified, an end-effector will be created at the same position as the joint and this new end-effector will be used as the end-effector.
priority(p) int createqueryedit
Sets the priority of the handle. Logically, all handles with a lower number priority are solved before any handles with a higher numbered priority. (All handles of priority 1 are solved before any handles of priority 2 and so on.) Handle priorities must be ] 0.
autoPriority(ap) boolean edit
Specifies that this handle's priority is assigned automatically. The assigned priority will be based on the hierarchy distance from the root of the skeletal chain to the start joint of the handle.
weight(w) float createqueryedit
Specifies the handles weight in error calculations. The weight only applies when handle goals are in conflict and cannot be solved simultaneously. When this happens, a solution is computed that weights the "distance" from each goal to the solution by the handle's weight and attempts to minimize this value. The weight must be ]= 0.
positionWeight(pw) float createqueryedit
Specifies the position/orientation weight of a handle. This is used to compute the "distance" between the goal position and the end-effector position. A positionWeight of 1.0 computes the distance as the distance between positions only and ignores the orientations. A positionWeight of 0.0 computes the distance as the distance between the orientations only and ignores the positions. A positionWeight of 0.5 attempts to weight the distances equally but cannot actually compute this due to unit differences. Because there is no way to add linear units and angular units.
solver(sol) string createqueryedit
Specifies the solver. The complete list of available solvers may not be known until run-time because some of the solvers may be implemented as plug-ins. Currently the only valid solver are ikRPsolver, ikSCsolver and ikSplineSolver.
forceSolver(fs) boolean createqueryedit
Forces the solver to be used everytime. It could also be known as animSticky. So, after you set the first key the handle is sticky.
snapHandleFlagToggle(shf) boolean createqueryedit
Specifies that the handle position should be snapped to the end-effector position if the end-effector is moved by the user. Setting this flag on allows you to use forward kinematics to pose or adjust your skeleton and then to animate it with inverse kinematics.
snapHandleToEffector(see) boolean edit
All handles are immediately moved so that the handle position and orientation matches the end-effector position and orientation.
sticky(s) string createqueryedit
Specifies that this handle is "sticky". Valid values are "off", "sticky", "superSticky". Sticky handles are solved when the skeleton is being manipulated interactively. If a character has sticky feet, the solver will attempt to keep them in the same position as the user moves the character's root. If they were not sticky, they would move along with the root.
connectEffector(ce) boolean createedit
This option is set to true as default, meaning that end-effector translate is connected with the endJoint translate.
jointList(jl) boolean edit
Returns the list of joints that the handle is manipulating.
exists(ex) string edit
Indicates if the specified handle exists or not.
setupForRPsolver(srp) boolean edit
If the flag is set and ikSolver is ikRPsolver, call RPRotateSetup for the new ikHandle. It is for ikRPsolver only.
enableHandles(eh) boolean edit
set given handles to full ik (ikBlend attribute = 1.0)
disableHandles(dh) boolean edit
set given handles to full fk (ikBlend attribute = 0.0)
curve(c) name createqueryedit
Specifies the curve to be used by the ikSplineHandle. Joints will be moved to align with this curve. This flag is mandatory if you use the -freezeJoints option.
createCurve(ccv) boolean create
Specifies if a curve should automatically be created for the ikSplineHandle.
freezeJoints(fj) boolean createedit
Forces the curve, specfied by -curve option, to align itself along the existing joint chain. When false, or unspecified, the joints will be moved to positions along the specified curve.
simplifyCurve(scv) boolean create
Specifies if the ikSplineHandle curve should be simplified.
rootOnCurve(roc) boolean createqueryedit
Specifies if the root is locked onto the curve of the ikSplineHandle.
twistType(tws) string createqueryedit
Specifies the type of interpolation to be used by the ikSplineHandle. The interpolation options are "linear", "easeIn", "easeOut", and "easeInOut".
createRootAxis(cra) boolean create
Specifies if a root transform should automatically be created above the joints affected by the ikSplineHandle. This option is used to prevent the root flipping singularity on a motion path.
parentCurve(pcv) boolean create
Specifies if the curve should automatically be parented to the parent of the first joint affected by the ikSplineHandle.
snapCurve(snc) boolean create
Specifies if the curve should automatically snap to the first joint affected by the ikSplineHandle.
numSpans(ns) int create
Specifies the number of spans in the automatically generated curve of the ikSplineHandle.
rootTwistMode(rtm) boolean createqueryedit
Specifies whether the start joint is allowed to twist or not. If not, then the required twist is distributed over the remaining joints. This applies to all the twist types.

Flag can appear in Create mode of command Flag can appear in Edit mode of command
Flag can appear in Query mode of command Flag can have multiple arguments, passed either as a tuple or a list.

Python examples

import maya.cmds as cmds

# Will create a handle from Joint-1 to an end-effector at
# the location of Joint-5 with a priority of 2 and a
# weight of 0.5
cmds.ikHandle( sj='joint1', ee='joint5', p=2, w=.5 )

# Create a handle called leg from the start joint
# named hip to the end-effector named Ankle.
cmds.ikHandle( n='Leg', sj='Hip', ee='Ankle' )