Scripting: CreateRefModel

CreateRefModel

Introduced

v6.0

Description

Creates a referenced model in the scene. You can use this command to create a new instance of an existing model on disk or specify the name of a model file that does not yet exist. It also allows you to specify whether to activate the new model, what resolution to use, and under which model or object to parent it.

Scripting Syntax

oReturn = CreateRefModel( [FileName], [ModelName], [ResolutionName], [Parent], [Activate], [CreateFile], [ExternalCnxMappingTemplate], [ShareOptions] );

Return Value

The new referenced Model

Parameters

Parameter	Type	Description
FileName	String	If a filename is specified, it is loaded and used for the first resolution.
ModelName	String	The model name. Default Value: The name of the file (specified in Filename)
ResolutionName	String	The name of the first resolution. Default Value: res1
Parent	String	Object or model to use as the parent of the imported model Default Value: Scene Root
Activate	Boolean	True to import the model for the first resolution. If false, the model stays offloaded. Default Value: True
CreateFile	Boolean	If the file specified does not exist yet, this argument tells Softimage to automatically create a dummy model file (directories are also created). This is useful in a multiple-artist production pipeline to prepare the layout of a shot for a top-down approach before all the files exist. Default Value: False
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. The model is reconnected at the end of the import. If this parameter is null we will try to reconnect it to the original model name when the model was first exported.
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: siImportShareOptionsAll

Examples

1. JScript Example

/*
        This example shows how to create a referenced model based on an asset that doesn't exist 
        yet. This will create the file on disk, and create an offloaded referenced model.
*/
NewScene( null, false );
var sPath = XSIUtils.BuildPath( Application.InstallationPath(siUserPath), "Data", "alain.emdl" );
CreateRefModel( sPath, "alaind", "low", null, false, true) ;

2. JScript Example

/*
        This example shows how to create a referenced model based on a model that already exists.
        It also demonstrates how to activate it and specify a parent model.
*/
NewScene( null, false );
CreateModel( null, "mymodel" );
var sPath = XSIUtils.BuildPath( Application.InstallationPath(siFactoryPath), 
        "Data", "XSI_SAMPLES", "Models", "Man.emdl" );
CreateRefModel( sPath, "man", "low", "mymodel", true, false );