Softimage SDK Programmer's Guide > Script Development > Introduction to Scripting in Softimage >

# Using the Softimage Object Model for Novices

Using the object model to write code usually consists of three steps:

1. Indicate where you are working—see Defining Your Workspace.

2. Identify what you are working on—see Identifying Your Object.

3. Explain what you want to do with it or know about it—see Getting and Setting Object Data.

For more information on using the components of the object model, see individual help in the C++ API Reference or the Commands and Scripting Reference.

Defining Your Workspace

The first thing you need to indicate is where to look for the object you want to deal with. Typically you start at the scene root.

To get the root model of the scene

- The Application object contains a property that accesses the root directly:

      Application.ActiveSceneRoot

  Note

  If your script is running inside Softimage, using the word Application is optional. This is because the Application object is global. That means that these two statements are equivalent:

      ActiveSceneRoot
      Application.ActiveSceneRoot

  Tip

  Use a Set statement to assign objects to variables, so that you can refer to them quickly in the rest of your procedure. You can combine Set statements to suit your needs. The following statement gets an object pointer to the scene root:

      set oRoot = ActiveSceneRoot

To get the active scene

- You can access the ActiveScene property on the Project object:

      Application.ActiveProject.ActiveScene

To get the active project

- You can access the ActiveProject property on the Application object:

      Application.ActiveProject

Identifying Your Object

After indicating where to look, you need to identify which object you want to work with. This process is different depending on whether you need to add an object to the scene or work with an existing object.

Adding Something to Your Scene

You can add a 3D object to your scene by using a method of whatever object will be its parent (typically the root model). For example, if you want to create a polygon mesh sphere, you need to use the AddGeometry method of the root model object:

    Set oSphere = ActiveSceneRoot.AddGeometry( "Sphere", "MeshSurface" )

You can also use scene items themselves as parents of other objects. For example, if you want to add a phong material to your new sphere, you could add this statement to the previous one:

    Set oMaterial = oSphere.AddMaterial("Phong")

Working with an Existing Softimage Object

To find objects in the scene, you need to use the FindChild or FindChildren method of the model you want look under. Both of these methods allow you to use several different ways of searching (criteria); the only difference is that FindChild returns the first object it finds that matches the criteria, and FindChildren returns a collection of every object that matches.

You can search using any of these criteria:

- Name—the name of the object as a string expression. This can include wildcards, so that any object beginning with "co*" is a potential match.

- Type—the type of the object as a string or a constant. For a list of possible values, see the siType constant reference page.

- Family—the name of the family to which the object belongs. A family is a group of objects that are connected. They may be loosely connected (Geometries) or a very similar type (Topology Operators). For a list of possible values, see the siFamily constant reference page.

  Note

  The other parameter you can specify is Recursive, which is a Boolean (meaning it can be only False or True) value. If you specify False here, the method searches only the current object's children; otherwise, all of its dependents are also searched.

To access the first object starting with "cube"

    	' Set up the scene with a cube
    	set oRoot = ActiveSceneRoot
    	oRoot.AddGeometry "Cube", "MeshSurface", "cubeist"

    	' Find the first thing starting with "cube"
    	Set oCube = oRoot.FindChild( "cube*" )
    	' Here's a check to make sure that an empty object doesn't crash the script
    	if Application.ClassName( oCube ) <> "Nothing" then
    		Application.LogMessage "Found " & oCube.Name
    	else
    		Application.LogMessage "Couldn't find it... Sorry."

    	end if
    	' Script outputs the following:
    	'INFO : "Found cubeque"

Tip

Notice that because this example uses the Name parameter with a wildcard, this method might return "cube", "cube99", or "cubeist", depending on what it finds first.

To access all lights under the scene root using the Type parameter

    	Set oLights = ActiveSceneRoot.FindChildren( , "light" )
    	' Once you get the collection of lights you can loop through it
    	' Here's another check to make sure the collection isn't empty
    	if oLights.Count > 0 then
    	   Application.LogMessage "Found the following member(s)..."
    	   For Each oMember in oLights
    	      Application.LogMessage vbTab & oMember
    	   Next
    	else
    	   Application.LogMessage "Couldn't find it... Sorry."
    	end if

    	' Script outputs the following:
    	'INFO : "Found the following member(s)..."
    	'INFO : "	light"

Tip

Notice that this example uses the string name of the Light primitive type. You could also use the name of the constant instead too: siLightPrimType (without quotation marks).

To find the number of null primitives in the scene

    ' Set up two nested nulls under the scene root
    set oRoot = ActiveSceneRoot
    set oNested = oRoot.AddNull("Nodule")
    oNested.AddNull

    ' Starting at the lower nested level, look for any nulls underneath
    printFindResults oNested
    ' Then look at the scene root
    printFindResults oRoot

    function printFindResults( in_object )
       set oNullColl = in_object.FindChildren( ,,siNullPrimitiveFamily )

       ' Check to make sure empty collections won't crash the script
       if oNullColl.Count > 0 then
          LogMessage "There are " & oNullColl.Count & " null primitives under " _
                  & in_object.Parent.Name & ":"
          for each oNP in oNullColl
             LogMessage vbTab & oNP.Name & " is nested under " & oNP.Parent.Name
          next
       else
          LogMessage "Couldn't find it...Sorry."
       end if
    end function

    ' Output of above script:
    'INFO : "There are 2 null primitives under Scene_Root:"
    'INFO : 	"Nodule is nested under Scene_Root"
    'INFO : 	"null is nested under Nodule"
    'INFO : "There are 4 null primitives under Scene_Root:"
    'INFO : 	"Camera_Root is nested under Scene_Root"
    'INFO : 	"Camera_Interest is nested under Camera_Root"
    'INFO : 	"Nodule is nested under Scene_Root"
    'INFO : 	"null is nested under Nodule"

Working with Parameters

Getting Information about a Specific Object's Parameters

Some parameters are defined directly on an object (that is, there is no organizing parameter/property set to go through first) and some are accessible only through the parameter set (also known as a property).

You can get all the information about an object's parameters by accessing the ParameterCollection either directly from the object or through each member of the PropertyCollection.

The following example pulls all the parameter names and descriptions out of Softimage and dumps the information in a text file on your hard drive.

To print out a list of information on all parameters on an object

Copy and paste this script into the Softimage Script Editor and run it. Once it's done you can view the information is written in the textfile in this location: C:\Temp\Camera_Parameter_List.txt.

    ' First get the camera
    set oCamera = ActiveSceneRoot.FindChild( ,siCameraPrimType )

    ' Check to make sure it found something (prevent it from crashing)
    if ClassName( oCamera ) <> "Nothing" then
       ' Write some headers to identify the start and end of
       ' the list of parameters
       sOutput = "========================================" & _
    	 "========================================" & vbLf
       sOutput = sOutput & 	"PARAMETERS directly on the " & _
             oCamera.Name & " object......" & vbLf
       sOutput = sOutput & "----------------------------------------" & _
             "----------------------------------------" & vbLf

       ' Print out the information for each parameter
       for each oParam in oCamera.Parameters
          sOutput = sOutput & oParam.ScriptName & ": " & vbTab & _
    	    "(" & oParam.Name & ")" & vbTab & _
    	    oParam.Description & vbLf
          next

          for each oProp in oCamera.Properties
    	 ' Write some headers to identify the start and end of
    	 ' the list of parameters
    	 sOutput = sOutput & "----------------------------------------" & _
                        "----------------------------------------" & vbLf
             sOutput = sOutput & 	"PARAMETERS on the " & oCamera.Name & "." & _
    	          oProp.Name & " property......" & vbLf
             sOutput = sOutput & "----------------------------------------" & _

                        "----------------------------------------" & vbLf
             ' Print out the information for each parameter
    	 for each oParam in oProp.Parameters
    	    sOutput = sOutput & oParam.ScriptName & ": " & vbTab & _
    	          "(" & oParam.Name & ")" _
                  & vbTab & oParam.Description & vbLf
             next
          next
    	' Write a footer to identify the end of the file
            sOutput = sOutput & "========================================" & _
                      "========================================" & vbLf
    end if

    ' Write the output to the external file
    set fso = CreateObject( "Scripting.FileSystemObject" )
    set ts = fso.CreateTextFile( "C:\Temp\Camera_Parameter_List.txt", true )
    ts.Write sOutput
    ts.Close

    ' Just so you know when it's done
    Application.LogMessage "Output complete."

Accessing a Specific Parameter by its Name with the Object Model

A lot of script writers use the automatic logging feature of the History Log to give the correct command syntax for certain commands in the scripts they want to write. Some also activate the Use Script Names feature from the Show menu in the Softimage explorer so that they can see how to refer to each object in scripting.

However, the object model uses a different way to access objects and parameters. What the History Log of the Script Editor shows is the object and parameter names (generally called String Expressions) that can be used with commands, but not necessarily with the object model. The object model uses its own set of object and parameter names, some of which have shortcuts.

If you want to use the object model, it's a little more involved, but it makes sense once you know what to look for. You just traverse down the hierarchy as it appears in the explorer.

To get the camera visibility property (parameter set)

    ' First get the camera (Camera object)
    set oCamera = ActiveSceneRoot.FindChild( , siCameraPrimType )

    ' Underneath the camera are its properties (Properties returns the
    ' PropertyCollection)
    set oProps = oCamera.Properties

    ' Once you have all the property sets (PropertyCollection) you can specify the
    ' one you want (the Property object is returned)
    set oVis = oProps( "visibility" )

    ' Now we have a single Property (property set), so we need to get all the
    ' parameters for that property set (Parameters returns the ParameterCollection)
    set oParams = oVis.Parameters

    ' Again we choose the single parameter we want from the collection (the
    ' Parameter object is returned)
    ' NB: This is where what appears in the History Log comes into play...
    set oViewVis = oParams( "viewvis" )

    ' And once you have a single Parameter object, you can get it's value...
    ' (the line below returns 'INFO : "False")
    logmessage oViewVis.Value

    ' ...or set it...
    oViewVis.Value = true

    ' And you can make as many shortcuts as you like, so...
    oCamera.Properties( "visibility" ).Parameters( "viewvis" ).Value = false

What You Should Know about the Range of a Parameter

Using the object model to set parameters can bypass the maximum and minimum values allowed. Setting a value outside the allowable range can cause unpredictable results.

To avoid this, it's good programming practice to get the maximum and minimum allowable values for a parameter before you try to change them.

To find out what the range is for a given parameter

    ' Pick a number out of the air for the new value for a parameter
    dProposedValue = -10.00

    ' Set up an object and get its Display::Near Distance to
    ' Output Camera parameter
    set oNull = ActiveSceneRoot.AddNull()
    set oParam = oNull.Properties( "display" ).Parameters( "neardist" )

    ' Get the range of allowable values for this parameter
    dMaxValue = oParam.Max
    dMinValue = oParam.Min

    ' Now check the number you were going to use against the range
    if dProposedValue > dMaxValue then
       ' Here is where you write some code to handle it
       Application.LogMessage dProposedValue & " has exceeded the " _
             & "maximum value (" & dMaxValue & ") set for this " _
             & "parameter. Please adjust the value and try again."
    elseif dProposedValue < dMinValue then
       ' Here is where you write some code to handle it
       Application.LogMessage dProposedValue & " has not met the " _
             & "minimum value (" & dMinValue & ") set for this " _
             & "parameter. Please adjust the value and try again."
    else
       ' Here is where you update the parameter with your value
       oParam.Value = dProposedValue
       Application.LogMessage oParam.Name & "'s value = " & oParam.Value
    end if

    ' Output of above script:
    'INFO : "-10 has not met the minimum value (0) set for this parameter. Please adjust the value and try again."

Getting and Setting Object Data

Once you have identified the object you want to work with, you need to explain what you want to find out about it or what you want to do to it. For example, if you want to display the object's name in the history pane of the Script Editor, you could use the following:

    Set oRoot = ActiveSceneRoot
    Set oThing = oRoot.AddGeometry( "Cube", "MeshSurface" )
    Application.LogMessage oThing.Name  ' Getting information

    If you want to change the name of the object instead, you could use this code fragment:

    Set oRoot = ActiveSceneRoot
    Set oThing = oRoot.AddGeometry( "Cube", "MeshSurface" )
    oThing.Name = "Toybox"              ' Setting information