Main Content

importrobot

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

Description

URDF, Xacro, or SDF Import

example

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

example

robot = importrobot(text) parses robot description from URDF, Xacro, or SDF text.

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.

example

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. For example, 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

[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, revolute joints, and floating 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: {[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

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

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

collapse all

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 ModelMesh VisualizationDescription
"iiwa7.urdf"

Figure contains the mesh of KUKA LBR iiwa 7 R800 7-axis robot

KUKA LBR iiwa 7 R800 7-axis robot

"iiwa14.urdf"

Figure contains the mesh of URDF version of KUKA LBR iiwa 14 R820 7-axis robot

URDF version of KUKA LBR iiwa 14 R820 7-axis robot

"iiwa14.xacro"

Figure contains the mesh of Xacro version of KUKA LBR iiwa 14 R820 7-axis robot

Xacro version of KUKA LBR iiwa 14 R820 7-axis robot

"iiwa14.sdf"

Figure contains the mesh of SDF version of KUKA LBR iiwa 14 R820 7-axis robot

SDF version of KUKA LBR iiwa 14 R820 7-axis robot

"sawyer.urdf"

Figure contains the mesh of Rethink Robotics Sawyer 7-axis robot

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 ModelMesh VisualizationDescription
"abbIrb120.urdf"

Figure contains the mesh of ABB IRB 120 6-axis robot

ABB IRB 120 6-axis robot

"abbIrb120T.urdf"

Figure contains the mesh of ABB IRB 120T 6-axis robot

ABB IRB 120T 6-axis robot

"abbIrb1600.urdf"

Figure contains the mesh of ABB IRB 1600 6-axis robot

ABB IRB 1600 6-axis robot

"abbYuMi.urdf"

Figure contains the mesh of ABB YuMi 2-armed robot

ABB YuMi 2-armed robot

"amrPioneer3AT.urdf"

Figure contains the mesh of Adept MobileRobots Pioneer 3-AT mobile robot

Adept MobileRobots Pioneer 3-AT mobile robot

"amrPioneer3DX.urdf"

Figure contains the mesh of Adept MobileRobots Pioneer 3-DX mobile robot

Adept MobileRobots Pioneer 3-DX mobile robot

"amrPioneerLX.urdf"

Figure contains the mesh of Adept MobileRobots Pioneer LX mobile robot

Adept MobileRobots Pioneer LX mobile robot

"atlas.urdf"

Figure contains the mesh of Boston Dynamics ATLAS Humanoid robot

Boston Dynamics ATLAS® Humanoid robot

"clearpathHusky.urdf"

Figure contains the mesh of Clearpath Robotics Husky mobile robot

Clearpath Robotics Husky mobile robot

"clearpathJackal.urdf"

Figure contains the mesh of Clearpath Robotics Jackal mobile robot

Clearpath Robotics Jackal mobile robot

"clearpathTurtleBot2.urdf"

Figure contains the mesh of Clearpath Robotics TurtleBot 2 mobile robot

Clearpath Robotics TurtleBot 2 mobile robot

"fanucLRMate200ib.urdf"

Figure contains the mesh of FANUC LR Mate 200iB 6-axis robot

FANUC LR Mate 200iB 6-axis robot

"fanucM16ib.urdf"

Figure contains the mesh of FANUC M-16iB 6-axis robot

FANUC M-16iB 6-axis robot

"frankaEmikaPanda.urdf"

Figure contains the mesh of Franka Emika Panda 7-axis robot

Franka Emika Panda 7-axis robot

"kinovaGen3.urdf"

Figure contains the mesh of version 1 of KINOVA Gen3 7-axis robot

Version 1 of Kinova®Gen3 7-axis robot

"kinovaGen3V12.urdf"

Figure contains the mesh of version 2 of KINOVA Gen3 7-axis robot

Version 2 of Kinova Gen3 7-axis robot

"kinovaJacoJ2N6S200.urdf"

Figure contains the mesh of KINOVA JACO 2-fingered 6 DOF robot with non-spherical wrist

Kinova JACO® 2-fingered 6 DOF robot with non-spherical wrist

"kinovaJacoJ2N6S300.urdf"

Figure contains the mesh of KINOVA JACO 3-fingered 6 DOF robot with non-spherical wrist

Kinova JACO® 3-fingered 6 DOF robot with non-spherical wrist

"kinovaJacoJ2N7S300.urdf"

Figure contains the mesh of KINOVA JACO 3-fingered 7 DOF robot with non-spherical wrist

Kinova JACO® 3-fingered 7 DOF robot with non-spherical wrist

"kinovaJacoJ2S6S300.urdf"

Figure contains the mesh of KINOVA JACO 3-fingered 6 DOF robot with spherical wrist

Kinova JACO® 3-fingered 6 DOF robot with spherical wrist

"kinovaJacoJ2S7S300.urdf"

Figure contains the mesh of KINOVA JACO 3-fingered 7 DOF robot with spherical wrist

Kinova JACO® 3-fingered 7 DOF robot with spherical wrist

"kinovaJacoTwoArmExample.urdf"

Figure contains the mesh of Two KINOVA JACO 3-fingered 6 DOF robots with non-spherical wrist

Two Kinova JACO® 3-fingered 6 DOF robots with non-spherical wrist

"kinovaMicoM1N4S200.urdf"

Figure contains the mesh of KINOVA MICO 2-fingered 4 DOF robot

Kinova MICO® 2-fingered 4 DOF robot

"kinovaMicoM1N6S200.urdf"

Figure contains the mesh of KINOVA MICO 2-fingered 6 DOF robot

Kinova MICO® 2-fingered 6 DOF robot

"kinovaMicoM1N6S300.urdf"

Figure contains the mesh of KINOVA MICO 3-fingered 6 DOF robot

Kinova MICO® 3-fingered 6 DOF robot

"kinovaMovo.urdf"

Figure contains the mesh of KINOVA MOVO 2-armed mobile robot

Kinova MOVO® 2-armed mobile robot

"kukaIiwa7.urdf"

Figure contains the mesh of KUKA LBR iiwa 7 R800 7-axis robot

KUKA LBR iiwa 7 R800 7-axis robot

"kukaIiwa14.urdf"

Figure contains the mesh of KUKA LBR iiwa 14 R820 7-axis robot

KUKA LBR iiwa 14 R820 7-axis robot

"meca500r3.urdf"

Figure contains the mesh of Mecademic Meca500 R3 6-axis robot

Mecademic Meca500 R3 6-axis robot

"omronEcobra600.urdf"

Figure contains the mesh of Omron eCobra 600 4-axis SCARA robot

Omron eCobra 600 4-axis SCARA robot

"puma560.urdf"

Figure contains the mesh of PUMA 560 6-axis robot

PUMA 560 6-axis robot

"quanserQArm.urdf"

Figure contains the mesh of Quanser QArm 4 DOF robot

Quanser QArm 4 DOF robot

"quanserQBot2e.urdf"

Figure contains the mesh of Quanser QBot 2e mobile robot

Quanser QBot 2e mobile robot

"quanserQCar.urdf"

Figure contains the mesh of Quanser QCar mobile robot

Quanser QCar mobile robot

"rethinkBaxter.urdf"

Figure contains the mesh of Rethink Robotics Baxter 2-armed robot

Rethink Robotics Baxter 2-armed robot

"rethinkSawyer.urdf"

Figure contains the mesh of Rethink Robotics Sawyer 7-axis robot

Rethink Robotics Sawyer 7-axis robot

"robotiq2F85.urdf"

Figure contains the mesh of Robotiq 2F-85 2-finger gripper

Robotiq 2F-85 2-finger gripper

The gripper can be used with the following list of manipulators:

  • Universal Robots UR3

  • Universal Robots UR3e

  • Universal Robots UR5

  • Universal Robots UR5e

  • Universal Robots UR10

  • Universal Robots UR10e

  • Universal Robots UR16e

  • Kinova Gen3 (versions 1 and 2)

"robotisOP2.urdf"

Figure contains the mesh of ROBOTIS OP2 Humanoid robot

ROBOTIS OP2 Humanoid robot

"robotisOpenManipulator.urdf"

Figure contains the mesh of ROBOTIS OpenMANIPULATOR 4-axis robot with gripper

ROBOTIS OpenMANIPULATOR 4-axis robot with gripper

"robotisTurtleBot3Burger.urdf"

Figure contains the mesh of ROBOTIS TurtleBot 3 Burger robot

ROBOTIS TurtleBot 3 Burger robot

"robotisTurtleBot3Waffle.urdf"

Figure contains the mesh of ROBOTIS TurtleBot 3 Waffle robot

ROBOTIS TurtleBot 3 Waffle robot

"robotisTurtleBot3WaffleForOpenManipulator.urdf"

Figure contains the mesh of ROBOTIS TurtleBot 3 Waffle robot for OpenMANIPULATOR

ROBOTIS TurtleBot 3 Waffle robot with OpenMANIPULATOR

"robotisTurtleBot3WafflePi.urdf"

Figure contains the mesh of ROBOTIS TurtleBot 3 Waffle Pi robot

ROBOTIS TurtleBot 3 Waffle Pi robot

"robotisTurtleBot3WafflePiForOpenManipulator.urdf"

Figure contains the mesh of ROBOTIS TurtleBot 3 Waffle Pi robot for OpenMANIPULATOR

ROBOTIS TurtleBot 3 Waffle Pi robot with OpenMANIPULATOR

"techmanTM5-700"

Figure contains the mesh of Techman TM5-700 6-axis robot with Camera

Techman TM5-700 6-axis robot with Camera

"techmanTM5x-700"

Figure contains the mesh of Techman TM5X-700 6-axis robot without Camera

Techman TM5X-700 6-axis robot without Camera

"techmanTM5-900"

Figure contains the mesh of Techman TM5-900 6-axis robot with Camera

Techman TM5-900 6-axis robot with Camera

"techmanTM5x-900"

Figure contains the mesh of Techman TM5X-900 6-axis robot without Camera

Techman TM5X-900 6-axis robot without Camera

"techmanTM12"

Figure contains the mesh of Techman TM12 6-axis robot with Camera

Techman TM12 6-axis robot with Camera

"techmanTM12x"

Figure contains the mesh of Techman TM12X 6-axis robot without Camera

Techman TM12X 6-axis robot without Camera

"techmanTM14"

Figure contains the mesh of Techman TM14 6-axis robot with Camera

Techman TM14 6-axis robot with Camera

"techmanTM14x"

Figure contains the mesh of Techman TM14X 6-axis robot without Camera

Techman TM14X 6-axis robot without Camera

"universalUR3.urdf"

Figure contains the mesh of Universal Robots UR3 6-axis robot

Universal Robots UR3 6-axis robot

"universalUR3e.urdf"

Figure contains the mesh of Universal Robots UR3e 6-axis robot

Universal Robots UR3e 6-axis robot

"universalUR5.urdf"

Figure contains the mesh of Universal Robots UR5 6-axis robot

Universal Robots UR5 6-axis robot

"universalUR5e.urdf"

Figure contains the mesh of Universal Robots UR5e 6-axis robot

Universal Robots UR5e 6-axis robot

"universalUR10.urdf"

Figure contains the mesh of Universal Robots UR10 6-axis robot

Universal Robots UR10 6-axis robot

"universalUR10e.urdf"

Figure contains the mesh of Universal Robots UR10e 6-axis robot

Universal Robots UR10e 6-axis robot

"universalUR16e.urdf"

Figure contains the mesh of Universal Robots UR16e 6-axis robot

Universal Robots UR16e 6-axis robot

"valkyrie.urdf"

Figure contains the mesh of NASA Valkyrie Humanoid robot

NASA Valkyrie Humanoid robot

"willowgaragePR2.urdf"

Figure contains the mesh of Willow Garage PR2 mobile robot

Willow Garage PR2 mobile robot

"yaskawaMotomanMH5.urdf"

Figure contains the mesh of Yaskawa Motoman MH5 6-axis robot

Yaskawa Motoman MH5 6-axis robot

Example: "robot_file.urdf"

Example: "robot_file.xacro"

Example: "robot_file.sdf"

Data Types: char | string

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

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

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

URDF, Xacro, 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, Xacro, or SDF file, but MeshPath defines the relative paths for these specified files.

Dependencies

To use this name-value argument, you must specify either the filename or the text argument as a URDF, Xacro, or SDF file.

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.

Dependencies

To use this name-value argument, you must specify either the filename or the text argument as an SDF file or SDF text description, respectively.

Data Types: char | string

Maximum number of bodies allowed in imported robot during code generation, specified as an integer. Use MaxNumBodies to add rigid bodies to the imported tree inside a function that supports code generation. The number of additional bodies that can be added is the difference between MaxNumBodies and the number of bodies in the imported tree, rigidBodyTree.NumBodies.

Note

This name-value pair is only necessary for code generation workflows.

Decomposition of the collision meshes of the robot after import, specified as a logical 0 (false), logical 1 (true), or vhacdOptions object.

  • falseimportrobot does not decompose the robot collision meshes after import.

  • trueimportrobot uses the collisionVHACD function with default decomposition options to decompose the robot collision meshes specified in the URDF file or text.

  • vhacdOptions object — importrobot uses the collisionVHACD function with specified decomposition options to decompose the collision meshes specified in the URDF file or text. You must set the Type property of the vhacdOptions object to "RigidBodyTree".

Simscape Multibody Model Import

collapse all

Closed chain breaking, specified as "error" or "remove-joints".

  • "error"importrobot returns an error when the source model contains closed chains.

  • "remove-joints"importrobot removes joints from the robot model to break closed chains. You can see the removed joints in the BlockConversionInfo property of the importInfo output argument.

Data Types: char | string

Unsupported to fixed joint conversion, specified as "error" or "convert-to-fixed".

  • "error"importrobot returns an error when the source model contains unsupported joints.

  • "convert-to-fixed"importrobot converts unsupported joints in the source model to fixed joints. You can see the converted joints in the BlockConversionInfo property of the importInfo output argument.

An unsupported joint is any joint other than a fixed, prismatic, or revolute joint.

Data Types: char | string

Constraint block removal, specified as "error" or "remove".

  • "error"importrobot returns an error when the source model contains restraint blocks.

  • "remove"importrobot removes contributions from constraint blocks present in the source model. You can see the removed constraints in the BlockConversionInfo property of the importInfo output argument.

Data Types: char | string

Variable inertia block removal, specified as "error" or "remove".

  • "error"importrobot returns an error when the source model contains variable inertia blocks.

  • "remove"importrobot removes contributions from variable inertia blocks present in the source model. You can see the removed variable inertias in the BlockConversionInfo property of the importInfo output argument.

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, bodyInfoFromBlocks, or bodyInfoFromJoint to get information about specific components in either the robot output or the model input.

Limitations

  • importrobot does 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 MeshPath

    • Current 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 MeshPath input 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 R2017a

expand all