Using the object model to write code usually consists of three steps:
Indicate where you are working—see Defining Your Workspace.
Identify what you are working on—see Identifying Your Object.
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.
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.
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.
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"
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"
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"
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