Using the Softimage Object Model for Novices

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