importrobot

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

collapse all in page

Syntax

robot = importrobot(filename)
robot = importrobot(URDFtext)
[robot,importInfo] = importrobot(model)
___ = importrobot(___,Name,Value)

Description

example

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

example

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

[robot,importInfo] = importrobot(model) imports a Simscape™ Multibody™ model and returns an equivalent rigidBodyTree object and info about the import in importInfo. Only fixed, prismatic, and revolute joints are supported in the output rigidBodyTree object. Use the Simscape Multibody Model Import name-value pairs to import a model that uses other joint types, constraint blocks, or variable inertias.

___ = importrobot(___,Name,Value) provides additional options specified by Name,Value pair arguments. Use any of the previous syntaxes. Only certain name-value pairs apply depending on whether you convert from a URDF file or a Simscape Multibody model.

Examples

collapse all

Open Live Script

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)

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
Open Live Script

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'
Open Live Script

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. Use the show function to visualize 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);

This example uses:

Open Live Script

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 URDF file, specified as a string scalar or character vector. This file must be a valid URDF robot description.

Example: "robot_file.urdf"

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

Data Types: char | string

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

Data Types: double | char | string

Name-Value Pair 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 File 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 file, but MeshPath defines the relative paths for these specified files. When using this function, the URDF importer searches for the mesh files specified in the URDF using all the specified relative paths.

Data Types: char | string | cell

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

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

    • One level above the folder containing the URDF file

  • The file name from the mesh path in the URDF 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.

See Also

|

Topics

Introduced in R2017a

Robotics System Toolbox Documentation
Support