Inverse Kinematics Designer

Design inverse kinematics solvers, configurations, and waypoints

Since R2022a

Description

The Inverse Kinematics Designer enables you to design an inverse kinematics solver for a URDF robot model. You can adjust the inverse kinematics solver and add constraints to achieve the desired behavior. Using this app you can:

• Import URDF robot models from URDF files or the MATLAB Workspace.

• Adjust inverse kinematics solvers and constraints.

• Create joint configurations and export waypoints.

• Export solver settings, constraints, and joint configurations to the MATLAB^® workspace.

×

Open the Inverse Kinematics Designer App

• MATLAB Toolstrip: On the Apps tab, under Robotics And Autonomous Systems, click Inverse Kinematics Designer .

• MATLAB command prompt: Enter inverseKinematicsDesigner.

Examples

Create Inverse Kinematics Designer Session

This example shows how to create, load, and save an Inverse Kinematics Designer session in addition to loading a robot into the session. The completed file is attached for reference as iksessiondata.mat. Load the session with the inverseKinematicsDesigner function or follow along with this example to create it.

Create Session

Open Inverse Kinematics Designer by using the inverseKinematicsDesigner function.

inverseKinematicsDesigner

Load Robot into Session

Use loadrobot from the Command Window to load a rigidBodyTree such as a Universal UR5e into the Workspace. importrobot can also be used to import a rigidBodyTree object from any robot URDF file.

uniUR5e = loadrobot("universalUR5e");

Click New Session and select uniUR5e from the table in the dialog and click OK. This table contains all of the rigidBodyTree objects in the workspace. If you do not see your object in the table, verify that it is in your workspace and click Refresh.

Alternatively, you can load a robot by selecting from a list of robot models that come with the Robotics System Toolbox™ using the Rigid body tree drop down dialog and clicking OK.

The Scene Canvas now contains the robot model, and the Scene Browser now displays all of the rigid bodies of the robot.

Add Collision Objects

To add a collision object into the Scene Canvas, a collision object must be in the Workspace. For convenience, this example provides a simple box to use. For more information about creating collision objects, see collisionMesh, collisionBox, collisionSphere, and collisionCylinder.

Load the collisionobject MAT file which will save a collisionBox named box to your Workspace. Click Add Collision Object, and select box, from the table. Click OK to add it to the Scene Canvas.

The Scene Canvas now contains both the robot and the collision object. We will keep the object in this example, but if you want to delete the collision object, find the collision object in the Scene Browser under Scene, right-click the name of the collision object and click Delete.

The position and Euler orientation of the object can viewed using the Scene Inspector when the object is selected in either the Scene Canvas or Scene Browser. The properties listed will change depending on the type of the collision object selected.

Save Session

To save this session, click Save Session. If this is the first time saving the session, name the file and select a location to save it. The file will be saved as a MAT (*.mat) file containing all session data and settings.

Load Saved Session

To load a session file, click Open Session from the Inverse Kinematics Designer app or specify the MAT file as a string to the inverseKinematicsDesigner. An example of this session has been provided in this example as iksessiondata.mat.

inverseKinematicsDesigner("iksessiondata.mat")

Use Scene Canvas and Move Robot

This example shows how to use the Scene Canvas and move a robot in it using the Inverse Kinematics Designer app.

Load an existing session (iksessiondata.mat) or refer to the Create Inverse Kinematics Designer Session example to create a session.

inverseKinematicsDesigner

Scene Canvas Controls

Use the axes toolbar in the Scene Canvas to control the view.

To rotate the Scene Canvas, select the Rotate 3D button and click and drag within the scene.

Click the Pan button and click and drag within the scene to pan within the Scene Canvas.

Select the Zoom In, or Zoom Out buttons and click and drag up or down to zoom in or out of an area within the Scene Canvas respectively.

Click the Restore View button to revert to the original default view.

Move Robot

Move the robot using constraints such as the preset Marker Pose Target constraint. The Marker Pose Target constraint is the simplest constraint to use to move the robot. This constraint sets a target pose on the last body in the robot model. In this case the marker body is set to tool0. The marker is visualized on top of the selected marker body with the red, green, and blue linear and circular indicators in the Scene Canvas. Clicking and dragging the linear or circular indicators will change the target position and Euler orientation respectively. The colors correspond to the axes colors indicated in the bottom left of the Scene Canvas.

Click Marker Pose Constraint to open the Constraint tab. From the Constraint tab, set Cartesian position in meters, Euler orientation in degrees, and the weights and tolerances of the position and orientation. The marker body can be changed in either the Constraint tab under End Effector Body list or in the Marker Body list in the Inverse Kinematics tab. Click Apply to save any changes, and click Close Constraint to exit the Constraint tab. Note that the specified Euler angles are computed using XYZ sequence.

The Marker Pose Target constraint can also be toggled on or off by using clearing or selecting the check box next to the Marker Pose Target constraint in the Constraints Browser.

Solution Details

When the Marker Pose Target is moved, it sets the target pose and the inverse kinematics solver solves for a configuration where the selected marker body reaches the target pose. If it cannot find a solution to the target pose, the robot will move to the best available solution and the marker body will not move to the Marker Pose Target. This kind of solution can be identified visually by the constraint icon in the Constraints Browser. The icon with red x shows that the constraint is not met, while the green check shows that the constraint is being met.

To find more information about why the solver failed to reach the solution, click the Report Status to see the details of the solver's solution. The number of Iterations and Number of Random Restarts list the number of times that the solver executed each respectively. The Constraints Violations shows structure array of all the conflicts that can be displayed in the command window. The status will show success if the solver successfully solves for the target pose, or best available if the solver is showing the best available solution it found if it could not reach the target pose. Exit Flag provides more detail on the execution of the specific solver algorithm. See Inverse Kinematics Algorithms for more information about the different exit flag types.

To troubleshoot why a solver failed to reach a solution, see Resolving Constraint Conflict for some tips.

Create Collision-Free Configurations and Export Waypoints

This example shows how to use Inverse Kinematics Designer to create joint configurations and check for collisions using the Scene Inspector. This example uses data and skills from Create Inverse Kinematics Designer Session, and Use Scene Canvas and Move Robot. Refer to those examples before continuing.

Load Session

Use inverseKinematicsDesigner with the iksessiondata.mat session file to load a robot with a basic collision object in the scene.

inverseKinematicsDesigner

Create Configurations

Use the Configurations Panel to create, modify, and view configurations.

Before moving the robot, click Store Configuration to save the current joint configuration of the robot as shown in the Scene Canvas. This adds the configuration to the table in the Configurations Panel with a default configuration name, the Collision Status, and Value of each joint as a vector. Both the name and value of each configuration can be edited by double-clicking the respective element. Rename this configuration to home and leave its Value at [0.00 0.00 0.00 0.00 0.00 0.00].

Create another configuration, but this time making it collide with the box. Set the end-effector into the center of the box at [-0.5 0.5 0] using the Marker Pose Constraint, and store the configuration. To switch the view between multiple configurations, select a configuration, click Snap to Configuration or click the forward or backward step buttons to step to switch the current configuration.

Check Collisions

Click Check Collisions > Check All Configurations to update the Collision Status of all the stored configurations. To check one configuration, select desired configuration, click Snap to Configuration, and click Check Collisions > Check Current Configuration to update the Collision Status of the currently selected configuration.

After the collision checking, the Collision Status of the first and second configuration contain PASS and FAIL respectively. Select the configuration that failed the collision check. The bodies in the Scene Browser update for the selected configuration to display an red x or green check icon, indicating that the body is in-collision or collision-free respectively. The bodies marked as in-collision will also be highlighted in red in the Scene Canvas. Note that flange and tool0 are indicated to be collision-free even though they appear to be positionally in-collision. This is because those bodies are just frames and do not contain collision meshes. If you intend to check for collisions, ensure before importing any robot that the physical bodies of your robot contain collision meshes.

Select the box, either by clicking on it in the Scene Browser, or in the Scene Canvas, and then inspect the States pane. The States pane contains the position, orientation, collision status, and a list of all the known collisions since the last collision check. The Known Collisions list shows all of the bodies colliding with the selected body. Selecting any of the bodies from the list and clicking Inspect Selected Body will switch the Scene Inspector to that body.

Create Configuration Path

To create a path, add configurations to the table sequential sequentially. Since the second configuration is in-collision with the box, select it and click delete.

Set the target marker pose to behind the box at [-0.9 0.0 0.1], and store the configuration. This configuration will the be goal configuration so rename it as goal.

Snap to configuration home and add an additional configuration over the box at [-0.5 0.5 0.5] to act as an intermediate configuration between home and goal. If a configuration needs to be modified, snap to that configuration, adjust the target marker pose, save a new configuration, and delete the old configuration. Click the move configuration buttons to move the new configuration between the home and goal configurations.

Click Check Collisions > Check All Configurations to check all the configurations for collisions. If a configuration does not pass, adjust it as necessary.

Export Configurations as Waypoints

Saving the session will also save the stored configurations within the session, but to export the configurations as waypoints to the MATLAB™ Workspace, click Export > Configurations. Select all of the configurations to export, specify the name of the waypoint matrix in Waypoint matrix name and click Export. Check your workspace for a matrix containing waypoints. Note that the size of the waypoint matrix is dependent on the number of configurations exported and the number of joints of the robot, and will be exported in row format. The dimensions of the waypoint matrix for this example is 3x6.

Related Examples

• Plan Manipulator Path for Dispensing Task Using Inverse Kinematics Designer
• Create Constrained Inverse Kinematics Solver Using Inverse Kinematics Designer

Parameters

Session

Inverse Kinematics — Manage session, check collisions, import and export solver/constraints/configurations

tab

Use the Inverse Kinematics tab to manage session, add and edit constraints, check collisions for configurations, and import and export solvers, constraints, and configurations. The parameters and buttons in this tab are usable only after a session has been created or loaded.

Parameters/Buttons	Description
New Session	Click New Session to load a specified robot from the workspace or from the lists of robots in the robot library using the New Session dialog box.
Open Session	Click Open Session to load a saved session MAT-file.
Save Session	Click Save Session to save the current session as a MAT-file.
Import	Click Import > Solver to import a solver from the workspace using the Import Inverse Kinematics Solver dialog box. Click Import > Constraints to import constraint(s) from the workspace using the Import Inverse Kinematics Constraints dialog box. Click Import > Configurations to import configuration(s) from the workspace using the Import Joint Configurations dialog box.
Add Collision Object	Click Add Collision Object to add collision objects to the scene from the workspace using the Add Collision Object dialog box.
Add Constraint	Click Add Constraint to add a constraint to the inverse kinematics solver using the Constraint tab.
Edit Constraint	Click Edit Constraint to edit the selected solver constraint using the Constraint tab.
Refresh Solver	Click Refresh Solver to run the inverse kinematics solver using the current configuration as the initial guess.
Solver Settings	Click Solver Settings to edit the inverse kinematics solver settings using the Solver tab.
Report Status	Click Report Status to view the status of the most recent inverse kinematics solver solution using the Solution Report dialog box.
Marker Pose Constraint	Click Marker Pose Constraint to edit the Marker Pose Target from the Constraint tab.
Marker Body	Select a body from the list of bodies in the loaded robot model to be constrained by the marker pose target constraint. By default, Marker Body is set to the last body in the robot model.
Check Collisions	Click Check Collisions > Check Current Configuration to check the current configuration for collisions with collision objects in the scene. Click Check Collisions > Check All Configurations to check the all stored configurations for any collisions with collision objects in the scene. Select Ignore Self-Collisions to ignore collisions between bodies of the robot.
Export	Click Export > Solver and Constraints to export the current solver and constraints to the workspace as objects using the Export Solver and Constraints dialog box. Click Export > Configurations to export configurations from the Configurations Panel to the workspace as a matrix using the Export Waypoints dialog box.

Solver — Solver settings

tab

These parameters specify settings for the inverse kinematics solver. To access these parameters, open the Solver tab. To open the Solver tab, on the Inverse Kinematics tab, select Solver Settings.

Parameters	Description
Solver Algorithm	Inverse kinematics solver algorithm, specified as one of these options: BFGS Gradient Projection (default) Levenberg-Marquardt For more information on how to select a solver, see Choose an Algorithm.
Max Iterations	Maximum number of iterations for the inverse kinematics solver to run, specified as a positive integer. The default value is 50.
Max Time	Maximum time that the inverse kinematics solver can search for a solution, specified as a positive scalar in seconds. The default value is 5.
Enforce Joint Limits	Select to set the inverse kinematics solver to enforce joint limits from the robot model. The default value is on. For more details about enforcing joint limits, see Solver Parameters.
Allow Random Restart	Select to allow the inverse kinematics solver to restart with a different randomly generated initial guess if the algorithm approaches a solution that does not satisfy the constraints. The default value is on. For more details about enforcing joint limits, see Solver Parameters.

Click Reset Settings > Reset Settings and Reset Settings > Reset To Default Settings to reset the inverse kinematics solver settings to the last stored value and default settings respectively.

After editing the solver settings, click Apply to Solver to apply changes to the current inverse kinematics solver.

Constraint — Add or edit constraint

tab

To open the Constraint tab and create a constraint, on the Inverse Kinematics tab, select Add Constraint. Set the name of the constraint and select the type of constraint. The Constraint tab also contains a section with parameters for the selected constraint:

• Pose Constraint — Constraint that assigns a target pose to a body. See the corresponding tab section Pose Constraint, and MATLAB object constraintPoseTarget, for more information.

• Cartesian Bounds Constraint — Constraint that defines a bounded target region for an end-effector pose. See the corresponding tab section Cartesian Bounds Constraint, and MATLAB object constraintCartesianBounds, for more information.

• Aiming Constraint — Constraint that assigns custom joint limits. See the corresponding tab section, Aiming Constraint, and MATLAB object constraintAiming for more information.

• Joint Bounds Constraint — Constraint that assigns custom joint limits. See the corresponding tab section, Joint Bounds Constraint, and MATLAB object constraintJointBounds for more information.

• Distance Bounds Constraint — Constraint that defines a minimum and maximum distance that two bodies can be from each other. See the corresponding tab section, Distance Bounds Constraint, and MATLAB object constraintDistanceBounds for more information.

• Fixed Joint Constraint — Constraint that fixes the position and orientation between two bodies. See the corresponding tab section, Fixed Joint Constraint, and MATLAB object constraintFixedJoint for more information.

• Revolute Joint Constraint — Constraint that simulates revolute motion between two bodies. See the corresponding tab section Revolute Joint Constraint, and MATLAB object constraintRevoluteJoint, for more information.

• Prismatic Joint Constraint — Constraint that simulates prismatic motion between two bodies. See the corresponding tab section, Prismatic Joint Constraint, and MATLAB object constraintPrismaticJoint for more information.

After setting the constraint parameters, click Apply to save your changes and select Close Constraint to return to the Inverse Kinematics tab. If you do not click Apply before closing the Constraint tab, Inverse Kinematics Designer does not save your changes..

New Session — Start new session and select robot model

dialog box

Start new session and select robot model as a rigidBodyTree either from the Rigid body tree list or the MATLAB workspace. To import a robot into the workspace, use either the loadrobot function or importrobot function.

For more information about how to create a rigid body tree, see Build Basic Rigid Body Tree Models.

For a full list of all the rigid body trees included with the Robotics System Toolbox™, see the robotname input of loadrobot.

Add Collision Object — Add collision meshes from workspace

dialog box

Add collision meshes from the MATLAB workspace, specified as collisionBox, collisionCylinder, collisionSphere, or collisionMesh objects. The Add Collision Object dialog box is accessible by clicking Add Collision Object in the Inverse Kinematics tab.

Solution Report — Details of most recent inverse kinematics solution

dialog box

View the details of the most recent inverse kinematics solution in the Solution Report dialog box. To access these parameters, on the Inverse Kinematics tab, select Report Status.

These parameters are read-only.

Parameter	Description
Iterations	Number of iterations needed to achieve the solution result.
Number of Random Restarts	Number of times that the solution randomly restarted. Random restarts are triggered when the algorithm approaches a solution that does not satisfy the constraints. The solver restarts with a randomly generated initial guess.
Constraint Violations	Constraint violations, indicated as a 1-by-N structure array, where N is the number of enabled constraints in the session. Select 1xN struct array to print the details of each constraint violation in the Command Window. See Constraint Violation Format for more details.
Status	Status of the solution, indicated as either Success or Best available. Success indicates that the solver successfully reached a configuration that satisfies all constraints. Best available indicates that the solver did not reach a configuration that satisfies all constraints, and is showing the best available configuration it could achieve.
Exit Flag	Exit flag of the solver. See Exit Flags for more information.

Constraints

Pose Constraint — Pose constraint settings

tab section

Click Pose Constraint in the Constraint tab to open the Pose Constraint tab section to create a constraint.

Parameter	Description
End Effector Body	End-effector body, specified as a selection from a list of bodies in the loaded robot model. The default value is set to the last body in the loaded robot model.
Reference Body	Reference body, specified as a selection from a list of bodies in the loaded robot model. The default value is set to the first body in the loaded robot model.
X	Target x position of the end effector in the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.
Y	Target y position of the end effector in the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.
Z	Target z position of the end effector in the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.
Euler X	Target Euler x rotation of the end-effector body in the reference frame of the Reference Body, specified as a scalar in degrees. The default value is 0.
Euler Y	Target Euler y rotation of the end-effector body in the reference frame of the Reference Body, specified as a scalar in degrees. The default value is 0.
Euler Z	Target Euler z rotation of the end-effector body in the reference frame of the Reference Body, specified as a scalar in degrees. The default value is 0.
Position Tolerance	Tolerance for the end-effector position, specified as a nonnegative scalar in meters. The default value is 0.01.
Position Weight	Weight for the end-effector position, specified as a nonnegative scalar. The default value is 1.
Orientation Tolerance	Tolerance for the end-effector orientation, specified as a nonnegative scalar in degrees. The default value is 1.
Orientation Weight	Weight for the end-effector orientation, specified as a nonnegative scalar. The default value is 1.

Cartesian Bounds Constraint — Cartesian bounds constraint settings

tab section

Click Cartesian Bounds Constraint in the Constraint tab to open the Cartesian Bounds Constraint tab section to create a constraint.

Parameter	Description
End Effector Body	End-effector body, specified as a selection from a list of bodies in the loaded robot model. The default value is set to the last body in the loaded robot model.
Reference Body	Reference body, specified as a selection from a list of bodies in the loaded robot model. The default value is set to the first body in the loaded robot model.
X	Target x position of the end effector in the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.
Y	Target y position of the end effector in the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.
Z	Target z position of the end effector in the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.
Euler X	Target Euler x rotation of the end-effector body in the reference frame of the Reference Body, specified as a scalar in degrees. The default value is 0.
Euler Y	Target Euler y rotation of the end-effector body in the reference frame of the Reference Body, specified as a scalar in degrees. The default value is 0.
Euler Z	Target Euler z rotation of the end-effector body in the reference frame of the Reference Body, specified as a scalar in degrees. The default value is 0.
X Min	Minimum x bound on end-effector position relative to the reference frame of the Reference Body, specified as a scalar in meters. The default value is -0.5.
Y Min	Minimum y bound on end-effector position relative to the reference frame of the Reference Body, specified as a scalar in meters. The default value is -0.5
Z Min	Minimum z bound on end-effector position relative to the reference frame of the Reference Body, specified as a scalar in meters. The default value is -0.5
X Max	Maximum x bound on end-effector position relative to the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.5
Y Max	Maximum y bound on end-effector position relative to the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.5
Z Max	Maximum z bound on end-effector position relative to the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.5
X Weight	Weight of the constraint on x bound, specified as a scalar. The default value is 1.
Y Weight	Weight of the constraint on y bound, specified as a scalar. The default value is 1.
Z Weight	Weight of the constraint on z bound, specified as a scalar. The default value is 1.

Aiming Constraint — Aiming constraint settings

tab section

Click Aiming Constraint in the Constraint tab to open the Aiming Constraint tab section to create a constraint.

Parameter	Description
End Effector Body	End-effector body, specified as a selection from a list of bodies in the loaded robot model. The default value is set to the last body in the loaded robot model.
Reference Body	Reference body, specified as a selection from a list of bodies in the loaded robot model. The default value is set to the first body in the loaded robot model.
X Target	Target x position relative to Reference Body, specified as a scalar in meters. The default value is 0.
Y Target	Target y position relative to Reference Body, specified as a scalar in meters. The default value is 0.
Z Target	Target z position relative to Reference Body, specified as a scalar in meters. The default value is 0.
Angular Tolerance	Maximum allowed angular tolerance, specified as a nonnegative scalar in degrees. The default value is 1.
Constraint Weight	Weight of constraint, specified as a scalar. The default value is 1.

Joint Bounds Constraint — Joint bounds constraint settings

tab section

Click Joint Bounds Constraint in the Constraint tab to open the Joint Bounds Constraint tab section to create a constraint.

Parameter	Description
Upper Joint Limits	Upper joint limit angles, specified as a N-element row vector of angles in degrees, where N is the number of moving joints in the robot model. The default value is 180*ones(1,N).
Lower Joint Limits	Lower joint limit angles, specified as a N-element row vector of angles in degrees, where N is the number of moving joints in the robot model. The default value is -180*ones(1,N).
Joint Limit Weights	Joint limit weights, specified as a N-element row vector where N is the number of moving joints in the robot model. The default value is ones(1,N).

Distance Bounds Constraint — Distance bounds constraint settings

tab section

On the Constraint tab, select Distance Bounds Constraint in the Constraint tab to create a distance bounds constraint and open the Distance Bounds Constraint section.

Parameter	Description
End Effector Body	End-effector body, selected from a list of bodies in the loaded robot model. The default value is the last body in the loaded robot model.
Reference Body	Reference body, selected from a list of bodies in the loaded robot model. The default value is the first body in the loaded robot model.
Max Distance	Maximum distance bound on the end-effector position relative to the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.
Min Distance	Minimum distance bound on end-effector position relative to the reference frame of the Reference Body, specified as a scalar in meters. The default value is 0.
Distance Weight	Weight for the end-effector position, specified as a nonnegative scalar. The default value is 1.

Fixed Joint Constraint — Fixed joint constraint settings

tab section

On the Constraint tab, select Fixed Joint Constraint in the Constraint tab to create a fixed joint constraint and open the Fixed Joint Constraint section.

Parameter	Description
Successor Body	Successor body, selected from a list of bodies in the loaded robot model. The default value is the last body in the loaded robot model
Predecessor Body	Predecessor body, selected from a list of bodies in the loaded robot model. The default value is the first body in the loaded robot model.
Position Tolerance	Tolerance for the end-effector position, specified as a nonnegative scalar in meters. The default value is 0.01.
Position Weight	Weight for the end-effector position, specified as a nonnegative scalar. The default value is 1.
Orientation Tolerance	Tolerance for the end-effector orientation, specified as a nonnegative scalar in degrees. The default value is 1.
Orientation Weight	Weight for the end-effector orientation, specified as a nonnegative scalar. The default value is 1.

To set the successor and predecessor transforms, select Successor Transform or Predecessor Transform, respectively:

Parameter	Description
X	Target x-position of the successor or predecessor transform in the reference frame of the corresponding body. specified as a scalar in meters. The default value is 0.
Y	Target y-position of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in meters. The default value is 0.
Z	Target z-position of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in meters. The default value is 0.
Euler X	Target Euler x-rotation of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in degrees. The default value is 0.
Euler Y	Target Euler y-rotation of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in degrees. The default value is 0.
Euler Z	Target Euler z-rotation of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in degrees. The default value is 0.
Import from workspace	Import a transform from the workspace as an se3 transformation object.

Prismatic Joint Constraint — Prismatic joint constraint settings

tab section

On the Constraint tab, select Prismatic Joint Constraint in the Constraint tab to create a prismatic joint constraint and open the Prismatic Joint Constraint tab.

Parameter	Description
Successor Body	Successor body, selected from a list of bodies in the loaded robot model. The default value is the last body in the loaded robot model
Predecessor Body	Predecessor body, selected from a list of bodies in the loaded robot model. The default value is the first body in the loaded robot model.
Position Tolerance	Tolerance for the position of the aligned successor and predecessor transforms, specified as a nonnegative scalar in meters. The default value is 0.01.
Position Weight	Weight for the position of the aligned successor and predecessor transforms, specified as a nonnegative scalar. The default value is 1.
Orientation Tolerance	Tolerance for the orientation of the aligned successor and predecessor transforms, specified as a nonnegative scalar in degrees. The default value is 1.
Orientation Weight	Weight for the orientation of the aligned successor and predecessor transforms, specified as a nonnegative scalar. The default value is 1.
Joint Limits	Position limits of the joint constraint, specified as a two-element row vector of the form [minimum maximum], in meters. The default value is [-1 1].
Joint Limits Weight	Weight for the joint position limits, specified as a nonnegative scalar. The default value is 1.

To set the successor and predecessor transforms, select Successor Transform or Predecessor Transform, respectively:

Parameter	Description
X	Target x-position of the successor or predecessor transform in the reference frame of the corresponding body. specified as a scalar in meters. The default value is 0.
Y	Target y-position of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in meters. The default value is 0.
Z	Target z-position of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in meters. The default value is 0.
Euler X	Target Euler x-rotation of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in degrees. The default value is 0.
Euler Y	Target Euler y-rotation of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in degrees. The default value is 0.
Euler Z	Target Euler z-rotation of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in degrees. The default value is 0.
Import from workspace	Import a transform from the workspace as an se3 transformation object.

Revolute Joint Constraint — Revolute joint constraint settings

tab section

On the Constraint tab, select Revolute Joint Constraint in the Constraint tab to create a revolute joint constraint and open the Revolute Joint Constraint tab.

Parameter	Description
Successor Body	Successor body, selected from a list of bodies in the loaded robot model. The default value is the last body in the loaded robot model
Predecessor Body	Predecessor body, selected from a list of bodies in the loaded robot model. The default value is the first body in the loaded robot model.
Position Tolerance	Tolerance for the position of the aligned successor and predecessor transforms, specified as a nonnegative scalar in meters. The default value is 0.01.
Position Weight	Weight for the position of the aligned successor and predecessor transforms, specified as a nonnegative scalar. The default value is 1.
Orientation Tolerance	Tolerance for the orientation of the aligned successor and predecessor transforms, specified as a nonnegative scalar in degrees. The default value is 1.
Orientation Weight	Weight for the orientation of the aligned successor and predecessor transforms, specified as a nonnegative scalar. The default value is 1.
Joint Limits	Position limits of the joint constraint, specified as a two-element row vector of the form [minimum maximum], in degrees. The default value is [-180 180].
Joint Limits Weight	Weight for the joint position limits, specified as a nonnegative scalar. The default value is 1.

To set the successor and predecessor transforms, select Successor Transform or Predecessor Transform, respectively:

Parameter	Description
X	Target x-position of the successor or predecessor transform in the reference frame of the corresponding body. specified as a scalar in meters. The default value is 0.
Y	Target y-position of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in meters. The default value is 0.
Z	Target z-position of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in meters. The default value is 0.
Euler X	Target Euler x-rotation of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in degrees. The default value is 0.
Euler Y	Target Euler y-rotation of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in degrees. The default value is 0.
Euler Z	Target Euler z-rotation of the successor or predecessor transform in the reference frame of the corresponding body, specified as a scalar in degrees. The default value is 0.
Import from workspace	Import a transform from the workspace as an se3 transformation object.

Import

Import Inverse Kinematics Solver — Import inverse kinematics solver

dialog box

Import an inverse kinematics solver from the MATLAB workspace, specified as either a generalizedInverseKinematics, or inverseKinematics object. Solvers in the Workspace appear in the Available solvers table. Select a solver and click Import to import the solver into the Inverse Kinematics Designer app. If a solver from the Workspace does not appear in the Available solvers table, click Refresh.

Import Joint Configurations — Import joint configurations

dialog box

Import joint configurations from the MATLAB workspace, specified as an M-by-N matrix of doubles where M is the number of configurations, and N is the number of moveable joints in the robot. Configuration data in the Workspace appear in the Configurations in the workspace table. Select configuration data and click Import to import the configuration data into the Inverse Kinematics Designer app.

If a configuration in the Workspace does not appear in the Configurations in the workspace table, click Refresh.

Import Inverse Kinematics Constraints — Import inverse kinematics constraints

dialog box

Import inverse kinematics constraints from the Workspace, specified as a constraintAiming, constraintPoseTarget, constraintCartesianBounds, or constraintJointBounds object. Constraint objects in the Workspace appear in the Configurations in the workspace table. Select the desired constraint objects and click Import to import the constraints into the Inverse Kinematics Designer app.

If a configuration in the Workspace does not appear in the Constraint objects in the workspace table, click Refresh.

Import Transform — Import transform

dialog box

Import a transform from the workspace to use as a successor or predecessor transform, specified as an se3 object. Transforms in the workspace appear in the SE(3) objects in the workspace table. Select the desired transform and click Import to import the transform into the Inverse Kinematics Designer app.

If a transform in the workspace does not appear in the SE(3) objects in the workspace table, click Refresh.

Export

Export Solver and Constraints — Solver and constraint export settings

dialog box

Change solver and constraint export settings, and export the solver and constraints to the MATLAB. To access these parameters, on the Inverse Kinematics tab, select Export > Solver and Constraints. When all settings and selections are complete, click Export to export the solver and constraints to the workspace.

Parameter	Description
Export solver	Select to include the inverse kinematics solver when exporting. The default value is on.
Solver name	Name of the inverse kinematics solver. The default value is ikSolver.
Export constraints	Select to include the solver constraints when exporting. The default value is on.
Constraints cell array name	Name of the solver constraints cell array, specified as a string. The default value is ikConstraints. To enable this parameter, select the Export constraints parameter.
Available constraints	Table containing solver constraints, listing the name, size, and class of each constraint. Select constraints from this table and click Export to export the constraints to the workspace. To enable this parameter, select the Export constraints parameter.

Export Waypoints — Export configurations as waypoints

dialog box

Export configurations as waypoints using the Export Waypoints dialog box. To access these parameters, on the Inverse Kinematics tab, select Export > Configurations. When selections are complete, click Export to export the waypoints as an M-by-N matrix of data type double to the MATLAB workspace, where M is the number of waypoints, and N is the number of movable joints in the robot.

Parameter	Description
Waypoint matrix name	Name of waypoint matrix. The default value is waypointData.
Available configurations	Table containing available configurations, listing the name, size, and class of each constraint. Select configurations from this table and click Export to export the configurations to the workspace as waypoints.

Programmatic Use

inverseKinematicsDesigner

inverseKinematicsDesigner opens the Inverse Kinematics Designer app.

inverseKinematicsDesigner(sessionFileName)

inverseKinematicsDesigner(sessionFileName) opens the Inverse Kinematics Designer app and loads the specified inverse kinematics session MAT file that was previously saved from the app.

More About

Resolving Constraint Conflict

Constraint conflicts occur when constraints cannot be met by the solver. They are indicated in the Constraints Browser with a red symbol next to the corresponding constraint. When the constraint is met during the most recent solution, the Constraints Browser indicates this with a green symbol next to the corresponding constraint. To solve these conflicts, troubleshoot your constraints based on the last action you performed:

• If you moved the marker pose constraint, check if the pose you specified is within the bounds of the robot. If it is not within the bounds, try moving it to somewhere within the bounds and see if this resolves the conflict. If the constraint conflict does not resolve, the constraint may be in conflict with joint limits or another constraint. In this case, consider modifying the parameters of the marker pose constraint, such as the weights.

  Note

  The solver assumes priority using the assigned weights of each constraint when attempting to satisfy each constraint.

• If you added a constraint, verify if it is causing the conflict by clearing that constraint in the Constraints Browser and clicking Refresh Solver. If all other constraints resolve, edit the parameters of this constraint, or ensure that the existing unresolved constraints have the desired parameter values, to resolve the conflict.

• If you modified a constraint, change the parameters of that constraint, if applicable, or edit the parameters of other unresolved constraints. Consider modifying the solver weights of each constraint, or disabling constraints to see if some constraint conflicts can be resolved independently.

Constraint Violation Format

When you select the constraint violations structure array from the Solution Report dialog box, the Inverse Kinematics Designer prints the type, violation magnitude, and name of each enabled constraint in the Constraints Browser to the MATLAB Command Window. The structure contains these fields for each constraint:

• Type — Type of constraint, represented as:

  • 'pose' — Pose constraint.

  • 'aiming' — Aiming constraint.

  • 'joint' — Joint constraint.

  • 'cartesian' — Cartesian constraint.

  • 'distance' — Distance bounds constraint.

  • 'fixedjoint' — Fixed joint constraint.

  • 'revolutejoint' — Revolute joint constraint.

  • 'prismaticjoint' — Prismatic joint constraint.

• Violation — Magnitude of the violation along each weighted part of the constraint during optimization. A violation magnitude of 0 indicates no violation, and that the constraint has been met. The format of the magnitude changes depending on the Type:

  • 'pose' — Two-element row vector of the form [position orientation], where position is the magnitude of the position violation, and orientation is the magnitude of the orientation violation.

  • 'aiming' — Scalar indicating the magnitude of the orientation violation.

  • 'joint' — N-element row vector indicating the magnitude of the joint bound violation for each of the N joints in the rigid body tree.

  • 'cartesian' — Three-element row vector of the form [xBound yBound zBound], where xBound indicates the magnitude of the violation in the x-bound, yBound indicates the magnitude of the violation in the y-bound, and zBound indicates the magnitude of the violation in the z-bound.

  • 'distance' — Scalar indicating the magnitude of the distance violation.

  • 'fixedjoint' — Two-element row vector of the form [position orientation], where position is the magnitude of the position violation, and orientation is the magnitude of the orientation violation.

  • 'revolutejoint' — Three-element row vector of the form [xEul yEul zEul], where xEul, yEul, and zEul are the magnitudes of the orientation violations in the x-, y-, and z-axes, respectively.

  • 'prismaticjoint' — Three-element row vector of the form [xPosition yPosition zPosition], where xPosition, yPosition, and zPosition are the magnitudes of the position violation in the x-, y-, and z-axes, respectively.

  Note

  Positive magnitudes that are close to 0 can still indicate success. For example, 1e-10 indicates almost no constraint violation.

• Name — Name of the constraint in the Constraints Browser.

For example, the constraint violations structure prints information for a pose constraint named PoseConstraint, with violations in position and orientation, as:

***
Type: 'pose'
Violation: [0.2638 0.8253]
Name: "PoseConstraint"
***

Version History

Introduced in R2022a

R2023a: Inverse Kinematics Designer supports additional constraints

Inverse Kinematics Designer supports now supports these additional constraints:

• Distance Bounds Constraint

• Fixed Joint Constraint

• Prismatic Joint Constraint

• Revolute Joint Constraint