Import URDF Models
To import a URDF model into a Simscape™
Multibody™ model, use the
smimport function. You must specify
the file extension.
If you omit the file extension, the
assumes that the file is in the XML format used to import CAD models. For
example, the command
tells the function to create a multibody model from the
sm_humanoid XML file. If the function finds no XML file
with the specified name, it returns an error even if there is a URDF file with
the same name in the same folder.
Supported URDF Elements and Attributes
smimport function supports a subset of elements
and attributes of the URDF
specification. When you import a URDF model with unsupported
elements or attributes, the
recognizes only the supported elements and attributes. The following example
shows all the supported elements and attributes in black.
<robot name> <link name> <inertial> <origin xyz rpy /> <mass value /> <inertia ixx iyy izz ixy ixz iyz /> </inertial> <visual name> <origin xyz rpy /> <geometry> <box size /> <cylinder radius length /> <sphere radius /> <mesh filename scale /> </geometry> <material name> <color rgba /> <texture filename /> </material> </visual> <collision name> <origin xyz rpy /> <geometry> <box size /> <cylinder radius length /> <sphere radius /> <mesh filename scale /> </geometry> </collision> </link> <joint name type> <origin xyz rpy /> <parent link /> <child link /> <axis xyz /> <calibration rising /> <calibration falling /> <dynamics damping friction /> <limit lower upper effort velocity /> <mimic joint multiplier offset /> <safety_controller soft_lower_limit ... ... soft_upper_limit k_position k_velocity /> </joint> </robot>
Elements are in bold font and attributes are in regular font. Unsupported
elements and attributes are highlighted in red. The
smimport function does not support an element or
attribute if the element or attribute is not shown in the above example.
Note that the
scale attribute of the
element is shown in orange because the attribute is partially supported. For
more information about the
scale attribute, see the Mesh Geometries
Mapping to Simscape Multibody Blocks
<robot> element maps into a Simscape
Multibody model. The
<link> elements nested
<robot> element map into Simulink® Subsystem blocks representing the links or, in Simscape
Multibody nomenclature, bodies. The
elements map into equivalent Simscape
Multibody joint blocks. The
name attributes of these
elements map into the model name, the Subsystem block names, and the joint
block names, respectively.
The Subsystem blocks comprise solid, Inertia, Rigid
Transform, and Reference
Frame blocks. The solid blocks provide the geometries
and colors of the body; these blocks correspond to the
<visual> tags of the URDF model and are named
Visual. The Inertia
block provides the mass, center of mass, moments of inertia, and products of
inertia of the body; this block corresponds to the
<inertial> element of the URDF model and it is
The Rigid Transform blocks provide the
translational and rotational offsets from the local reference frame of the
body to the Inertial and Visual elements. These transforms are derived from
<origin> elements of the
<visual> elements of links, as well as from the
elements of joints. The Reference Frame block
identifies the local reference frame of the body.
The type of joint block used depends on the
<type> attribute of the
<joint> element. The joint mapping between URDF
Multibody software is largely intuitive. A
<joint> element of
prismatic maps into a Prismatic Joint block. A
<joint> element of
fixed maps into a Weld Joint block. The
table shows the mappings for the remaining URDF
Correspondence Between URDF and Simscape Multibody Joints
|URDF <joint type> Attribute||Simscape Multibody Joint Block||Degrees of Freedom|
|Revolute Joint||One rotational (with limits)|
|Revolute Joint||One rotational|
|Prismatic Joint||One translational (with limits)|
|6-DOF Joint||Three rotational and three translational|
|Planar Joint||Two rotational and one translational|
To specify the visual geometries of a URDF model by using external
geometry files, use the
<mesh> element, for
<link name="link_1.3"> <visual> <origin rpy="0 -1.57079632679 0" xyz="0 0 0.0425"/> <geometry> <mesh filename="package://xela_models/mesh_simplified/finger_link_3.stl" scale="0.001 0.001 0.001"/> </geometry> </visual> </link>
The geometry files are not a part of the URDF file, and you must save the
geometry files in the same folder as the corresponding URDF file. The
geometry files must be in STL or STEP format. Note that the
smimport function does not support Collada (DAE)
files. If you import a model with references to DAE files, the Simscape
Multibody model does not render the geometries derived from these files. The
lack of visualization may limit your ability to analyze the model but has no
impact on the model dynamics.
When you import a URDF model whose visual geometries refer to external files, the vertex
data in the files remain unscaled regardless of the value of the
scale attribute. The
attribute specifies the units for the vertex data in the converted
To specify the units to
cm, set the
x, y, and
z-axis scale factors of the
scale attribute to 0.01. To specify the units as
mm, set all three factors to 0.001. Note that all
three factors must have the same value, and you must specify the value as
either 0.01 or 0.001. If the values do not meet these conditions, the
smimport function specifies the units to
In the converted Simscape Multibody model, the block parameters use the International System of Unit, SI.
URDF Import Limitations
smimport function imports only URDF models with
tree topologies and does not support URDF variants such as SDF (Simulation
Description Format) and DrakeURDF. However, after importing a URDF, you can
add blocks to the Simscape Multibody model to form a kinematic loop.
smimport function does not support the elements
and attributes derived from URDF extensions, such as
Differences from CAD Import
Despite their similarities, including their mutual reliance on the
smimport function, CAD and URDF import differ in
some important aspects:
CAD models are imported in an intermediate XML format. URDF models are imported directly in URDF format.
The intermediate XML files provide the information needed to recreate the CAD models in the Simscape Multibody environment. The same information is provided directly in URDF files when importing URDF models. XML multibody description files must conform to the Simscape Multibody XML schema. See Exporting a CAD Model for ways to generate a valid XML file.
Imported CAD models have their numerical parameters defined in MATLAB® files. Imported URDF models have their numerical parameters hardcoded into the block dialog boxes.
CAD import uses a detached data framework that places all block parameter values in a cell structure defined in a separate MATLAB data file. The detached data framework enables you to update a previously imported model when you modify the source CAD model. URDF import lacks this feature and does not support model update.
Import a Simple URDF Model
As an example, import the double-pendulum URDF model described in the Create a Simple URDF Model section. Create the URDF model if you have not yet done so before proceeding. To import the model, navigate to the folder in which you saved your double-pendulum URDF model. Then, at the MATLAB command prompt, enter the command
About the Imported Model
<link> elements named
link B, and
C in the URDF model map into Simulink Subsystem blocks also named
link B, and
link C. The
<joint> elements named
joint B—each with
type set to
continuous—map into Simscape
Revolute Joint blocks
joint A and
The block diagram reflects the topology of the URDF model—an
unbranched kinematic tree.
link C connects to
link B as a child of that element.
B in turn connects to
link A as a child
of that element.
link A is the root link and is
therefore grounded—a condition reflected in the rigid connection
link A and World Frame blocks.
URDF Model Topology
The Subsystem blocks representing the URDF
<link> elements each comprise a small block
diagram with one Reference Frame block, one Brick
Solid block, one
Inertia block, and multiple
Rigid Transform blocks. The
Subsystem blocks are not masked and can be opened
directly with a double click. The figure shows the block diagram of the
The Brick Solid block is the translated
equivalent of the
<visual> URDF element and is
named Visual. This block contains the relevant parameters of the
<visual> element, including link geometry
and color. The Inertia block is the
translated equivalent of the
element and is accordingly named Inertial. This block contains the
relevant parameters of the
including link mass, moments of inertia, and products of inertia.
link A Subsystem
The Reference Frame block identifies
the local reference frame of the
element. This frame coincides with the joint connection frame to the
parent link or, as in this case of a root link, to the
World Frame block. The
Rigid Transform blocks specify the
translational and rotational transforms to the reference frames of the
<joint> URDF elements. An additional
Rigid Transform block specifies the
rotation transform needed to align the Simscape
Multibody joint axis with the URDF joint axis.
Assemble and Simulate the Imported Model
Build on the model to obtain a meaningful simulation. You can, for example, use joint state targets to assemble the double pendulum in an unstable configuration and simulate its fall under gravity:
In the dialog box of the joint_A block, select the State Targets > Specify Position Target check box and set the Value parameter to
30deg. This parameter sets the starting angle of the upper joint.
In the Solver pane of the Configuration Parameters window, click Additional options and set the Max step size parameter to
0.01. This value keeps the solver step size small enough to produce a smooth animation during simulation. Increase the value if simulation proceeds slowly.
Update the block diagram and run the simulation. In the Modeling tab, click Update Model. You can simulate the model by selecting Run. Mechanics Explorer shows an animation of the double pendulum fall under gravity.