Model Class Reference

---

Detailed Description

The Model object represents any Softimage model node, including referenced models, and even the Scene Root. Softimage models act as a container for objects (usually hierarchies of objects) and many of their properties. Models are a type of X3DObject and as such can be positioned in space. A model can contain objects, Groups, or other models.

The Scene Root can be accessed using Application::GetActiveSceneRoot. In addition, any ProjectItem or Parameter can return a reference to the model in which it lives via the ProjectItem::GetModel and Parameter::GetModel functions.

You can also get list of all models under a given model by using X3DObject::GetModels (a Model is a specialized kind of X3DObject). Therefore, if you use GetModels on the Scene Root recursively, it returns all models in the active scene.

To create a new model, use X3DObject::AddModel, which also returns a Model object. There are also a few scripting commands which create model nodes as well: CreateModel, SICreateModel, etc.

You can also import or export models (including referenced models) with a series of commands: ImportModel, ExportModel, ImportRefModels, etc. When a referenced model is instantiated in the scene, changes to that model are tracked by the Delta system as of v6.0.

See also:

Group

Example:

Demonstrates how to work with groups in a model

        using namespace XSI;
        Application app;
        Model root = app.GetActiveSceneRoot();

        Null myNull;
        root.AddNull( L"MyNull", myNull );

        CRefArray groupMembersRef;
        groupMembersRef.Add(myNull);

        Group myGroup;
        root.AddGroup(groupMembersRef, L"MyGroup",false, myGroup);

        app.LogMessage( CString(L"The group: ") + myGroup.GetFullName() );

#include <xsi_model.h>

Inheritance diagram for Model:

List of all members.

Public Member Functions
	Model ()
	~Model ()
	Model (const CRef &in_ref)
	Model (const Model &in_obj)
bool	IsA (siClassID in_ClassID) const
siClassID	GetClassID () const
Model &	operator= (const Model &in_obj)
Model &	operator= (const CRef &in_ref)
CRefArray	GetGroups () const
CRefArray	GetSources () const
CStatus	AddGroup (const CRefArray &in_members, const CString &in_name, bool in_branch, Group &io_group)
Mixer	GetMixer () const
bool	HasMixer () const
ActionSource	AddActionSource (const CString &in_name=CString())
Mixer	AddMixer ()
CRefArray	GetExternalFiles () const
XSI::siModelKind	GetModelKind () const
Model	GetInstanceMaster () const
CSIObjectRefArray	FindObjects (const XSI::siClassID &in_nClsID) const
CSIObjectRefArray	FindObjects (const CString &in_sCLSID) const

---

Constructor & Destructor Documentation

Model

(

)

Default constructor.

~Model

(

)

Default destructor.

Model

(

const CRef &

in_ref

)

Constructor.

Parameters:

in_ref

constant reference object.

Model

(

const Model &

in_obj

)

Copy constructor.

Parameters:

in_obj

constant class object.

---

Member Function Documentation

bool IsA

(

siClassID

in_ClassID

)

const [virtual]

Returns true if a given class type is compatible with this API class.

Parameters:

in_ClassID

class type.

Returns:

bool true if the class is compatible, false otherwise.

Reimplemented from X3DObject.

siClassID GetClassID

(

)

const [virtual]

Returns the type of the API class.

Returns:

siClassID the class type.

Reimplemented from X3DObject.

Model& operator=

(

const Model &

in_obj

)

Creates an object from another object. The newly created object is set to empty if the input object is not compatible.

Parameters:

in_obj

constant class object.

Returns:

Model& New Model object.

Model& operator=

(

const CRef &

in_ref

)

Creates an object from a reference object. The newly created object is set to empty if the input reference object is not compatible.

Parameters:

in_ref

constant class object.

Returns:

Model& New Model object.

Reimplemented from X3DObject.

CRefArray GetGroups

(

)

const

Returns an array of references to all Group objects in the model.

Returns:

CRefArray array of references to Group objects in the model.

CRefArray GetSources

(

)

const

Returns an array of references to all Source objects in the model. Currently, the only sources available to the model are of type ActionSource, which is a specialized kind of Source object.

Audio and Image sources (which are basically references to audio and image files) are all stored under the Scene container (see Scene::GetExternalFiles).

Note:

Prior to v6.0, Model sources were also available using this property as a way to manage changes to reference models; however, this functionality is now provided by the Delta system.

Returns:

CRefArray array of references to data source objects in the model.

Example:

Demonstrates how to find all sources in the scene by using the Model.Sources property on every model returned from the X3DObject.Models property, given this structure:

           Scene_Root (Model)
               |- Herb (Model)
               |    |- Mixer (animation clip on null.posx)
               |    |- null  (null.size = FCurve)
               |
               |- Jesse (Model)
               |    |- Mixer (animation clips on null.scly,null.sclz,null.rotz)
               |    |- null
               |
               |- Sally (Model)
                    |- Mixer (audio clip)
                    |- grid (image on its texture projection)

        using namespace XSI;

        // Forward declarations
        CString GetRelativePath( Parameter& in_param );
        void MakeNewFCrvSource( Null& in_null );
        CRefArray FindSourcesUnderModel( Model& in_model );

        Application app;

        // NewScene command
        CValueArray cargs; CValue oarg;
        cargs.Add( L"" ); cargs.Add( false );
        app.ExecuteCommand( L"NewScene", cargs, oarg );
        cargs.Clear(); oarg.Clear();

        // Get the SceneRoot
        Model root = app.GetActiveSceneRoot();

        // Create a new model and add a null
        Model m; root.AddModel( CRefArray(), L"MyModel", m );
        Null n; m.AddNull( L"MyNull", n );

        // Add an fcurve ActionSource based on the new null
        MakeNewFCrvSource( n );

        // Find sources under the SceneRoot
        FindSourcesUnderModel( root );

        // Look under any other models
        CRefArray mdls = root.GetModels();
        for ( LONG i=0; i<mdls.GetCount(); ++i ) {
            Model m( mdls[i] );
            FindSourcesUnderModel( m );
        }


        // Expected results:
        //INFO : No sources found on Scene_Root
        //INFO : Sources.MyModel.StoredFcvAction is a ActionSource


        CRefArray FindSourcesUnderModel( Model& in_model )
        {
            Application app;
            CRefArray foundsrcs = in_model.GetSources();

           // Loop through the collection of sources found under this model to print the
           // name and add its name to the result string
           if ( foundsrcs.GetCount() > LONG(0) ) {
               for ( LONG i=0; i<foundsrcs.GetCount(); ++i ) {
                  Source src( foundsrcs[i] );
                  app.LogMessage( src.GetFullName() + L" is a " + src.GetClassIDName() );
               }
           } else {
               app.LogMessage( L"No sources found on " + in_model.GetFullName() );
           }

           return foundsrcs;
        }


        // Function to remove the name of the model from the FullName of the specified parameter.
        // This is necessary when setting up a source that will later be used to instantiate a
        // clip when the parameter lives under a model other than the Scene_Root.
        CString GetRelativePath( Parameter& in_param )
        {
            Model mdl = in_param.GetModel();
            CString mdlname = mdl.GetFullName();
            if ( mdlname.IsEqualNoCase(L"Scene_Root") ) {
                return in_param.GetFullName();
            } else {
                CString tmp = in_param.GetFullName();
                CString lookfor = mdlname + L".";
                CString foundsofar = L"";
                CString relpath = L"";
                for ( ULONG i=0; i<tmp.Length(); ++i ) {
                    if ( foundsofar.IsEqualNoCase(lookfor) ) {
                        relpath += tmp[i];
                    } else {
                        foundsofar += tmp[i];
                    }
                }
                return relpath;
            }
        }

        // Create a simple (fcurve) actionsource based on a null's position
        void MakeNewFCrvSource( Null& in_null )
        {
            Application app;
            Model mdl = in_null.GetModel();

            CTimeArray time; time.Add( CTime(1.000) ); time.Add( CTime(50.000) ); time.Add( CTime(100.000) );
            CValueArray vals;

            // X
            Parameter posx = in_null.GetParameter( L"posx" ); CString rposx = GetRelativePath(posx);
            FCurve fcx; posx.AddFCurve( siStandardFCurve, fcx );
            vals.Add( CValue(-8.153) ); vals.Add( CValue(0.197) ); vals.Add( CValue(9.413) );
            fcx.SetKeys( time, vals ); vals.Clear();

            // Y
            Parameter posy = in_null.GetParameter( L"posy" ); CString rposy = GetRelativePath(posy);
            FCurve fcy; posy.AddFCurve( siStandardFCurve, fcy );
            vals.Add( CValue(7.015) ); vals.Add( CValue(-1.92) ); vals.Add( CValue(7.015) );
            fcy.SetKeys( time, vals ); vals.Clear();

            // Z
            Parameter posz = in_null.GetParameter( L"posz" ); CString rposz = GetRelativePath(posz);
            FCurve fcz; posz.AddFCurve( siStandardFCurve, fcz );
            vals.Add( CValue(-0.702) ); vals.Add( CValue(0.192) ); vals.Add( CValue(-0.702) );
            fcz.SetKeys( time, vals );

            // Build an action with the fcurves as source items
            ActionSource src = mdl.AddActionSource( L"StoredFcvAction" );
            src.AddSourceItem( rposx, fcx, true );
            src.AddSourceItem( rposy, fcy, true );
            src.AddSourceItem( rposz, fcz, true );
        }

CStatus AddGroup	(	const CRefArray &	in_members,
		const CString &	in_name,
		bool	in_branch,
		Group &	io_group
	)

Creates a group in the model and adds objects to the group.

Parameters:

in_members	array of reference to members to add to the group.
in_name	name of the group.
in_branch	Add new members as branch members
io_group	Group that was added.

Returns:

CStatus::OK success

CStatus::Fail failure

Mixer GetMixer

(

)

const

Returns the active Mixer if there is one. If not, this method returns an invalid Mixer object. You can check its validity by using the CBase::IsValid method.

Returns:

Mixer

Since:

4.0

bool HasMixer

(

)

const

Returns true if there is a mixer nested directly under the model, false otherwise.

Returns:

bool true if there's an active Mixer for this Model.

Since:

4.0

ActionSource AddActionSource

(

const CString &

in_name = CString()

)

Adds an empty action source. In order to fill the ActionSource you must use ActionSource::AddSourceItem.

Parameters:

in_name

Name of the new action source

Returns:

ActionSource the newly created ActionSource object

See also:

ActionSource::AddSourceItem, AnimationSourceItem, AnimationSourceItem::SetAsStatic

Since:

4.0

Example:

See the AnimationSourceItem page for an example of how to create an empty ActionSource, populate it and then change the source.

Mixer AddMixer

(

)

Adds an empty Mixer object. If the current model does not have a mixer, this function fails and returns an invalid Mixer object.

Returns:

Mixer the newly created Mixer object

Since:

4.0

CRefArray GetExternalFiles

(

)

const

Returns the external file list for the model.

Returns:

Array of FileReference objects.

Since:

5.0

XSI::siModelKind GetModelKind

(

)

const

Returns the type of model. The type can be one of regular, referenced, or instance.

Returns:

The siModelKind type of model.

Since:

6.0

Model GetInstanceMaster

(

)

const

Returns the master model of this model, if this model is an instance. To check whether this model is an instance model, use Model::GetModelKind to query for the type.

Returns:

The master Model of this instance model (if applicable).

See also:

siModelKind

Since:

7.0

CSIObjectRefArray FindObjects

(

const XSI::siClassID &

in_nClsID

)

const

Returns all objects found in this model that match a class identifier. These identifiers are documented but can also be discovered by inspecting Softimage objects with the SDK Explorer. The supported class identifierss are the following:

• XSI::siAnnotationID
• XSI::siCameraID
• XSI::siClusterID
• XSI::siClusterPropertyID
• XSI::siConstraintID
• XSI::siCustomOperatorID
• XSI::siCustomPropertyID
• XSI::siEnvelopeID
• XSI::siEnvelopeWeightID
• XSI::siExpressionID
• XSI::siGeometryID
• XSI::siGroupID
• XSI::siICETreeID
• XSI::siLightID
• XSI::siMaterialID
• XSI::siModelID
• XSI::siNullID
• XSI::siNurbsSurfaceMeshID
• XSI::siNurbsCurveListID
• XSI::siOperatorID
• XSI::siPolygonMeshID
• XSI::siPropertyID
• XSI::siShaderID
• XSI::siShapeKeyID
• XSI::siX3DObjectID

Parameters:

in_nClassID

An object class id as defined in XSI::siClassID.

Returns:

CSIObjectRefArray Array of objects.

See also:

Application::FindObjects

Since:

9.5 (2011)

Example:

        using namespace XSI;
        Application app;

        // Returns all 3d objects in the scene as X3DObjects objects
        Application app;
        CSIObjectRefArray objArray = app.GetActiveSceneRoot().FindObjects( siX3DObjectID );
        for ( LONG i=0; i<objArray.GetCount(); i++ )
        {
            app.LogMessage( "X3DObject: " + objArray[i].GetFullName() );
        }

        // Returns all lights found in model 'A' as Light 3D objects.
        Model modelA = app.GetActiveSceneRoot().GetModels().GetItem( "A" );
        objArray = modelA.FindObjects( siLightID );
        for ( LONG i=0; i<objArray.GetCount(); i++ )
        {
            app.LogMessage( "Lights: " + objArray[i].GetFullName() );
        }

CSIObjectRefArray FindObjects

(

const CString &

in_sCLSID

)

const

Returns all objects found in this model that match a Softimage object CLSID. Object CLSID are not documented but can be discovered with XSIUtils.DataRepository or by inspecting Softimage objects with the SDK Explorer.

Parameters:

in_sCLSID

An object CLSID.

Returns:

CSIObjectRefArray Array of objects.

See also:

Application::FindObjects

Since:

9.5 (2011)

Example:

        using namespace XSI;
        Application app;
        
        // Find all lights in model 'A'
        Model modelA = app.GetActiveSceneRoot().GetModels().GetItem( "A" );
        CSIObjectRefArray lights = modelA.FindObjects( "{F3705C30-5204-11D0-8298-00A0243E366B}" );

        for ( LONG i=0; i< lights.GetCount(); i++ )
        {
            app.LogMessage( "Light: " + lights[i].GetFullName() );
        }

---

The documentation for this class was generated from the following file:

• xsi_model.h