Main Content

importrobot

Import rigid body tree model from URDF, SDF file, text, or Simscape Multibody model

Description

URDF or SDF Import

example

robot = importrobot(filename) returns a rigidBodyTree object by parsing the Unified Robot Description Format (URDF) or Simulation Description Format (SDF) file specified by filename.

example

robot = importrobot(URDFtext) parses the URDF text. Specify URDFtext as a string scalar or character vector.

robot = importrobot(SDFtext) parses the SDF text. Specify SDFtext as a string scalar or character vector.

robot = importrobot(___,format) explicitly specifies the type of the robot description in addition to any combination of input arguments from previous syntaxes. If the format of the text file does not match the format specified in the format argument, the function returns an error.

robot = importrobot(___,Name,Value) specifies options using one or more name-value pair arguments in addition to any combination of input arguments from previous syntaxes. Use the URDF or SDF Import name-value pairs to import a model from URDF, SDF file, or text.

Simscape Multibody Model Import

[robot,importInfo] = importrobot(model) imports a Simscape™ Multibody™ model and returns an equivalent rigidBodyTree object and information about the import in importInfo. Only fixed, prismatic, and revolute joints are supported in the output rigidBodyTree object.

[robot,importInfo] = importrobot(___,Name,Value) 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.

Examples

collapse all

Import a URDF file as a rigidBodyTree object.

robot = importrobot('iiwa14.urdf')
robot = 
  rigidBodyTree with properties:

     NumBodies: 10
        Bodies: {1x10 cell}
          Base: [1x1 rigidBody]
     BodyNames: {1x10 cell}
      BaseName: 'world'
       Gravity: [0 0 0]
    DataFormat: 'struct'

show(robot)

Figure contains an axes object. The axes object contains 29 objects of type patch, line. These objects represent world, 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, iiwa_link_0_mesh, iiwa_link_1_mesh, iiwa_link_2_mesh, iiwa_link_3_mesh, iiwa_link_4_mesh, iiwa_link_5_mesh, iiwa_link_6_mesh, iiwa_link_7_mesh.

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'

  Show all properties

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'

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.

show(robot,'visuals','on','collision','off');

Figure contains an axes object. The axes object contains 29 objects of type patch, line. These objects represent world, 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, iiwa_link_0_mesh, iiwa_link_1_mesh, iiwa_link_2_mesh, iiwa_link_3_mesh, iiwa_link_4_mesh, iiwa_link_5_mesh, iiwa_link_6_mesh, iiwa_link_7_mesh.

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','collision','on'); 

Figure contains an axes object. The axes object contains 29 objects of type patch, line. These objects represent world, 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, iiwa_link_0_mesh, iiwa_link_1_mesh, iiwa_link_2_mesh, iiwa_link_3_mesh, iiwa_link_4_mesh, iiwa_link_5_mesh, iiwa_link_6_mesh, iiwa_link_7_mesh, iiwa_link_0_coll_mesh, iiwa_link_1_coll_mesh, iiwa_link_2_coll_mesh, iiwa_link_3_coll_mesh, iiwa_link_4_coll_mesh, iiwa_link_5_coll_mesh, iiwa_link_6_coll_mesh, iiwa_link_7_coll_mesh.

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: {1x21 cell}
          Base: [1x1 rigidBody]
     BodyNames: {1x21 cell}
      BaseName: 'Base'
       Gravity: [0 0 -9.8066]
    DataFormat: 'struct'

importInfo = 
  rigidBodyTreeImportInfo with properties:

        SourceModelName: 'example_smhumanoidrobot'
          RigidBodyTree: [1x1 rigidBodyTree]
    BlockConversionInfo: [1x1 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)   
--------------------

Input Arguments

collapse all

Name of the URDF or SDF file, specified as a string scalar or character vector. This file must be a valid URDF robot description or SDF model description.

Included Robot Models with Mesh Data

Robot ModelDescription
"iiwa7.urdf"

KUKA LBR iiwa 7 R800 7-axis robot

"iiwa14.urdf"

URDF 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

To download the mesh data for the included robot models without the mesh data, install Robotics System Toolbox™ Robot Library Data support package. See Get and Manage Add-Ons.

Included Robot Models without Mesh Data

Robot ModelDescription
"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

"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

"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

"universalUR3.urdf"

Universal Robots UR3 6-axis robot

"universalUR5.urdf"

Universal Robots UR5 6-axis robot

"universalUR10.urdf"

Universal Robots UR10 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.sdf"

Data Types: char | string

URDF robot text, specified as a string scalar or character vector.

Example: "<?xml version="1.0" ?><robot name="min"><link name="L0"/></robot>"

Example: "robot_file.txt","urdf"

Data Types: char | string

SDF model text, specified as a string scalar or character vector.

Example: "<?xml version="1.0" ?><sdf version="1.6"><model name="min"><link name="L0"/></model></sdf>"

Example: "robot_file.txt","sdf"

Data Types: char | string

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","sdf"

Data Types: char | string

Simscape Multibody model, specified as a model handle, string scalar, or character vector.

Data Types: char | string

Name-Value 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: "MeshPath",{"../arm_meshes","../body_meshes"}
URDF or SDF Import

collapse all

Relative search paths for mesh files, specified as a string scalar, character vector, or cell array of string scalars or character vectors. Mesh files must still be specified inside the URDF or SDF file, but MeshPath defines the relative paths for these specified files.

Data Types: char | string | cell

Input/output data format for the kinematics and dynamics functions of the robot model, specified as the comma-separated pair consisting of 'DataFormat' and "struct", "row", or "column". To use dynamics functions, you must specify either "row" or "column". This name-value pair sets the DataFormat property of the rigidBodyTree robot model.

Data Types: char | string

Select a model from the SDF file or text that contain multiple models, specified as a string scalar or character vector.

Note

This name-value pair only applies to the SDF model and text.

Data Types: char | string

Simscape Multibody Model Import

collapse all

Indicates whether to break closed chains in the given model input, specified as "error" or "remove-joints". If you specify "remove-joints", the resulting robot output has chain closure joints removed. Otherwise, the function throws an error.

Data Types: char | string

Indicates whether to convert unsupported joints to fixed joints in the given model input, specified as "error" or "convert-to-fixed". If you specify "convert-to-fixed", the resulting robot output has any unsupported joints converted to fixed joints. Only fixed, prismatic, and revolute joints are supported in the output rigidBodyTree object. Otherwise, if the model contains unsupported joints, the function throws an error.

Data Types: char | string

Indicates whether to remove constraint blocks in the given model input, specified as "error" or "remove". If you specify "remove", the resulting robot output has the constraints removed. Otherwise, if the model contains constraint blocks, the function throws an error.

Data Types: char | string

Indicates whether to remove variable inertia blocks in the given model input, specified as "error" or "remove". If you specify "remove", the resulting robot output has the variable inertias removed. Otherwise, if the model contains variable inertia blocks, the function throws an error.

Data Types: char | string

Input/output data format for the kinematics and dynamics functions of the robot model, specified as the comma-separated pair consisting of 'DataFormat' and "struct", "row", or "column". To use dynamics functions, you must specify either "row" or "column". This name-value pair sets the DataFormat property of the rigidBodyTree robot model.

Data Types: char | string

Output Arguments

collapse all

Robot model, returned as a rigidBodyTree object.

Note

If the gravity is not specified in the URDF file, the default Gravity property is set to [0 0 0]. Simscape Multibody uses a default of [0 0 -9.80665]m/s2 when using smimport to import a URDF.

Object for storing import information, returned as a rigidBodyTreeImportInfo object. This object contains the relationship between the input model and the resulting robot output.

Use showdetails to list all the import info for each body in the robot. Links to display the rigid body info, their corresponding blocks in the model, and highlighting specific blocks in the model are output to the command window.

Use bodyInfo, bodyInfoFromBlock, or bodyInfoFromJoint to get information about specific components in either the robot output or the model input.

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 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 MeshPath

    • Current folder

    • MATLAB® path

    • The folder containing the URDF or SDF file

    • One level above the folder containing the URDF or SDF file

  • The file name from the mesh path in the URDF or SDF file is appended to the MeshPath input argument.

If the mesh file is still not found, the parser ignores the mesh file and returns a rigidBodyTree object without visual.

Introduced in R2017a