show
Show robot model in figure
Description
show(
uses
the joint positions specified in robot
,configuration
)configuration
to
show the robot body frames.
show(___,
specifies options
using one or more name-value pair arguments in addition to any combination of input
arguments from previous syntaxes. For example, Name=Value
)Frames="off"
hides
the rigid body frames in the figure.
returns
the axes handle the robot is plotted on.ax
= show(___)
Examples
Display Robot Model with Visual Geometries
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 corresponding bodies.
Use the show
function to display the visual and collision 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.
show(robot,Visuals="on",Collisions="off");
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(robot,Visuals="off",Collisions="on");
Visualize Robot Configurations
Show different configurations of a robot created using a rigidBodyTree
model. Use the homeConfiguration
or randomConfiguration
functions to generate the structure that defines all the joint positions.
Load a FANUC LR Mate 200ib from the Robotics System Toolbox™ loadrobot
. It is returned as a rigidBodyTree
object.
robot = loadrobot("fanucLRMate200ib");
showdetails(robot)
-------------------- Robot: (9 bodies) Idx Body Name Joint Name Joint Type Parent Name(Idx) Children Name(s) --- --------- ---------- ---------- ---------------- ---------------- 1 base base_link-base fixed base_link(0) 2 link_1 joint_1 revolute base_link(0) link_2(3) 3 link_2 joint_2 revolute link_1(2) link_3(4) 4 link_3 joint_3 revolute link_2(3) link_4(5) 5 link_4 joint_4 revolute link_3(4) link_5(6) 6 link_5 joint_5 revolute link_4(5) link_6(7) 7 link_6 joint_6 revolute link_5(6) flange(8) tool0(9) 8 flange joint_6-flange fixed link_6(7) 9 tool0 link_6-tool0 fixed link_6(7) --------------------
Create a structure for the home configuration of the robot. The structure has joint names and positions for each body on the robot model.
config = homeConfiguration(robot)
config=1×6 struct array with fields:
JointName
JointPosition
Show the home configuration using show
. You do not need to specify a configuration input.
show(robot);
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; show(robot,config);
Create random configurations and show them.
show(robot,randomConfiguration(robot));
Build Manipulator Robot Using Denavit-Hartenberg Parameters
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 [1]. The Puma robot is a serial chain manipulator. The DH parameters are relative to the previous row 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:
Create a
rigidBody
object and give it a unique name.Create a
rigidBodyJoint
object and give it a unique name.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.Call
addBody
to attach the first body joint to the base frame of the robot.
body1 = rigidBody('body1'); jnt1 = rigidBodyJoint('jnt1','revolute'); setFixedTransform(jnt1,dhparams(1,:),'dh'); body1.Joint = jnt1; addBody(robot,body1,'base')
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'); setFixedTransform(jnt2,dhparams(2,:),'dh'); setFixedTransform(jnt3,dhparams(3,:),'dh'); setFixedTransform(jnt4,dhparams(4,:),'dh'); setFixedTransform(jnt5,dhparams(5,:),'dh'); setFixedTransform(jnt6,dhparams(6,:),'dh'); body2.Joint = jnt2; body3.Joint = jnt3; body4.Joint = jnt4; body5.Joint = jnt5; body6.Joint = jnt6; addBody(robot,body2,'body1') addBody(robot,body3,'body2') addBody(robot,body4,'body3') addBody(robot,body5,'body4') addBody(robot,body6,'body5')
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.
showdetails(robot)
-------------------- 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) --------------------
show(robot);
axis([-0.5,0.5,-0.5,0.5,-0.5,0.5])
axis off
References
[1] Corke, P. I., and B. Armstrong-Helouvry. “A Search for Consensus among Model Parameters Reported for the PUMA 560 Robot.” Proceedings of the 1994 IEEE International Conference on Robotics and Automation, IEEE Computer. Soc. Press, 1994, pp. 1608–13. DOI.org (Crossref), doi:10.1109/ROBOT.1994.351360.
Add Collision Meshes and Check Collisions for Manipulator Robot Arm
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 clearCollision(robot.Bodies{i}) end show(robot,Collisions="on",Visuals="off");
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. else addCollision(robot.Bodies{i},collisionObj) end end show(robot,Collisions="on",Visuals="off");
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.
figure rng(0) % Set random seed for repeatability. for i = 1:20 config = randomConfiguration(robot); isColliding = checkCollision(robot,config,SkippedSelfCollisions="parent"); if isColliding show(robot,config,Collisions="on",Visuals="off"); title("Collision Detected") else % Skip non-collisions. end end
Input Arguments
robot
— Robot model
rigidBodyTree
object
Robot model, specified as a rigidBodyTree
object.
configuration
— Robot configuration
vector | structure
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 robot
to either "row"
or "column"
.
Name-Value Arguments
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: Frames="off"
hides the rigid body frames in the
figure.
Parent
— Parent of axes
Axes
object
Parent of axes, specified as an Axes
object in which to
draw the robot. By default, the robot is plotted in the active
axes.
PreservePlot
— Option to preserve robot plot
true
or
1
(default) | false
or 0
Option to preserve robot plot, specified as a logical
1
(true
) or
0
(false
). When you specify
PreservePlot
as true
, you
must also use hold
on
so that show
does not
overwrite previous rigid body tree patches in the axes that were
displayed by calling show
. When you specify
PreservePlot
as false
, the
show
overwrites previous plots of the
rigid body tree in the same axes regardless of the current
hold
value.
Note
If PreservePlot
is true
,
then the FastUpdate
argument must be
false
.
Data Types: logical
Frames
— Display body frames
"on"
(default) | "off"
Display body frames, specified as either "on"
or
"off"
. These frames are the coordinate frames of
individual bodies on the rigid body tree.
Data Types: char
| string
Visuals
— Display visual geometries
"on"
(default) | "off"
Display visual geometries, specified as either "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.
Data Types: char
| string
Collisions
— Display collision geometries
"off"
(default) | "on"
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.
Data Types: char
| string
Position
— Position of robot
[0 0 0 0]
(default) | four-element vector
Position of the robot, specified as the comma-separated pair
consisting of "Position"
and a four-element vector of
the form [x
y
z
yaw]. The x, y,
and z elements specify the position in meters, and
yaw specifies the yaw angle in radians.
Data Types: single
| double
FastUpdate
— Fast updates to existing plot
false
or
0
(default) | true
or 1
Fast updates to existing plot, specified as a logical
0
(false)
or 1
(true)
. You must use the show
object function to initially display the robot model before you can
specify it with this argument.
Note
If FastUpdate
is true
, then
the PreservePlot
argument must be
false
.
Data Types: logical
Output Arguments
ax
— Axes graphic handle
Axes
object
Axes graphic handle, returned as an Axes
object. This object
contains the properties of the figure that the robot is plotted onto.
Tips
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 theimportrobot
to import a robot model with either a specified.stl
or.dae
file. By right-clicking individual bodies in a figure, you can turn off their meshes or specify theVisuals
name-value pair to hide all visual geometries.
Version History
Introduced in R2016b
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)