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")

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.

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.