import rigid body tree model from urdf, xacro, sdf file, text, or simscape multibody model

syntax

robot = importrobot(filename)

robot = importrobot(text)

robot = importrobot(___,format)

robot = importrobot(___,name,value)

[robot,importinfo] = importrobot(model)

[robot,importinfo] = importrobot(___,name,value)

description

urdf, xacro, or sdf import

example

robot = importrobot(filename) returns a 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.

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

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'
  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 = '';

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 .

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

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

import simscape™ multibody™ model to `rigidbodytree` object

this example uses:

import an existing simscape™ multibody™ robot model into the robotics system toolbox™ as a 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: {'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: [1x1 rigidbodytree]
    blockconversioninfo: [1x1 struct]

display details about the created 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

`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 .

included robot models without mesh data

robot model	mesh visualization	description
`"abbirb120.urdf"`		abb 6-axis robot
`"abbirb120t.urdf"`		abb irb 120t 6-axis robot
`"abbirb1600.urdf"`		abb 6-axis robot
`"abbyumi.urdf"`		abb 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 ® humanoid robot
`"clearpathhusky.urdf"`		clearpath robotics mobile robot
`"clearpathjackal.urdf"`		clearpath robotics mobile robot
`"clearpathturtlebot2.urdf"`		clearpath robotics 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 ® 2-fingered 6 dof robot with non-spherical wrist
`"kinovajacoj2n6s300.urdf"`		kinova ® 3-fingered 6 dof robot with non-spherical wrist
`"kinovajacoj2n7s300.urdf"`		kinova ® 3-fingered 7 dof robot with non-spherical wrist
`"kinovajacoj2s6s300.urdf"`		kinova ® 3-fingered 6 dof robot with spherical wrist
`"kinovajacoj2s7s300.urdf"`		kinova ® 3-fingered 7 dof robot with spherical wrist
`"kinovajacotwoarmexample.urdf"`		two kinova ® 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"`		4 dof robot
`"quanserqbot2e.urdf"`		mobile robot
`"quanserqcar.urdf"`		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: 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"`		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
`"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 = ['', ...
        '', ...
        '', ...
        ''];
% 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 = ['', ...
        '', ...
        '', ...
        ''];
% 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 = ['', ...
        ', ...
        'xmlns:xacro="http://www.ros.org/wiki/xacro">', ...
        '', ...
        ''];
% 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 = ['', ...
        ', ...
        'xmlns:xacro="http://www.ros.org/wiki/xacro">', ...
        '', ...
        ''];
% 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 = ['', ...
        '', ...
        '', ...
        '', ...
        '', ...
        ''];
% 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 = ['', ...
        '', ...
        '', ...
        '', ...
        '', ...
        ''];
% 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"}

urdf, xacro, or sdf import

`meshpath` — relative search paths for mesh files
string scalar | character vector | cell array of string scalars or character vectors

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.

data types: char | string | cell

`dataformat` — input/output data format for kinematics and dynamics functions
`"struct"` (default) | `"row"` | `"column"`

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 property of the robot model.

data types: char | string

`sdfmodel` — select model from sdf that contain multiple models
string scalar | character vector

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

`maxnumbodies` — maximum number of bodies allowed in imported robot during code generation
integer

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.

simscape multibody model import

`breakchains` — indicates whether to break closed chains
`"error"` (default) | `"remove-joints"`

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

`convertjoints` — indicates whether to convert unsupported joints to fixed
`"error"` (default) | `"convert-to-fixed"`

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

`smconstraints` — indicates whether to remove constraint blocks
`"error"` (default) | `"remove"`

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

`variableinertias` — indicates whether to remove variable inertia blocks
`"error"` (default) | `"remove"`

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

`dataformat` — input/output data format for kinematics and dynamics functions
`"struct"` (default) | `"row"` | `"column"`

data types: char | string

output arguments

`robot` — robot model
`rigidbodytree` object

robot model, returned as a 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/s² when using smimport to import a urdf.

`importinfo` — object for storing import information
`rigidbodytreeimportinfo` object

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

use 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 , , or 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, xacro, or sdf file. references to ros packages have the package:\\ 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 object without visual.

version history

introduced in r2017a

import rigid body tree model from urdf, xacro, sdf file, text, or simscape multibody model -凯发k8网页登录

syntax

description

urdf, xacro, or sdf import

simscape multibody model import

examples

import robot from urdf file

import robot from urdf character vector

display robot model with visual geometries

import simscape™ multibody™ model to `rigidbodytree` object

input arguments

`filename` — name of robot description file
string scalar | character vector

`text` — robot description text
string scalar | character vector

`format` — file format of robot description text file
`"urdf"` | `"xacro"` | `"sdf"`

`model` — simscape multibody model
model handle | string scalar | character vector

name-value arguments

`meshpath` — relative search paths for mesh files
string scalar | character vector | cell array of string scalars or character vectors

`dataformat` — input/output data format for kinematics and dynamics functions
`"struct"` (default) | `"row"` | `"column"`

`sdfmodel` — select model from sdf that contain multiple models
string scalar | character vector

`maxnumbodies` — maximum number of bodies allowed in imported robot during code generation
integer

`breakchains` — indicates whether to break closed chains
`"error"` (default) | `"remove-joints"`

`convertjoints` — indicates whether to convert unsupported joints to fixed
`"error"` (default) | `"convert-to-fixed"`

`smconstraints` — indicates whether to remove constraint blocks
`"error"` (default) | `"remove"`

`variableinertias` — indicates whether to remove variable inertia blocks
`"error"` (default) | `"remove"`

`dataformat` — input/output data format for kinematics and dynamics functions
`"struct"` (default) | `"row"` | `"column"`

output arguments

`robot` — robot model
`rigidbodytree` object

`importinfo` — object for storing import information
`rigidbodytreeimportinfo` object

tips

version history

see also

topics

import rigid body tree model from urdf, xacro, sdf file, text, or simscape multibody model -凯发k8网页登录

syntax

description

urdf, xacro, or sdf import

simscape multibody model import

examples

import robot from urdf file

import robot from urdf character vector

display robot model with visual geometries

import simscape™ multibody™ model to rigidbodytree object

input arguments

filename — name of robot description file string scalar | character vector

text — robot description text string scalar | character vector

format — file format of robot description text file "urdf" | "xacro" | "sdf"

model — simscape multibody model model handle | string scalar | character vector

name-value arguments

meshpath — relative search paths for mesh files string scalar | character vector | cell array of string scalars or character vectors

dataformat — input/output data format for kinematics and dynamics functions "struct" (default) | "row" | "column"

sdfmodel — select model from sdf that contain multiple models string scalar | character vector

maxnumbodies — maximum number of bodies allowed in imported robot during code generation integer

breakchains — indicates whether to break closed chains "error" (default) | "remove-joints"

convertjoints — indicates whether to convert unsupported joints to fixed "error" (default) | "convert-to-fixed"

smconstraints — indicates whether to remove constraint blocks "error" (default) | "remove"

variableinertias — indicates whether to remove variable inertia blocks "error" (default) | "remove"

dataformat — input/output data format for kinematics and dynamics functions "struct" (default) | "row" | "column"

output arguments

robot — robot model rigidbodytree object

importinfo — object for storing import information rigidbodytreeimportinfo object

tips

version history

see also

topics

wechat

import simscape™ multibody™ model to `rigidbodytree` object

`filename` — name of robot description file
string scalar | character vector

`text` — robot description text
string scalar | character vector

`format` — file format of robot description text file
`"urdf"` | `"xacro"` | `"sdf"`

`model` — simscape multibody model
model handle | string scalar | character vector

`meshpath` — relative search paths for mesh files
string scalar | character vector | cell array of string scalars or character vectors

`dataformat` — input/output data format for kinematics and dynamics functions
`"struct"` (default) | `"row"` | `"column"`

`sdfmodel` — select model from sdf that contain multiple models
string scalar | character vector

`maxnumbodies` — maximum number of bodies allowed in imported robot during code generation
integer

`breakchains` — indicates whether to break closed chains
`"error"` (default) | `"remove-joints"`

`convertjoints` — indicates whether to convert unsupported joints to fixed
`"error"` (default) | `"convert-to-fixed"`

`smconstraints` — indicates whether to remove constraint blocks
`"error"` (default) | `"remove"`

`variableinertias` — indicates whether to remove variable inertia blocks
`"error"` (default) | `"remove"`

`dataformat` — input/output data format for kinematics and dynamics functions
`"struct"` (default) | `"row"` | `"column"`

`robot` — robot model
`rigidbodytree` object

`importinfo` — object for storing import information
`rigidbodytreeimportinfo` object