Import URDF Models

To import a URDF model into a Simscape™ Multibody™ model, use the smimport function. You must specify the file extension.

smimport('Humanoid.urdf')

If you omit the file extension, the smimport function assumes that the file is in the XML format used to import CAD models. For example, the command

smimport('Humanoid')

tells the function to create a multibody model from the 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. For more information about how to import a URDF model, see Import a URDF Humanoid Model.

Supported URDF Elements and Attributes

The 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 smimport function 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 <visual>/<geometry>/<mesh> element is shown in orange because the attribute is partially supported. For more information about the scale attribute, see the Mesh Geometries section.

Mapping to Simscape Multibody Blocks

The URDF <robot> element maps into a Simscape Multibody model. The <link> elements nested inside the <robot> element map into Simulink^® Subsystem blocks representing the links or, in Simscape Multibody nomenclature, bodies. The <joint> 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 named Inertia.

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 the <origin> elements of the <inertial> and <visual> elements of links, as well as from the <origin> and <axis> 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 and Simscape Multibody software is largely intuitive. A <joint> element of type prismatic maps into a Prismatic Joint block. A <joint> element of type fixed maps into a Weld Joint block. The table shows the mappings for the remaining URDF <joint> elements.

Correspondence Between URDF and Simscape Multibody Joints

URDF <joint type> Attribute	Simscape Multibody Joint Block	Degrees of Freedom
`revolute`	Revolute Joint	One rotational (with limits)
`continuous`	Revolute Joint	One rotational
`prismatic`	Prismatic Joint	One translational (with limits)
`fixed`	Weld Joint	None
`floating`	6-DOF Joint	Three rotational and three translational
`planar`	Planar Joint	Two rotational and one translational

Mesh Geometries

To specify the visual geometries of a URDF model by using external geometry files, use the <mesh> element, for example:

<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 scale attribute specifies the units for the vertex data in the converted File Solid blocks.

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

Physical Units

In the converted Simscape Multibody model, the block parameters use the International System of Unit, SI.

URDF Import Limitations

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

The smimport function does not support the elements and attributes derived from URDF extensions, such as <transmission>, <gazebo>, <model_state>, and <sensor> elements.

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 Export a CAD Assembly 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

smimport('DoublePendulum.urdf')

If you saved your URDF model under a different name, use that name instead. The function imports the URDF model and generates an equivalent Simscape Multibody model. The figure shows the resulting model with the blocks and their connection lines slightly rearranged.

About the Imported Model

The <link> elements named link A, link B, and link C in the URDF model map into Simulink Subsystem blocks also named link A, link B, and link C. The <joint> elements named joint A and joint B—each with type set to continuous—map into Simscape Multibody Revolute Joint blocks also named joint A and joint B.

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. link A is the root link and is therefore grounded—a condition reflected in the rigid connection between the 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 link A Subsystem block.

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 <inertial> URDF element and is accordingly named Inertial. This block contains the relevant parameters of the <inertial> element, 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 <inertial>, <visual>, and <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 30 deg. 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.