Scripting: ImportModel

ImportModel

Description

Imports a model from an .emdl file. To execute this command a .emdl file is required.

By default the model is imported as a regular model, but if the argument Reference is True, the model will be imported as a referenced model. When importing a referenced model, the model is loaded in the scene but a referenced model is never saved with a scene. Each time a scene that contains referenced models is loaded, all referenced models are imported from their original location.

Note: There is a preference to add a prefix (referenced_) to the model name when importing a referenced model. The option is turned on by default. The preference is located under: preferences.General.refmodelprefix

You can access this command from the main menu in File->Import->Model.

This command supports the downloading of files off the internet. If the filename specified is a URL then the file will be downloaded locally before the command is executed.

Warning: This command is undoable since version 4, but note that when undoing an import model, only the model is deleted, all objects that are nested under a different container like materials, image clip, etc. are not deleted. You can use the different commands to cleanup un-used material or image clips. Undoing ImportModel on a referenced model has no effect.

Note: This command uses output arguments. C# and some scripting languages (such as JScript, PerlScript and Python) don't support arguments passed by reference so you need to use the best workaround for your situation:

For scripting languages this command returns an ISIVTCollection which you can use to get the output arguments.

For C# you can use the XSIApplication.ExecuteCommand method to call this command. ExecuteCommand packs the output arguments into a C# System.Object containing an Array of the output arguments (see Calling Commands from C#).

Scripting Syntax

ImportModel( FileName, [Parent], [Reference], [Value], [Name], [ShareOptions], [ExternalCnxMappingTemplate] );

Parameters

Parameter	Type	Description
FileName	String	Name of the model file to import.
Parent	String	Object or model to use as the parent of the imported model
Reference	Boolean	As of v6.0, this parameter is obsolete. To import model as a referenced model, use the CreateRefModel command instead. Default Value: False
Value	Model	Returns the model
Name	String	The name to give to the model imported
ShareOptions	siImportShareOptions	Bit field values of type Integer that specify the different options for sharing objects when importing a model. See siImportShareOptions to know what can be shared during model import. Sharing image clips: Image clips are identical if they refer to the same image source and all their parameters are equal, therefore FCurves on the parameters are ignored for the comparaison. Note that the image sources are always shared when importing a model. Sharing Materials: Materials are identical based on their name, their library, their number of shaders and their shaders' order. If we find a material with the same library.materialName, the same number of shaders which appear in the same order, we reuse it. Sharing Layers/Partitions: Layers and partitions are shared also based on their name. When the model is exported it remember the name of the layers and partitions for each objects, so when importing a model, and there is a layer or a partition with the same name the object goes in it. Referenced models share only image clips that are locked by referenced models, or if the image clip is unused. Standard models share only imageclips that are not locked at all. Default Value: siImportShareOptionsImageClips AND siImportShareOptionsLayers AND siImportShareOptionsPartitions
ExternalCnxMappingTemplate	String	This parameter contains a list of model separated by a comma, that is used to resolved the objects that we try to reconnect at the end of the import of referenced models. If this parameter is not null, the model is reconnected at the end of the import, else no reconnection is done. For referenced model only (when the parameter Reference is True): We always reconnect the model. If this parameter is null we will try to reconnect it to the original model name when the model was first exported.

Examples

1. VBScript Example

'---------------------------------------------------------
' VBScript example : Importing and exporting models using
' the ImportModel/ExportModel commands. Models and submodels
' are created and then exported and imported in this example.
'---------------------------------------------------------
' First create a model, a submodel, and primitives within them.
SICreateModel , "SubModel"
SICreateModel "SubModel", "Model"
CreatePrim  "Torus", "MeshSurface", "MyTorus", "SubModel"
CreatePrim  "Cube", "MeshSurface", "MyCube", "Model"
' Now export the models, once exporting submodels, and once not.
emdlFile = Application.InstallationPath( siUserPath ) & "\Model.emdl"
emdlSubFile = Application.InstallationPath( siUserPath ) & "\Model_with_Submodels.emdl"
ExportModel "Model", emdlFile, False
ExportModel "Model", emdlSubFile, True
' Now delete the models/primitives of the scene (so we can re-import them), 
DeleteObj "Model.SubModel.MyTorus"
DeleteObj "Model.SubModel"
DeleteObj "Model.MyCube"
DeleteObj "Model"
' Now import the exported files. One as a referenced model, the other not.
ImportModel emdlFile, , False, , "Model (no submodels, not referenced)"
ImportModel emdlSubFile, , True, , "Model (with submodels, referenced)"
'---------------------------------------------------------
'INFO : Output from this script:
'INFO : "4152 - Data loaded from file <UserPath>\Model.emdl was created with build number: <build_num> - compatibility version: 300"
'INFO : "4152 - Data loaded from file <UserPath>\Model_with_Submodels.emdl was created with build number: <build_num> - compatibility version: 300"
'INFO : Object: "Model___no_submodels__not_referenced_.MyCube"
'INFO : Object: "Model___with_submodels__referenced_.MyCube"
'INFO : Object: "Model___with_submodels__referenced_.SubModel.MyTorus"
'---------------------------------------------------------

2. VBScript Example

' This will import test.emdl as a ref model and reconnect envelop operators on deformers which are in model test2
ImportModel "T:\XSI_Project\Models\test.emdl", , True, ,,true, "test2"