importrobot
Import rigid body tree model from URDF, Xacro, SDF file, text, or Simscape Multibody model
Syntax
Description
URDF, Xacro, or SDF Import
robot = importrobot(filename)rigidBodyTree object by parsing
the Unified Robot Description Format (URDF), XML Macros (Xacro), or Simulation
Description Format (SDF) file specified by filename.
robot = importrobot(___,Name,Value)importrobot("iiwa14.urdf",CollisionDecomposition=true)
imports a KUKA LBR iiwa 14 robot and decomposes the collision meshes of the
robot using voxelized hierarchical approximate convex decomposition
(V-HACD).
Use the URDF, Xacro, or SDF Import name-value pairs to import a model from URDF, Xacro, or SDF file, or text.
Simscape Multibody Model Import
[
imports a Simscape™
Multibody™ model and returns an equivalent robot,importInfo] = importrobot(model)rigidBodyTree object and
information about the import in importInfo. Only fixed,
prismatic, and revolute joints are supported in the output
rigidBodyTree object.
[
specifies options using one or more name-value pair arguments in addition to the
Simscape
Multibody model from the previous syntax. Use the Simscape Multibody Model Import name-value pairs to
import a model that uses other joint types, constraint blocks, or variable
inertias.robot,importInfo] = importrobot(___,Name,Value)
Examples
Import Robot from URDF File
Import a URDF file as a rigidBodyTree object.
robot = importrobot('iiwa14.urdf')robot =
rigidBodyTree with properties:
NumBodies: 10
Bodies: {[1x1 rigidBody] [1x1 rigidBody] [1x1 rigidBody] [1x1 rigidBody] [1x1 rigidBody] [1x1 rigidBody] [1x1 rigidBody] [1x1 rigidBody] [1x1 rigidBody] [1x1 rigidBody]}
Base: [1x1 rigidBody]
BodyNames: {'iiwa_link_0' 'iiwa_link_1' 'iiwa_link_2' 'iiwa_link_3' 'iiwa_link_4' 'iiwa_link_5' 'iiwa_link_6' 'iiwa_link_7' 'iiwa_link_ee' 'iiwa_link_ee_kuka'}
BaseName: 'world'
Gravity: [0 0 0]
DataFormat: 'struct'
show(robot)
ans =
Axes (Primary) with properties:
XLim: [-1.5000 1.5000]
YLim: [-1.5000 1.5000]
XScale: 'linear'
YScale: 'linear'
GridLineStyle: '-'
Position: [0.1300 0.1100 0.7750 0.8150]
Units: 'normalized'
Use GET to show all properties
Import Robot from URDF Character Vector
Specify the URDF character vector. This character vector is a minimalist description for creating a valid robot model.
URDFtext = '<?xml version="1.0" ?><robot name="min"><link name="L0"/></robot>';Import the robot model. The description creates a rigidBodyTree object that has only a robot base link named 'L0'.
robot = importrobot(URDFtext)
robot =
rigidBodyTree with properties:
NumBodies: 0
Bodies: {1x0 cell}
Base: [1x1 rigidBody]
BodyNames: {1x0 cell}
BaseName: 'L0'
Gravity: [0 0 0]
DataFormat: 'struct'
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");
Import Simscape™ Multibody™ model to RigidBodyTree Object
Import an existing Simscape™ Multibody™ robot model into the Robotics System Toolbox™ as a rigidBodyTree object.
Open the Simscape™ Multibody™ model. This is a model for a humanoid robot.
open_system('example_smhumanoidrobot.slx')Import the model.
[robot,importInfo] = importrobot(gcs)
robot =
rigidBodyTree with properties:
NumBodies: 21
Bodies: {1×21 cell}
Base: [1×1 rigidBody]
BodyNames: {'Body01' 'Body02' 'Body03' 'Body04' 'Body05' 'Body06' 'Body07' 'Body08' 'Body09' 'Body10' 'Body11' 'Body12' 'Body13' 'Body14' 'Body15' 'Body16' 'Body17' 'Body18' 'Body19' 'Body20' 'Body21'}
BaseName: 'Base'
Gravity: [0 0 -9.8066]
DataFormat: 'struct'
importInfo =
rigidBodyTreeImportInfo with properties:
SourceModelName: 'example_smhumanoidrobot'
RigidBodyTree: [1×1 rigidBodyTree]
BlockConversionInfo: [1×1 struct]
Display details about the created rigidBodyTree object.
showdetails(importInfo)
-------------------- Robot: (21 bodies) Idx Body Name Simulink Source Blocks Joint Name Simulink Source Blocks Joint Type Parent Name(Idx) Children Name(s) --- --------- ---------------------- ---------- ---------------------- ---------- ---------------- ---------------- 1 Body01 Info | List | Highlight Joint01 Info | List | Highlight revolute Base(0) Body02(2) 2 Body02 Info | List | Highlight Joint02 Info | List | Highlight revolute Body01(1) Body03(3) 3 Body03 Info | List | Highlight Joint03 Info | List | Highlight revolute Body02(2) Body04(4) 4 Body04 Info | List | Highlight Joint04 Info | List | Highlight revolute Body03(3) 5 Body05 Info | List | Highlight Joint05 Info | List | Highlight revolute Base(0) Body06(6) 6 Body06 Info | List | Highlight Joint06 Info | List | Highlight revolute Body05(5) Body07(7) 7 Body07 Info | List | Highlight Joint07 Info | List | Highlight revolute Body06(6) Body08(8) 8 Body08 Info | List | Highlight Joint08 Info | List | Highlight revolute Body07(7) 9 Body09 Info | List | Highlight Joint09 Info | List | Highlight revolute Base(0) Body10(10) 10 Body10 Info | List | Highlight Joint10 Info | List | Highlight revolute Body09(9) Body11(11) 11 Body11 Info | List | Highlight Joint11 Info | List | Highlight revolute Body10(10) Body12(12) 12 Body12 Info | List | Highlight Joint12 Info | List | Highlight revolute Body11(11) 13 Body13 Info | List | Highlight Joint13 Info | List | Highlight revolute Base(0) Body14(14) 14 Body14 Info | List | Highlight Joint14 Info | List | Highlight revolute Body13(13) Body15(15) 15 Body15 Info | List | Highlight Joint15 Info | List | Highlight revolute Body14(14) Body16(16) 16 Body16 Info | List | Highlight Joint16 Info | List | Highlight revolute Body15(15) 17 Body17 Info | List | Highlight Joint17 Info | List | Highlight revolute Base(0) Body18(18) 18 Body18 Info | List | Highlight Joint18 Info | List | Highlight revolute Body17(17) Body19(19) 19 Body19 Info | List | Highlight Joint19 Info | List | Highlight fixed Body18(18) Body20(20) 20 Body20 Info | List | Highlight Joint20 Info | List | Highlight fixed Body19(19) 21 Body21 Info | List | Highlight Joint21 Info | List | Highlight fixed Base(0) --------------------
Decompose Collision Meshes of Imported Robot
Import a KUKA LBR iiwa 14 robot.
robot = importrobot("iiwa14.urdf");Display the robot with the default collision meshes.
t = tiledlayout(1,2); title(t,"KUKA iiwa 14") nexttile; show(robot,Visuals="off",Collisions="on"); title("Default Collision Meshes"); axis auto nexttile; show(robot); title("Visual Meshes"); axis auto
Import a robot but decompose the collision meshes using voxelized hierarchical approximate convex decomposition (V-HACD).
robotCollisionDecomp = importrobot("iiwa14.urdf",CollisionDecomposition=true);Display the robot with the updated collision meshes from decomposition.
figure show(robotCollisionDecomp,Visuals="off",Collisions="on"); title("Decomposition of Collision Meshes"); axis auto
By default the V-HACD solver decomposes the collision meshes of the robot. To decompose the visual meshes of the robot, import the robot with custom V-HACD solver options.
options = vhacdOptions("RigidBodyTree",SourceMesh="VisualGeometry"); robotVisualDecomp = importrobot("iiwa14.urdf",CollisionDecomposition=options);
Display the robot with the updated collision meshes from decomposition.
figure show(robotVisualDecomp,Visuals="off",Collisions="on"); title("Decomposition of Visual Meshes"); axis auto
Input Arguments
filename — Name of robot description file
string scalar | character vector
Name of the robot description file, specified as a string scalar or character vector. This file must be a valid URDF robot description, Xacro robot description, or SDF model description.
Included Robot Models with Mesh Data
| Robot Model | Mesh Visualization | Description |
|---|---|---|
"iiwa7.urdf" |
| KUKA LBR iiwa 7 R800 7-axis robot |
"iiwa14.urdf" |
| URDF version of KUKA LBR iiwa 14 R820 7-axis robot |
"iiwa14.xacro" |
| Xacro version of KUKA LBR iiwa 14 R820 7-axis robot |
"iiwa14.sdf" |
| SDF version of KUKA LBR iiwa 14 R820 7-axis robot |
"sawyer.urdf" |
| Rethink Robotics Sawyer 7-axis robot |
Note
To download the mesh data for the included robot models without the mesh data, see Install Robotics System Toolbox Robot Library Data Support Package.
Included Robot Models without Mesh Data
| Robot Model | Mesh Visualization | Description |
|---|---|---|
"abbIrb120.urdf" |
| ABB IRB 120 6-axis robot |
"abbIrb120T.urdf" |
| ABB IRB 120T 6-axis robot |
"abbIrb1600.urdf" |
| ABB IRB 1600 6-axis robot |
"abbYuMi.urdf" |
| ABB YuMi 2-armed robot |
"amrPioneer3AT.urdf" |
| Adept MobileRobots Pioneer 3-AT mobile robot |
"amrPioneer3DX.urdf" |
| Adept MobileRobots Pioneer 3-DX mobile robot |
"amrPioneerLX.urdf" |
| Adept MobileRobots Pioneer LX mobile robot |
"atlas.urdf" |
| Boston Dynamics ATLAS® Humanoid robot |
"clearpathHusky.urdf" |
| Clearpath Robotics Husky mobile robot |
"clearpathJackal.urdf" |
| Clearpath Robotics Jackal mobile robot |
"clearpathTurtleBot2.urdf" |
| Clearpath Robotics TurtleBot 2 mobile robot |
"fanucLRMate200ib.urdf" |
| FANUC LR Mate 200iB 6-axis robot |
"fanucM16ib.urdf" |
| FANUC M-16iB 6-axis robot |
"frankaEmikaPanda.urdf" |
| Franka Emika Panda 7-axis robot |
"kinovaGen3.urdf" |
| Version 1 of KINOVA® Gen3 7-axis robot |
"kinovaGen3V12.urdf" |
| Version 2 of KINOVA® Gen3 7-axis robot |
"kinovaJacoJ2N6S200.urdf" |
| KINOVA JACO® 2-fingered 6 DOF robot with non-spherical wrist |
"kinovaJacoJ2N6S300.urdf" |
| KINOVA JACO® 3-fingered 6 DOF robot with non-spherical wrist |
"kinovaJacoJ2N7S300.urdf" |
| KINOVA JACO® 3-fingered 7 DOF robot with non-spherical wrist |
"kinovaJacoJ2S6S300.urdf" |
| KINOVA JACO® 3-fingered 6 DOF robot with spherical wrist |
"kinovaJacoJ2S7S300.urdf" |
| KINOVA JACO® 3-fingered 7 DOF robot with spherical wrist |
"kinovaJacoTwoArmExample.urdf" |
| Two KINOVA JACO® 3-fingered 6 DOF robots with non-spherical wrist |
"kinovaMicoM1N4S200.urdf" |
| KINOVA MICO® 2-fingered 4 DOF robot |
"kinovaMicoM1N6S200.urdf" |
| KINOVA MICO® 2-fingered 6 DOF robot |
"kinovaMicoM1N6S300.urdf" |
| KINOVA MICO® 3-fingered 6 DOF robot |
"kinovaMovo.urdf" |
| KINOVA MOVO® 2-armed mobile robot |
"kukaIiwa7.urdf" |
| KUKA LBR iiwa 7 R800 7-axis robot |
"kukaIiwa14.urdf" |
| KUKA LBR iiwa 14 R820 7-axis robot |
"meca500r3.urdf" |
| Mecademic Meca500 R3 6-axis robot |
"omronEcobra600.urdf" |
| Omron eCobra 600 4-axis SCARA robot |
"puma560.urdf" |
| PUMA 560 6-axis robot |
"quanserQArm.urdf" |
| Quanser QArm 4 DOF robot |
"quanserQBot2e.urdf" |
| Quanser QBot 2e mobile robot |
"quanserQCar.urdf" |
| Quanser QCar mobile robot |
"rethinkBaxter.urdf" |
| Rethink Robotics Baxter 2-armed robot |
"rethinkSawyer.urdf" |
| Rethink Robotics Sawyer 7-axis robot |
"robotiq2F85.urdf" |
| Robotiq 2F-85 2-finger gripper The gripper can be used with the following list of manipulators:
|
"robotisOP2.urdf" |
| ROBOTIS OP2 Humanoid robot |
"robotisOpenManipulator.urdf" |
| ROBOTIS OpenMANIPULATOR 4-axis robot with gripper |
"robotisTurtleBot3Burger.urdf" |
| ROBOTIS TurtleBot 3 Burger robot |
"robotisTurtleBot3Waffle.urdf" |
| ROBOTIS TurtleBot 3 Waffle robot |
"robotisTurtleBot3WaffleForOpenManipulator.urdf" |
| ROBOTIS TurtleBot 3 Waffle robot with OpenMANIPULATOR |
"robotisTurtleBot3WafflePi.urdf" |
| ROBOTIS TurtleBot 3 Waffle Pi robot |
"robotisTurtleBot3WafflePiForOpenManipulator.urdf" |
| ROBOTIS TurtleBot 3 Waffle Pi robot with OpenMANIPULATOR |
"techmanTM5-700" |
| Techman TM5-700 6-axis robot with Camera |
"techmanTM5x-700" |
| Techman TM5X-700 6-axis robot without Camera |
"techmanTM5-900" |
| Techman TM5-900 6-axis robot with Camera |
"techmanTM5x-900" |
| Techman TM5X-900 6-axis robot without Camera |
"techmanTM12" |
| Techman TM12 6-axis robot with Camera |
"techmanTM12x" |
| Techman TM12X 6-axis robot without Camera |
"techmanTM14" |
| Techman TM14 6-axis robot with Camera |
"techmanTM14x" |
| Techman TM14X 6-axis robot without Camera |
"universalUR3.urdf" |
| Universal Robots UR3 6-axis robot |
"universalUR3e.urdf" |
| Universal Robots UR3e 6-axis robot |
"universalUR5.urdf" |
| Universal Robots UR5 6-axis robot |
"universalUR5e.urdf" |
| Universal Robots UR5e 6-axis robot |
"universalUR10.urdf" |
| Universal Robots UR10 6-axis robot |
"universalUR10e.urdf" |
| Universal Robots UR10e 6-axis robot |
"universalUR16e.urdf" |
| Universal Robots UR16e 6-axis robot |
"valkyrie.urdf" |
| NASA Valkyrie Humanoid robot |
"willowgaragePR2.urdf" |
| Willow Garage PR2 mobile robot |
"yaskawaMotomanMH5.urdf" |
| Yaskawa Motoman MH5 6-axis robot |
Example: "robot_file.urdf"
Example: "robot_file.xacro"
Example: "robot_file.sdf"
Data Types: char | string
text — Robot description text
string scalar | character vector
Robot description text, specified as a string scalar or character vector. The text must be a valid URDF robot description, Xacro robot description, or SDF model description.
Parse URDF Robot Description from text
Import robot model from URDF text.
% Specify URDF text as a character vector. text = ['<?xml version="1.0" ?>', ... '<robot name="min">', ... '<link name="L0"/>', ... '</robot>']; % Import the robot model from the URDF text. robot = importrobot(text);
Import robot model from a URDF text file.
% Specify URDF text as a character vector. text = ['<?xml version="1.0" ?>', ... '<robot name="min">', ... '<link name="L0"/>', ... '</robot>']; % Write the text to file. writelines(text,"URDF_robot.txt") % Import the robot model from the URDF text file. Specify the format of % the robot description text file. robot = importrobot("URDF_robot.txt","urdf");
Parse Xacro Robot Description from text
Import robot model from Xacro text.
% Specify Xacro text as a character vector. text = ['<?xml version="1.0" ?>', ... '<robot name="min" ', ... 'xmlns:xacro="http://www.ros.org/wiki/xacro">', ... '<link name="L0"/>', ... '</robot>']; % Import the robot model from the Xacro text. robot = importrobot(text);
Import robot model from a Xacro text file.
% Specify Xacro text as a character vector. text = ['<?xml version="1.0" ?>', ... '<robot name="min" ', ... 'xmlns:xacro="http://www.ros.org/wiki/xacro">', ... '<link name="L0"/>', ... '</robot>']; % Write the text to file. writelines(text,"Xacro_robot.txt") % Import the robot model from the Xacro text file. Specify the format of % the robot description text file. robot = importrobot("Xacro_robot.txt","xacro");
Parse SDF Model Description from text
Import robot model from SDF text.
% Specify SDF text as a character vector. text = ['<?xml version="1.0" ?>', ... '<sdf version="1.6">', ... '<model name="min">', ... '<link name="L0"/>', ... '</model>', ... '</sdf>']; % Import the robot model from the SDF text. robot = importrobot(text);
Import robot model from a SDF text file.
% Specify SDF text as a character vector. text = ['<?xml version="1.0" ?>', ... '<sdf version="1.6">', ... '<model name="min">', ... '<link name="L0"/>', ... '</model>', ... '</sdf>']; % Write the text to file. writelines(text,"SDF_robot.txt") % Import the robot model from the SDF text file. Specify the format of % the robot description text file. robot = importrobot("SDF_robot.txt","sdf");
Data Types: char | string
format — File format of robot description text file
"urdf" | "xacro" | "sdf"
File format of robot description text file, specified as a string scalar or character vector. Use this argument to specify explicitly the required format for the robot description file.
Example: "robot_file.txt","urdf"
Example: "robot_file.txt","xacro"
Example: "robot_file.txt","sdf"
Data Types: char | string
model — Simscape Multibody model
model handle | string scalar | character vector
Simscape Multibody model, specified as a model handle, string scalar, or character vector.
Data Types: char | string
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: "MeshPath",{"../arm_meshes","../body_meshes"}
Output Arguments
Limitations
importrobotdoes not support importing robot models from URDF files that contain the mimic tag.
Tips
When importing a robot model with visual meshes, the importrobot
function searches for the .stl or .dae files to
assign to each rigid body using these rules:
The function searches the raw mesh path for a specified rigid body from the URDF, Xacro, or SDF file. References to ROS packages have the
package:\\<pkg_name>removed.Absolute paths are checked directly with no modification.
Relative paths are checked using the following directories in order:
User-specified
MeshPathCurrent folder
MATLAB® path
The folder containing the URDF, Xacro, or SDF file
One level above the folder containing the URDF, Xacro, or SDF file
The file name from the mesh path in the URDF, Xacro, or SDF file is appended to the
MeshPathinput argument.
If the mesh file is still not found, the parser ignores the mesh file and returns a
rigidBodyTree object without
visual.
References
[1] Mammou, Khaled, et al. “Voxelized Hierarchical Approximate Convex Decomposition - V-HACD Version 4.” GitHub, October 24, 2022. https://github.com/kmammou/v-hacd.
Extended Capabilities
Version History
Introduced in R2017aSee Also
rigidBodyTree | rigidBodyTreeImportInfo | loadrobot | vhacdOptions
You can also select a web site from the following list:
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)