importrobot

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

This function imports a robot model from a URDF file, Xacro file, SDF file, robot description text, or a Simscape™ Multibody™ model as a rigidBodyTree object.

Note

To load predefined, ready-to-use, robot models from the Robotics System Toolbox™ Robot Library, use the loadrobot function.

URDF, Xacro, or SDF Import

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.

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

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

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

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.

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

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 DataFormat property of the rigidBodyTree 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.

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

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.

CollisionDecomposition — Decomposition of collision meshes of robot after import

false or 0 (default) | true or 1 | vhacdOptions object

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

• false — importrobot does not decompose the robot collision meshes after import.

• true — importrobot 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

BreakChains — Closed chain breaking

"error" (default) | "remove-joints"

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

ConvertJoints — Unsupported to fixed joint conversion

"error" (default) | "convert-to-fixed"

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

SMConstraints — Constraint block removal

"error" (default) | "remove"

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

VariableInertias — Variable inertia block removal

"error" (default) | "remove"

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

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

Data Types: char | string

Output Arguments

robot — Robot model

rigidBodyTree object

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/s² when using smimport to import a URDF.

importInfo — Object for storing import information

rigidBodyTreeImportInfo object

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

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

When using the CollisionDecomposition name-value argument, importrobot supports code generation when the value of CollisionDecomposition is true (1) or false (0).

Version History

Introduced in R2017a

R2024a: Import robots with floating joints

The importrobot function now supports:

• Importing floating joints from URDF files that use joint elements of attribute type floating. For more details, see https://wiki.ros.org/urdf/XML/joint.

• Importing 6-DOF Joint (Simscape Multibody) blocks from Simscape Multibody models as floating joint.

The rigid body tree represents the 6DOF joints in Simscape Multibody or floating joints in URDF files as rigidBodyJoint objects with the Type property set to "floating".

R2023b: Collision-mesh decomposition support

The importrobot function supports voxelized hierarchical approximate convex decomposition (V-HACD) of robot model collision meshes after import using the CollisionDecomposition name-value argument.

R2021b: Code generation support

The importrobot function supports code generation.