Documentation

URDF Import

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 command

smimport('sm_humanoid.urdf')
tells the function to import a URDF model named sm_humanoid. The command
smimport('sm_humanoid')

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

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, Rigid Transform, and Reference Frame blocks. The Solid blocks provide the solid properties—geometry, inertia, color—of the body. Each Subsystem block contains two types of Solid blocks. One is named Inertial and contains the inertia data from the <inertial> element. Inertial Solid block impact only model dynamics. The other is named Visual and contains the geometry and color data from the <visual> element. Visual Solid blocks impact only model visualization.

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> AttributeSimscape Multibody Joint BlockDegrees of Freedom
revoluteRevolute JointOne rotational with joint limits
continuousRevolute JointOne rotational (without joint limits)
prismaticPrismatic JointOne translational with joint limits
fixedWeld JointZero (rigid connection)
floating6-DOF JointThree rotational and three translational
planarPlanar JointTwo 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

smimport('double_pendulum.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, two Solid blocks, and a variable number of 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.

One 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 second Solid block is the translated equivalent of the <inertial> URDF element and is 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:

  1. In the dialog box of the joint_A block, select the State Targets > Specify Position Target checkbox and set the Value parameter to 30 deg. This parameter sets the starting angle of the upper joint.

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

  3. Update the block diagram and run the simulation. You can update the block diagram by selecting Simulation > Update Diagram. You can simulate the model by selecting Simulation > 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.

URDF elements and attributes derived from URDF extensions are not supported. Extensions include <transmission> elements used to model gear trains and parallel linkages, <gazebo> elements used to simulate URDF models in the Gazebo environment, and the less commonly used <model_state> and <sensor> elements.

Some core URDF elements and attributes are also not supported. Unsupported elements include <collision>, used for link collision detection, and <limit>, used for joint motion limits. Unsupported attributes include scale for mesh file scaling, friction for joint internal mechanics, and more. Unsupported URDF elements and attributes are ignored during import.

Mesh Geometries

You can import URDF models with references to external geometry files, but the files must be in a format compatible with Simscape Multibody software. Valid file formats include STL (Standard Tesselation Format) and STEP (Standard for the Exchange of Product data), sometimes referred to as STP.

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.

While not natively supported in URDF, any STEP file references that you include in your URDF model import without issue. If necessary, you can convert any DAE files referenced in your URDF model to STEP or STL format and update the file references—found in the <mesh> elements nested inside the link <geometry> elements—to import the model with full visualization.

Physical Units

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

See Also

Related Topics

Was this topic helpful?