inverseKinematics

Create inverse kinematic solver

Description

The inverseKinematics System object™ creates an inverse kinematic (IK) solver to calculate joint configurations for a desired end-effector pose based on a specified rigid body tree model. Create a rigid body tree model for your robot using the rigidBodyTree class. This model defines all the joint constraints that the solver enforces. If a solution is possible, the joint limits specified in the robot model are obeyed.

To specify more constraints besides the end-effector pose, including aiming constraints, position bounds, or orientation targets, consider using generalizedInverseKinematics. This object allows you to compute multiconstraint IK solutions.

For closed-form analytical IK solutions, see analyticalInverseKinematics.

To compute joint configurations for a desired end-effector pose:

1. Create the inverseKinematics object and set its properties.

2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?

Creation

Syntax

ik = inverseKinematics

ik = inverseKinematics(Name,Value)

Description

ik = inverseKinematics creates an inverse kinematic solver. To use the solver, specify a rigid body tree model in the RigidBodyTree property.

ik = inverseKinematics(Name,Value) creates an inverse kinematic solver with additional options specified by one or more Name,Value pair arguments. Name is a property name and Value is the corresponding value. Name must appear inside single quotes (''). You can specify several name-value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Properties

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

RigidBodyTree — Rigid body tree model

rigidBodyTree object

Rigid body tree model, specified as a rigidBodyTree object. If you modify your rigid body tree model, reassign the rigid body tree to this property. For example:

Create IK solver and specify the rigid body tree.

ik = inverseKinematics('RigidBodyTree',rigidbodytree)

Modify the rigid body tree model.

addBody(rigidbodytree,rigidBody('body1'),'base')

Reassign the rigid body tree to the IK solver. If the solver or the step function is called before modifying the rigid body tree model, use release to allow the property to be changed.

ik.RigidBodyTree = rigidbodytree;

SolverAlgorithm — Algorithm for solving inverse kinematics

'BFGSGradientProjection' (default) | 'LevenbergMarquardt'

Algorithm for solving inverse kinematics, specified as either 'BFGSGradientProjection' or 'LevenbergMarquardt'. For details of each algorithm, see Inverse Kinematics Algorithms.

SolverParameters — Parameters associated with algorithm

structure

Parameters associated with the specified algorithm, specified as a structure. The fields in the structure are specific to the algorithm. See Solver Parameters.

Usage

Syntax

[configSol,solInfo] = ik(endeffector,pose,weights,initialguess)

Description

[configSol,solInfo] = ik(endeffector,pose,weights,initialguess) finds a joint configuration that achieves the specified end-effector pose. Specify an initial guess for the configuration and your desired weights on the tolerances for the six components of pose. Solution information related to execution of the algorithm, solInfo, is returned with the joint configuration solution, configSol.

Input Arguments

endeffector — End-effector name

character vector

End-effector name, specified as a character vector. The end effector must be a body on the rigidBodyTree object specified in the inverseKinematics System object.

pose — End-effector pose

4-by-4 homogeneous transform

End-effector pose, specified as a 4-by-4 homogeneous transform. This transform defines the desired position and orientation of the rigid body specified in the endeffector property.

weights — Weight for pose tolerances

six-element vector

Weight for pose tolerances, specified as a six-element vector. The first three elements correspond to the weights on the error in orientation for the desired pose. The last three elements correspond to the weights on the error in xyz position for the desired pose.

initialguess — Initial guess of robot configuration

structure array | vector

Initial guess of robot configuration, specified as a structure array or vector. Use this initial guess to help guide the solver to a desired robot configuration. The solution is not guaranteed to be close to this initial guess.

To use the vector form, set the DataFormat property of the object assigned in the RigidBodyTree property to either 'row' or 'column' .

Output Arguments

configSol — Robot configuration solution

structure array | vector

Robot configuration, returned as a structure array. The structure array contains these fields:

• JointName — Character vector for the name of the joint specified in the RigidBodyTree robot model

• JointPosition — Position of the corresponding joint

This joint configuration is the computed solution that achieves the desired end-effector pose within the solution tolerance.

Note

For revolute joints, if the joint limits exceed a range of 2*pi, where joint position wrapping occurs, then the returned joint position is the one closest to the joint's lower bound.

To use the vector form, set the DataFormat property of the object assigned in the RigidBodyTree property to either 'row' or 'column' .

solInfo — Solution information

structure

Solution information, returned as a structure. The solution information structure contains these fields:

• Iterations — Number of iterations run by the algorithm.

• NumRandomRestarts — Number of random restarts because algorithm got stuck in a local minimum.

• PoseErrorNorm — The magnitude of the pose error for the solution compared to the desired end-effector pose.

• ExitFlag — Code that gives more details on the algorithm execution and what caused it to return. For the exit flags of each algorithm type, see Exit Flags.

• Status — Character vector describing whether the solution is within the tolerance ('success') or the best possible solution the algorithm could find ('best available').

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Generate Joint Positions to Achieve End-Effector Position

Generate joint positions for a robot model to achieve a desired end-effector position. The inverseKinematics system object uses inverse kinematic algorithms to solve for valid joint positions.

Load example robots. The puma1 robot is a rigidBodyTree model of a six-axis robot arm with six revolute joints.

load exampleRobots.mat
showdetails(puma1)

--------------------
Robot: (6 bodies)

 Idx    Body Name   Joint Name   Joint Type    Parent Name(Idx)   Children Name(s)
 ---    ---------   ----------   ----------    ----------------   ----------------
   1           L1         jnt1     revolute             base(0)   L2(2)  
   2           L2         jnt2     revolute               L1(1)   L3(3)  
   3           L3         jnt3     revolute               L2(2)   L4(4)  
   4           L4         jnt4     revolute               L3(3)   L5(5)  
   5           L5         jnt5     revolute               L4(4)   L6(6)  
   6           L6         jnt6     revolute               L5(5)   
--------------------

Generate a random configuration. Get the transformation from the end effector (L6) to the base for that random configuration. Use this transform as a goal pose of the end effector. Show this configuration.

randConfig = puma1.randomConfiguration;
tform = getTransform(puma1,randConfig,'L6','base');

show(puma1,randConfig);

Create an inverseKinematics object for the puma1 model. Specify weights for the different components of the pose. Use a lower magnitude weight for the orientation angles than the position components. Use the home configuration of the robot as an initial guess.

ik = inverseKinematics('RigidBodyTree',puma1);
weights = [0.25 0.25 0.25 1 1 1];
initialguess = puma1.homeConfiguration;

Calculate the joint positions using the ik object.

[configSoln,solnInfo] = ik('L6',tform,weights,initialguess);

Show the newly generated solution configuration. The solution is a slightly different joint configuration that achieves the same end-effector position. Multiple calls to the ik object can give similar or very different joint configurations.

show(puma1,configSoln);

References

[1] Badreddine, Hassan, Stefan Vandewalle, and Johan Meyers. "Sequential Quadratic Programming (SQP) for Optimal Control in Direct Numerical Simulation of Turbulent Flow." Journal of Computational Physics. 256 (2014): 1–16. doi:10.1016/j.jcp.2013.08.044.

[2] Bertsekas, Dimitri P. Nonlinear Programming. Belmont, MA: Athena Scientific, 1999.

[3] Goldfarb, Donald. "Extension of Davidon’s Variable Metric Method to Maximization Under Linear Inequality and Equality Constraints." SIAM Journal on Applied Mathematics. Vol. 17, No. 4 (1969): 739–64. doi:10.1137/0117067.

[4] Nocedal, Jorge, and Stephen Wright. Numerical Optimization. New York, NY: Springer, 2006.

[5] Sugihara, Tomomichi. "Solvability-Unconcerned Inverse Kinematics by the Levenberg–Marquardt Method." IEEE Transactions on Robotics Vol. 27, No. 5 (2011): 984–91. doi:10.1109/tro.2011.2148230.

[6] Zhao, Jianmin, and Norman I. Badler. "Inverse Kinematics Positioning Using Nonlinear Programming for Highly Articulated Figures." ACM Transactions on Graphics Vol. 13, No. 4 (1994): 313–36. doi:10.1145/195826.195827.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

When using code generation, you must specify the RigidBodyTree property to define the robot on construction of the object. For example:

ik = inverseKinematics('RigidBodyTree',robotModel);

You also cannot change the SolverAlgorithm property after creation. To specify the solver algorithm on creation, use:

ik = inverseKinematics('RigidBodyTree',robotModel,...
        'SolverAlgorithm','LevenbergMarquardt');

Version History

Introduced in R2016b

R2019b: inverseKinematics was renamed

The inverseKinematics object was renamed from robotics.InverseKinematics. Use inverseKinematics for all object creation.