Main Content

smimport

Import a CAD, URDF, or Robotics System Toolbox model

collapse all in page

    Syntax

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

    Description

    example

    [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 for import. Use XML files for CAD models, URDF files for URDF models, and rigidBodyTree (Robotics System Toolbox) objects for Robotics System Toolbox™ models. XML files must conform to the Simscape Multibody XML schema, and URDF files must conform to the Supported URDF Elements and Attributes. 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. For example, the smexportonshape function converts CAD models into XML files. The Simscape™ Multibody™ Link plug-in is able to convert Autodesk Inventor®, PTC®, and SolidWorks® CAD models into XML files. For other CAD applications and multibody modeling tools, 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. 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 and rigidBodyJoint objects. In the created Simscape Multibody model, joints become siblings to rigid bodies and features that not inside rigid body subsystems but alongside them. Joint limits and home positions persist, the later as position state targets, in the appropriate joint blocks.

    Note

    Joint limits are imported from URDF and rigidBodyTree models but not from CAD models. Reproduce the joint limits of CAD models manually if you must—by enabling joint limits in the joint blocks and setting the limit positions to appropriate values.

    example

    ___ = smimport(___,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.

    Examples

    collapse all

    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.

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

    smimport('sm_robot');

    Update the diagram to assemble the model and visualize it in Mechanics Explorer. In the Modeling tab, click Update Model.

    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 the bottom view of the robot on the screen. To change the view convention, use the View convention drop-down list in Mechanics Explorer.

    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.

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

    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 = 'robottos_new_data_file';
hws.reload

    To do the same using Model Explorer, first, select MODELING > DESIGN > Model Workspace to open the Model Explorer. Next, in the Model Hierarchy of the Model Explorer, left click Model Workspace. In the Model Workspace pane, enter robottos_new_data_file.m in the File Name parameter and click Reinitialize from Source button to apply the change.

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

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

    smimport('sm_humanoid.urdf');

    Update the diagram to visualize the model in its initial configuration using Mechanics Explorer. In the Modeling tab, click Update Model.

    Simulate the model. 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.

    You can modify the model and program the motions of the robot. The Humanoid Robot shows a simple example. You can open the example by entering sm_import_humanoid_urdf at the MATLAB® command prompt.

    Import a rigidBodyTree object for an LBR iiwa serial manipulator. The model is a part of the Robotics System Toolbox installation and a URDF model named iiwa14.urdf.

    Convert the URDF model into a ribidBodyTree object.

    iiwaRBT = importrobot('iiwa14.urdf');

    Note

    A Robotics System Toolbox license is required to run importrobot (Robotics System Toolbox).

    Import the iiwaRBT object into Simscape Multibody.

    iiwaSM = smimport(iiwaRBT);

    Update the diagram to visualize the model in its initial configuration using Mechanics Explorer. In the Modeling tab, click Update Model.

    Input Arguments

    collapse all

    Name of import file or object, specified as a string scalar or character vector. Use XML files for CAD models, URDF files for URDF models, and rigidBodyTree objects for Robotics System Toolbox models. 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 Arguments

    Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

    Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

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

    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: 'ModelSimplification','bringJointsToTop'

    Data Types: char | string

    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: 'ImportMode','dataFile'

    Data Types: char | string

    Name of the Simscape Multibody model, specified as the comma-separated pair consisting of 'ModelName' and a character vector or string scalar. 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: 'ModelName','robotto'

    Data Types: char | string

    Name of the supporting parameter data file, specified as the comma-separated pair consisting of 'DataFileName' and a character vector or string scalar. 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: 'DataFileName','robottos_new_data'

    Data Types: char | string

    Name of the last parameter data file, specified as the comma-separated pair consisting of 'PriorDataFile' and a character vector or string scalar. 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: 'PriorDataFile','robottos_original_data'

    Data Types: char | string

    Name of the MATLAB data structure provided in the parameter data file, specified as the comma-separated pair consisting of 'VariableName' and a character vector or string scalar. 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: 'VariableName','robottosData'

    Data Types: char | string

    Output Arguments

    collapse all

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

    Data Types: double

    Name of the parameter data file, returned as a character vector. The 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

    Version History

    Introduced in R2012b

    See Also

    | (Robotics System Toolbox)

    Topics