Learn more about SimMechanics

mech_import - Generate model from Physical Modeling XML file

Syntax

mech_import mech_import('-license') mech_import('filename.xml') mech_import('filename.xml', option1, value1, option2, value2, ...)

Description

mech_import with no inputs opens the Import Physical Modeling XML dialog box. In the dialog box, you select the XML file to import and the function options. See In the Import Dialog Box following.

mech_import('-license') displays the third-party license for use of this function.

mech_import('filename.xml') generates a SimMechanics model from a Physical Modeling XML file called filename.xml. For an XML file generated from computer-aided design (CAD), the name of the generated model is the same as the original CAD assembly, regardless of the name of the XML file.

mech_import('filename.xml', option1, value1, option2, value2, ...) generates the SimMechanics model from filename.xml using the specified option-value pairs when importing.

The mech_import function either generates a new SimMechanics model or updates a previously generated SimMechanics model that you specify. It also generates or updates the associated body geometry files.

Inputs

At the Command Line

In command line mode, mech_import requires one input and accepts additional optional inputs.

`'filename.xml'`	Input XML file name. Replace `filename` with the name of the XML file that you want to import. The `.xml` extension in this input is optional. This input is required.
`'ImportMode'`	`0` – Import XML into a new model. `1` – Use XML to update contents of a model or subsystem. `2` – Add contents of new XML to a model or subsystem. `3` – Import contents of new XML into a model or subsystem and delete the existing contents. This input is optional. Default: `0`
`'ModelToImportInto'`	String specifying the target model for importing or updating existing blocks. This input is optional. Default: Original CAD assembly name
`'SubsystemToImportInto'`	String specifying the target subsystem for importing or updating existing blocks. This input is optional.
`'CreateTopSS'`	`true` or `false` – Whether to create a new subsystem if the specified subsystem (`'SubsystemToImportInto'`) does not exist in the target model. Applies when `'ImportMode'` = 2. This input is optional. Default: `false`
`EnableIndvlBlkUpdCtrl`	`true` or `false` – Whether to respect the update settings of individual blocks. If false, then update all blocks regardless. This input is optional. Default: `true`
`'LayoutDirection'`	`'LR'` – Diagram grows from left to right. `'TB'` – Diagram grows from top to bottom. This input is optional. Default: `'LR'`
`'LayoutWithUpdate'`	`true` or `false` – Whether to arrange all the imported blocks after updating their parameters. Applies only when updating. This input is optional. Default: `false`
`'UseDefaultJointNames'`	`'on'` – Use default joint names like Revolute1, Revolute2, etc., and ignore joint names specified in the Physical Modeling XML file. `'off'` – Use the joint names from the Physical Modeling XML file. This input is optional. Default: `'on'`
`'UseBlockNamesForSpacing'`	`'on'` – Space blocks so that their names do not overlap. `'off'` – Use only block size to space blocks. This input is optional. Default: `'off'`
`'BackupMode'`	`0` – Do not create a backup updating an existing model. `1` – Create a backup in the same folder as the model. `2` – Specify a name for the backup and a location. This input is optional. Default: 1
`'BackupLocation'`	Specify the complete path where the backup should be created. Applies when `'BackupMode'` = 2. This input is optional.

In the Import Dialog Box

If you enter mech_import at the command line with no inputs, the Import Physical Modeling XML dialog box opens. This dialog box provides the same control over generating SimMechanics models from Physical Modeling XML files as does the function with inputs.

Enter your settings in the dialog box first. Click Apply to apply these settings. Click OK to complete the function input and start the file import. Click Cancel to stop the file import.

Caution MATLAB uses the last set of import options that you set in this dialog box and not the default options.

The dialog box has two tabs, Import and Advanced Options.

Import Tab

The Import tab has several active areas: the XML File field, the Import mode selection area, and two specifications for import into existing models/subsystems.

XML File

Enter the name of a Physical Modeling XML file, including its absolute path on your system. This field replaces the filename input of the mech_import function. There is no default name. If you do not specify an absolute path, the importer searches for the file on the MATLAB path and in the current MATLAB folder.

You can search for files with a file browser by clicking the ... button. Clicking this button opens a file browser in the current working folder. Close the file browser by clicking Open or Cancel.

If you click Open in the file browser, the selected name is copied to the File field. The name includes the file's absolute path on your operating system.

Reset to default settings

Click this button to restore the import dialog box settings to their defaults. See Inputs preceding.

Import Mode

Choose how you want to import the specified XML file as a SimMechanics model. The choices are mutually exclusive.

Import into new model

Select this option to create a new model from the specified XML file.

Update existing model

Select this option to use the specified XML file to update an existing model.

By default, the importer updates the model with the same name in the XML file. If you want to specify a different model, different subsystem, or both, use the Specify model to import into and Specify subsystem to import into options following.

Add to existing model

Select this option to use the specified XML file to add to an existing model.

By default, the importer adds to the model with the same name in the XML file. If you want to specify a different model, different subsystem, or both, use the Specify model to import into and Specify subsystem to import into options following.

Import into existing model (replace model or subsystem contents)

Select this option to use the specified XML file to replace contents of an existing model or subsystem.

By default, the importer replaces contents in the model with the same name in the XML file. If you want to specify a different model, different subsystem, or both, use the Specify model to import into and Specify subsystem to import into options following.

Options for Importing into an Existing Model or Subsystem

With these options, you can choose:

A name for a newly created model or subsystem
The name of an existing model to import into, if you are working with an existing model
The name of an existing subsystem to import into, if you are working with an existing subsystem

Specify model to import into

If you want to specify the name of the model into which you want to import the Physical Modeling XML, select the check box. Use this option if:

You want to specify the name of a newly created model, instead of the default. The default is the model name specified in the XML file.
You want to specify the name of existing model whose contents are to be updated, added to, or replaced.

The Model name field is active if you select the check box. Specify the model name in the field. Click the browse button ... to the right to search on your system for a model file.

Specify subsystem to import into

If you want to specify the name of the subsystem into which you want to import the Physical Modeling XML, select the check box. (You must also specify a model name.) Use this option if:

You want to specify the name of a newly created subsystem, instead of the default. The default is the top level of the model you are importing into.
You want to specify the name of existing subsystem whose contents are to be updated, added to, or replaced.

The Subsystem name field is active if you select the check box. Specify the subsystem name in the field.

In the update or replace cases ('ImportMode' = 1 or 3), the subsystem to import into must already exist.
In the add-to case ('ImportMode' = 2), the subsystem to be added to, does not have to exist. If it does not, specify a subsystem name and select the Create new subsystem if it does not exist check box. This check box is present only when the import mode is set to Add to existing model.

Advanced Options Tab

The Advanced Options tab has several active areas: Update, Layout, and Backup. These options give you control over how model update-import proceeds, how to lay out model blocks, and how to create model backup copies.

Update

This area is active only if you choose Update existing model under Import mode on the Import tab preceding.

Arrange all updated blocks: Select this check box if you want the importer to arrange the layout of the updated blocks in the model block diagram being updated. The default is not selected.
Respect individual block update settings: Select this check box if you want the importer to use, on individual blocks in the model being updated, the settings that allow each block to be updated or prevent each block from being updated. The default is selected.

Layout

The area is active regardless of Import mode choice on the Import tab preceding.

Name joints by joint type: Select this check box to ensure that Joint blocks in the generated model have short default names. (For example, short default names of a set of revolute joints could be Revolute1, Revolute2, etc.) Clearing this check box applies the Joint block names from the imported XML file. These names might be long and take up more space in your model. The default is selected.
Ensure block names do not overlap: Select this check box to enlarge the spacing between blocks in the generated model if their names are long. Clearing this check box leads to block spacing based only on the block sizes, not on the block names. The default is not selected.
Layout direction: Select one of two block diagram growth directions in the generated model, Horizontal or Vertical. The default is Horizontal.

Backup

This area is active only if you choose one of the options to update, add to, or replace contents in an existing model. The backup copy of the updated model is the most recent version before the current update.

Backup mode

In the pull-down menu, choose one of these backup options:

Don't create backup – The importer does not save the previous version.
Create backup in same folder – The importer saves the previous version in the same folder as the updated version. The backup model name is existingmodelname_backup.mdl.
This option is the default.
Specify location to create backup – The importer saves the previous version in a folder that you specify.
If you choose this option, the Backup model location field and the ... file browser button following become active.

Backup model location

This field and the ... file browser button following become active only if you select Specify location to create backup in the Backup mode pull-down menu preceding.

Enter a location on your file system to place the saved previous version of your model. You can enter the location in the field manually, or search for a location with a file browser by clicking the ... button.

Outputs

mech_import produces or updates one model file.

The default output model name is the same as the assembly name specified in the Physical Modeling XML file. The output model name is independent of the name of the XML file used as the input.

Examples

Importing a New Model

Create the Physical Modeling XML file for a CAD assembly called assembly by exporting the assembly from your CAD platform. Call the file assembly.xml.

Then enter

mech_import('assembly.xml')

at the command line. SimMechanics software generates the block diagram in a model file called assembly.mdl. You can then save, rename, modify, and run the model.

Importing a New Model with a Nondefault Name

Change a model's name from the default

By use of the 'ModelToImportInto' option when you invoke the function, before importing (see Inputs preceding).
By use of the Specify model to import into field in the dialog box, before importing.
When you save the model, after importing.

Apply a nondefault name to a final generated model in this way:

mech_import('robot.xml','ImportMode',0, ...
           'ModelToImportInto','myrobot')

This form of the function imports the demo file robot.xml into a new SimMechanics model called myrobot.

Updating an Existing Model with Several Options

Update an existing model (existingModel) with the XML file existingModelUpdate.xml:

mech_import('existingModelUpdate.xml','ImportMode',1, ...
            'ModelToImportInto','existingModel', ...
            'LayoutWithUpdate',true,'EnableIndvlBlkUpdCtrl',true, ...
            'BackupMode',2,'BackupLocation','C:\backupdir\')

The importer arranges the updated blocks, while respecting the individual block update settings. The function also creates a backup copy and specifies a nondefault location (C:\backupdir\).