Importing a URDF Model
You import a URDF model into the Simscape™
Multibody™ environment using the
smimport function with the URDF
file name as its principal argument. The function identifies the model
type—URDF or XML—via the file extension. If you omit the
extension, the function assumes that the file is in the XML format more
commonly used for CAD import. For example, the
sm_humanoid. The command
tells the function to import a multibody model from an intermediate
XML file named
sm_humanoid. 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. As
a rule, you must include the URDF file extension explicitly whenever
attempting to import URDF models.
URDF Entities That You Can Import
Simscape Multibody software supports only a subset of all the available URDF elements and attributes. You can import a URDF model with unsupported elements or attributes, but all such entities are ignored. The following code shows the elements and attributes that you can and cannot import. Elements are shown in bold font and attributes in regular font. Unsupported elements and attributes are shown in red.
<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>
Mapping to Simscape Multibody Blocks
<robot> element maps into
Multibody model. The
nested inside the
<robot> element map into Simulink® Subsystem
blocks representing the links or, in Simscape
<joint> elements map into equivalent Simscape
name attributes of these elements map
into the model name, the Subsystem block names, and the joint block
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
<origin> elements of the
of links, as well as from the
of joints. The Reference Frame block identifies the
local reference frame of the body.
The type of joint block used depends on the
<joint> element. The joint mapping
between URDF and Simscape
Multibody software is largely intuitive.
<joint> element of
maps into a Prismatic Joint block. A
type fixed maps into a Weld
Joint block. The table shows the mappings for the remaining
Correspondence Between URDF and Simscape Multibody Joints
|URDF <joint type> Attribute||Simscape Multibody Joint Block||Degrees of Freedom|
|Revolute Joint†||One rotational with joint limits†|
|Revolute Joint||One rotational (without joint limits)|
|Prismatic Joint||One translational with joint limits†|
|Weld Joint||Zero (rigid connection)|
|6-DOF Joint||Three rotational and three translational|
|Planar Joint||Two rotational and one translational|
†Joint limits are ignored
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
link C in
the URDF model map into Simulink Subsystem blocks also named
link B, and
<joint> elements named
joint B—each with
continuous—map into Simscape
Multibody Revolute Joint blocks also named
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.
link B in turn connects to
link A as a child of that element.
A is the root link and is therefore grounded—a
condition reflected in the rigid connection between the
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
<link> URDF 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.
URDF Import Limitations
URDF models allow only tree topologies. Some URDF variants, such as SDF (Simulation Description Format) and DrakeURDF, add support for kinematic loops. You cannot import models in these alternative formats. You can, however, add kinematic loops to an imported model once in the Simscape Multibody environment.
Some URDF elements and attributes derived from URDF extensions are not supported. Extensions
<transmission> elements used to model gear
trains and parallel linkages,
used to simulate URDF models in the Gazebo environment, and the less
Some core URDF elements
and attributes are also not supported. Unsupported elements include
used for link collision detection, and
used for joint motion limits. Unsupported attributes include
mesh file scaling,
friction for joint internal
mechanics, and more. Unsupported
URDF elements and attributes are ignored during import.
You can import URDF models with references to external geometry files, but the files must be in STL (Standard Tessellation Language) format.
Collada, or DAE, geometry files, common in URDF models, are not supported in Simscape Multibody software. If you import a model with references to DAE files, the geometries derived from those files are not rendered. The lack of visualization may limit your ability to analyze a model but has no impact on the model dynamics.
The block parameters of the imported model are automatically set to the URDF default units, SI. You can modify the units after import, but you must do so on a black-by-block basis. A variety of other units are supported, including those at the core of MKS (Meter-Kilogram-Second), USC (US Customary), and other units systems.
Differences from CAD Import
Despite their similarities, including their mutual reliance
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.