smimport

Import a CAD, URDF, or Robotics System Toolbox model

Syntax

[H,dataFileName] = smimport(modelSource)

[H,dataFileName] = smimport(modelSource,Name,Value)

Description

[H,dataFileName] = smimport(modelSource) creates a Simscape Multibody model from a CAD, URDF, or Robotics System Toolbox model.

modelSource is the name of the file or object containing the model or, for CAD import, an intermediate representation of it. CAD models must be in XML files, URDF models in URDF files, and Robotics System Toolbox models in RigidBodyTree objects. XML files must conform to the Simscape Multibody XML schema and URDF files must conform to the URDF specification. A Robotics System Toolbox license is required to create RigidBodyTree objects.

H is the model handle and dataFileName is the name of the supporting file that, in imported CAD models, stores the numeric values of block parameters—in a structure array populated with MATLAB variables referenced in the blocks. The data file provides a mechanism to update the imported model if the CAD model changes. Models imported from URDF files or RigidBodyTree objects do not rely on data files for block parameters.

XML files can come from different sources. The smexportonshape function converts Onshape CAD models into XML files for import. The Simscape Multibody Link plug-in does the same for Autodesk Inventor^®, PTC^®, and SolidWorks^® CAD models. The plug-in is free to download. For other CAD applications, and for multibody modeling tools of other types, the Simscape Multibody XML schema makes it possible to create a custom model export app.

CAD, URDF, and RigidBodyTree models all share the same components. These are (i) rigid bodies, also known as parts in CAD models and links in URDF models, and (ii) kinematic constraints, packaged, in some cases, as joints. Rigid bodies import as Simulink subsystems with Solid and Rigid Transform blocks—the elemental components from which the attributes of shape, inertia, color, and placement derive. Constraints map into joint, gear, and other constraint blocks.

URDF models contain <link> elements which in turn contain <joint> elements. Likewise, RigidBodyTree objects contain RigidBody objects which in turn contain Joint objects. This hierarchy changes with import into Simscape Multibody. Joints become siblings to rigid bodies and feature not inside rigid body subsystems but alongside them. Joint limits are ignored but home positions persist as position targets specified in the appropriate joint blocks.

[H,dataFileName] = smimport(modelSource,Name,Value) creates a Simscape Multibody model from a CAD, URDF, or Robotics System Toolbox model with custom name or regenerates the data file of a previously imported CAD model. Most name-value pair arguments apply only to CAD models. Use ImportMode to regenerate parameter data files and PriorDataFile to catch inadvertent changes to the model, such as the removal of a part or a change in its name.

Input Arguments

modelSource — Name of model file or object to import

custom string or character vector

Name of the model to import. Use the name of the model file for CAD and URDF models and the name of the rigidBodyTree object for Robotics System Toolbox models. Include extension and path for model files. CAD model files must be in XML format and URDF model files in URDF format. XML files must conform to the Simscape Multibody XML schema. If file extension is missing, the model is assumed to be in XML format. If file path is missing, the file is assumed to be on the MATLAB^® path.

Example: 'robotto.xml'

Data Types: char | string

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: smimport('sm_robot','ModelName','robotto','DataFileName','robottos_data_file');

'ModelSimplification' — Model topology simplification mode

none (default) | bringJointsToTop | groupRigidBodies

Model topology simplification mode to use during CAD import. Set ModelSimplification to:

• bringJointsToTop to group rigidly connected parts into subsystems and promote joints to the top level in the model hierarchy.

• groupRigidBodies to group rigidly connected parts into subsystems but leave joints in their original places in the model hierarchy.

• None to import the model as is, without simplification.

Joints brought to the top level of a model are renamed using generic names based on the joint type—for example, Revolute_Joint1. Subsystems of rigidly connected components that have been grouped together are given generic names based on the string RigidSubsystem—for example, RigidSubsystem1. This argument applies only to CAD import.

Example: 'bringJointsToTop'

Data Types: char | string

'ImportMode' — Choice of model import or data file update function modes

modelAndDataFile (default) | dataFile

Option to generate a new model or update existing model data. Set ImportMode to modelAndDataFile to generate a new model and data file. Set ImportMode to dataFile to generate a new data file for a previously imported model. The function does not update the block diagram itself. If you do not specify ImportMode, the function runs in modelAndDataFile mode. This argument applies only to CAD import.

Example: 'dataFile'

Data Types: char | string

'ModelName' — Name of the multibody model to generate

custom string or character vector

Name of the Simscape™ Multibody™ model to generate. The model is saved in SLX format. This argument is not valid when ImportMode is set to dataFile. If you do not specify ModelName, the model file is named after the multibody description file. If the multibody description file name is inconsistent with MATLAB naming rules, a slightly modified version is used instead.

Example: 'robotto'

Data Types: char | string

'DataFileName' — Name of the parameter data file to generate

custom string or character vector

Name of the supporting parameter data file. The data file is an M file with the block parameter values referenced in the imported Simscape Multibody model. If you do not specify DataFileName, the data file is named after the multibody description file. If the multibody description file name is inconsistent with MATLAB naming rules, a modified version is used instead. This argument applies only to CAD import.

Example: 'robottos_new_data'

Data Types: char | string

'PriorDataFile' — Name of the last used parameter data file

custom string or character vector

Name of the last parameter data file associated with a previously imported model. The prior data file helps to identify changes requiring special attention, such as new physical units, added and deleted components, and model topology changes. This argument is valid only when ImportMode is set to dataFile. This argument applies only to CAD import.

Example: 'robottos_original_data'

Data Types: char | string

'VariableName' — Name of the MATLAB structure provided in the parameter data file

custom string or character vector

Name of the MATLAB data structure provided in the parameter data file. This structure contains the numerical values of all block parameters in the Simscape Multibody model. If you specify neither PriorDataFile nor VariableName, the data structure is named smiData. If you specify PriorDataFile but not VariableName, the data structure name is derived from the prior data file. This argument applies only to CAD import.

Example: 'robottosData'

Data Types: char | string

Output Arguments

H — Model handle

double

Model handle returned as a double. Use the model handle to get or set model parameters, for example, using the get_param and set_param functions.

Data Types: double

dataFileName — Name of the parameter data file

character vector

Name of the parameter data file. The data file is an M file with the block parameter values referenced in the imported Simscape Multibody model. This output applies only to CAD import.

Data Types: char

Examples

Import a CAD Model with Default Name

Import a CAD model of a robotic arm. The model has been exported in XML format using Simscape Multibody Link. The XML file is named sm_robot.xml and it is part of your Simscape Multibody installation.

1. Import the model and store it in memory as Untitled. You can later change the name. As the model is in XML format, you can omit the extension in its name.

   smimport('sm_robot');

2. Update the diagram to assemble the model and visualize it in Mechanics Explorer. You can update the diagram from the Simulink^® menu bar by selecting Simulation > Update Diagram.

   

   CAD models often assume the y-axis as the vertical axis while Simscape Multibody models assume the z-axis. As a result, the imported model appears sideways on the screen. Use the View convention drop-down list in Mechanics Explorer to correct for the difference in convention.

3. In the Mechanics Explorer tool strip, set the View Convention parameter to Y up (XY Front) and select a standard viewpoint, such as Isometric, shown below.

   

   Selecting a standard view activates the new view convention. The model rotates to assume its orientation in the original CAD model.

4. Simulate the model. The robot arm lacks a control system and swings erratically under the pull of gravity. Build on the model by adding control systems to simulate useful tasks. Add internal mechanics to joints to dampen their motions and specify joint targets to change the initial arm pose.

Import a CAD Model with Custom Name

Import the CAD model of the robotic arm and save it in the active folder with the name robotto. Name the parameter data file robottos_data_file.

smimport('sm_robot','ModelName','robotto',...
'DataFileName','robottos_data_file');

Update an Imported CAD Model

Regenerate the data file for the imported CAD model of the robotic arm. To avoid overwriting the original data file, name the new file robottos_new_data_file.

smimport('sm_robot','ImportMode','dataFile','DataFileName',...
'robottos_new_data_file','PriorDataFile','robottos_data_file');

Point the imported model to the new data file and reinitialize the model workspace.

hws = get_param(bdroot,'modelworkspace');
hws.DataSource = 'MATLAB File';
hws.FileName = 'robotFileData';
hws.reload;

To do the same using Model Explorer, select the model and, in the Model Workspace pane, update the File Name parameter. Click Reinitialize from Source button to apply the change.

Import a URDF Model

Import a URDF model of a humanoid robot. The model is named sm_humanoid.urdf and it is part of your Simscape Multibody installation.

1. Import the model and store it in memory as Untitled. You can later change the name. As the model is in URDF format, the file extension is required.

   smimport('sm_humanoid.urdf');

2. Update the diagram to visualize the model in its initial configuration using Mechanics Explorer. You can update the diagram from the Simulink menu bar by selecting Simulation > Update Diagram.

   

3. Simulate the model. As with the robot arm, the humanoid robot lacks a control system and swings erratically under the pull of gravity. The shoulder line serves as the root body in the URDF model, and so it is fixed to the world frame after import.

   Try modifying the model—for example, by removing the rigid connection between the shoulder line and the world frame and by adding control subsystems at the various joints. See the Humanoid Robot featured example for a version of the model with basic motion controls. You can open the example by entering sm_import_humanoid_urdf at the MATLAB command prompt.

   

Import a RigidBodyTree Object

Import a RigidBodyTree object for an LBR iiwa serial manipulator (manufactured by KUKA Robotics). The model features in the Robotics System Toolbox installation as a URDF model named iiwa14.urdf.

1. Convert the URDF model into a RibidBodyTree object.

   iiwaRBT = importrobot('iiwa14.urdf');

   A Robotics System Toolbox license is required to run importrobot.

2. Import the iiwaRST object into Simscape Multibody.

   iiwaSM = smimport(iiwaRBT);

3. Update the diagram to visualize the model in its initial configuration using Mechanics Explorer. You can update the diagram from the Simulink menu bar by selecting Simulation > Update Diagram.

   

4. Simulate the model. As with the robot arm, the iiwa14 model lacks a control system and swings erratically under the pull of gravity. Build on the model by adding control systems to simulate useful tasks. Add internal mechanics to joints to dampen their motions and specify joint targets to change the initial arm pose.