Documentation

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')

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

^†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')

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 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 STL (Standard Tesselation) 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.

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: