Main Content


Show robot model in figure



show(robot) plots the body frames of the robot model in a figure with the predefined home configuration. Both Frames and Visuals are displayed automatically.

show(robot,configuration) uses the joint positions specified in configuration to show the robot body frames.

show(___,Name,Value) specifies options using one or more name-value pair arguments in addition to any combination of input arguments from previous syntaxes. For example, 'Frames','off' hides the rigid body frames in the figure.

ax = show(___) returns the axes handle the robot is plotted on.


collapse all

You can import robots that have .stl files associated with the Unified Robot Description format (URDF) file to describe the visual geometries of the robot. Each rigid body has an individual visual geometry specified. The importrobot function parses the URDF file to get the robot model and visual geometries. The function assumes that visual geometry and collision geometry of the robot are the same and assigns the visual geometries as collision geometries of corresponsing bodies.

Use the show function to display the visual and collosion geometries of the robot model in a figure. You can then interact with the model by clicking components to inspect them and right-clicking to toggle visibility.

Import a robot model as a URDF file. The .stl file locations must be properly specified in this URDF. To add other .stl files to individual rigid bodies, see addVisual.

robot = importrobot('iiwa14.urdf');

Visualize the robot with the associated visual model. Click bodies or frames to inspect them. Right-click bodies to toggle visibility for each visual geometry.


Visualize the robot with the associated collision geometries. Click bodies or frames to inspect them. Right-click bodies to toggle visibility for each collision geometry.


Show different configurations of a robot created using a RigidBodyTree model. Use the homeConfiguration or randomConfiguation functions to generate the structure that defines all the joint positions.

Load example robots as RigidBodyTree objects.

load exampleRobots.mat

Create a structure for the home configuration of a Puma robot. The structure has joint names and positions for each body on the robot model.

config = homeConfiguration(puma1)
config=1×6 struct array with fields:

Show the home configuration using show. You do not need to specify a configuration input.


Modify the configuration and set the second joint position to pi/2. Show the resulting change in the robot configuration.

config(2).JointPosition = pi/2;

Create random configurations and show them.


Use the Denavit-Hartenberg (DH) parameters of the Puma560® robot to build a robot. Each rigid body is added one at a time, with the child-to-parent transform specified by the joint object.

The DH parameters define the geometry of the robot with relation to how each rigid body is attached to its parent. For convenience, setup the parameters for the Puma560 robot in a matrix. The Puma robot is a serial chain manipulator. The DH parameters are relative to the previous line in the matrix, corresponding to the previous joint attachment.

dhparams = [0   	pi/2	0   	0;
            0.4318	0       0       0
            0.0203	-pi/2	0.15005	0;
            0   	pi/2	0.4318	0;
            0       -pi/2	0   	0;
            0       0       0       0];

Create a rigid body tree object to build the robot.

robot = rigidBodyTree;

Create the first rigid body and add it to the robot. To add a rigid body:

  1. Create a rigidBody object and give it a unique name.

  2. Create a rigidBodyJoint object and give it a unique name.

  3. Use setFixedTransform to specify the body-to-body transformation using DH parameters. The last element of the DH parameters, theta, is ignored because the angle is dependent on the joint position.

  4. Call addBody to attach the first body joint to the base frame of the robot.

body1 = rigidBody('body1');
jnt1 = rigidBodyJoint('jnt1','revolute');

body1.Joint = jnt1;


Create and add other rigid bodies to the robot. Specify the previous body name when calling addBody to attach it. Each fixed transform is relative to the previous joint coordinate frame.

body2 = rigidBody('body2');
jnt2 = rigidBodyJoint('jnt2','revolute');
body3 = rigidBody('body3');
jnt3 = rigidBodyJoint('jnt3','revolute');
body4 = rigidBody('body4');
jnt4 = rigidBodyJoint('jnt4','revolute');
body5 = rigidBody('body5');
jnt5 = rigidBodyJoint('jnt5','revolute');
body6 = rigidBody('body6');
jnt6 = rigidBodyJoint('jnt6','revolute');


body2.Joint = jnt2;
body3.Joint = jnt3;
body4.Joint = jnt4;
body5.Joint = jnt5;
body6.Joint = jnt6;


Verify that your robot was built properly by using the showdetails or show function. showdetails lists all the bodies in the MATLAB® command window. show displays the robot with a given configuration (home by default). Calls to axis modify the axis limits and hide the axis labels.

Robot: (6 bodies)

 Idx    Body Name   Joint Name   Joint Type    Parent Name(Idx)   Children Name(s)
 ---    ---------   ----------   ----------    ----------------   ----------------
   1        body1         jnt1     revolute             base(0)   body2(2)  
   2        body2         jnt2     revolute            body1(1)   body3(3)  
   3        body3         jnt3     revolute            body2(2)   body4(4)  
   4        body4         jnt4     revolute            body3(3)   body5(5)  
   5        body5         jnt5     revolute            body4(4)   body6(6)  
   6        body6         jnt6     revolute            body5(5)   
axis off

Load a robot model and modify the collision meshes. Clear existing collision meshes, add simple collision object primitives, and check whether certain configurations are in collision.

Load Robot Model

Load a preconfigured robot model into the workspace using the loadrobot function. This model already has collision meshes specified for each body. Iterate through all the rigid body elements and clear the existing collision meshes. Confirm that the existing meshes are gone.

robot = loadrobot('kukaIiwa7','DataFormat','column');

for i = 1:robot.NumBodies


Add Collision Cylinders

Iteratively add a collision cylinder to each body. Skip some bodies for this specific model, as they overlap and always collide with the end effector (body 10).

collisionObj = collisionCylinder(0.05,0.25);

for i = 1:robot.NumBodies
    if i > 6 && i < 10
        % Skip these bodies.


Check for Collisions

Generate a series of random configurations. Check whether the robot is in collision at each configuration. Visualize each configuration that has a collision.

rng(0) % Set random seed for repeatability.
for i = 1:20
    config = randomConfiguration(robot);
    isColliding = checkCollision(robot,config);
    if isColliding
        title('Collision Detected')
        % Skip non-collisions.

Input Arguments

collapse all

Robot model, specified as a rigidBodyTree object.

Robot configuration, specified as a vector of joint positions or a structure with joint names and positions for all the bodies in the robot model. You can generate a configuration using homeConfiguration(robot), randomConfiguration(robot), or by specifying your own joint positions in a structure. To use the vector form of configuration, set the DataFormat property for the robot to either "row" or "column" .

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: 'Frames','off' hides the rigid body frames in the figure.

Parent of axes, specified as the comma-separated pair consisting of Parent and an Axes object in which to draw the robot. By default, the robot is plotted in the active axes.

Option to reserve robot plot, specified as the comma-separated pair consisting of "PreservePlot" and true or false. When this property is set to true, previous plots displayed by calling show are not overwritten. This setting functions similar to calling hold on for a standard MATLAB® figure, but is limited to the robot body frames. When this property is set to false, previous plots of the robot are overwritten.

Display body frames, specified as 'on' or 'off'. These frames are the coordinate frames of individual bodies on the rigid body tree.

Display visual geometries, specified as 'on' or 'off'. Individual visual geometries can also be turned off by right-clicking them in the figure.

Specify individual visual geometries using addVisual. To import a URDF robot model with .stl files for meshes, see the importrobot function.

Display collision geometries, specified as the comma-separated pair consisting of 'Collisions and 'on' or 'off'.

Add collision geometries to the individual rigid bodies in the robot model using the addCollision function. To import a URDF robot model with .stl files for meshes, see the importrobot function.

Output Arguments

collapse all

Axes graphic handle, returned as an Axes object. This object contains the properties of the figure that the robot is plotted onto.


Your robot model has visual components associated with it. Each rigidBody object contains a coordinate frame that is displayed as the body frame. Each body also can have visual meshes associated with them. By default, both of these components are displayed automatically. You can inspect or modify the visual components of the rigid body tree display. Click body frames or visual meshes to highlight them in yellow and see the associated body name, index, and joint type. Right-click to toggle visibility of individual components.

  • Body Frames: Individual body frames are displayed as a 3-axis coordinate frame. Fixed frames are pink frames. Movable joint types are displayed as RGB axes. You can click a body frame to see the axis of motion. Prismatic joints show a yellow arrow in the direction of the axis of motion and, revolute joints show a circular arrow around the rotation axis.

  • Visual Meshes: Individual visual geometries are specified using addVisual or by using the importrobot to import a robot model with .stl files specified. By right-clicking individual bodies in a figure, you can turn off their meshes or specify the Visuals name-value pair to hide all visual geometries.

Introduced in R2016b