What to Watch Out for with Objects and Collections

Commands and methods generally behave in one of two ways:

They always return a valid object or collection. For example:
- The GetPrimCamera command or AddCamera method adds a camera to the scene and returns the new camera. The return value is always a valid object because the method always creates a new camera.
- The Geometry.Points property gets the collection of points from the object's geometry. The return value is always a valid collection because the any object implementing this property always contains a collection of points.
- The FindChildren and Filter methods always return valid collections that match the criteria specified. Even when it has no members, it still returns an empty but valid collection, unlike the SIFilter command.
They may return an invalid object or collection. For example:
- The SIFilter command takes an existing list as input and returns a subset of its members as a new collection that matches the criteria specified. If nothing matches the criteria, no valid collection is created. This behavior is different from the Filter methods which return a valid, empty collection if the criteria are not met.
- The FindChild or Find method takes input objects and returns the first thing that matches the criteria specified. If nothing matches, no valid object is returned.

Important

As you may suspect, your script will fail if you try to use an invalid object or collection (nothing). For this reason, you need to test the return value before trying to work with it any further. For more information, see Making Sure Returned Values are Valid.

Returning Values and Objects

Returning Data Values

Some commands and methods test objects to see whether a certain condition is true, so they return a boolean value which represents either True or False. For example, the IsAnimated command checks to see whether the object has animated parameters and the SIObject.IsEqualTo method checks to see whether the object is the same as some other item.

There are many others that perform some kind of mathematical calculation, so they return a numerical value. For example, the GetNbTriangles command returns the number of triangles (as a long) on a given object and the XSIMath.DegreesToRadians method converts an angle in degrees to radians (as a double).

Note

For more information on types, see What is ÔType'?.

Returning Objects

Most methods and some commands create individual scene items, so they return the name of the newly created object. For example, the CreatePrim command and the X3DObject.AddGeometry method both create 3D objects of the specified geometry type.

Tip

In these cases, if you are using VBScript you need to use the Set keyword before the variable name to get an object. For example, the CreatePrim command returns the primitive it creates. With the Set keyword, you get a pointer to the object (as an X3DObject):

Set oObj = CreatePrim( "Arc", "NurbsCurve" )
' TypeName(oObj) returns 'X3DObject'

Without the Set keyword, you get the name of the new object because the default property of an X3DObject is the Name property:

sRtn = CreatePrim( "Arc", "NurbsCurve" )
' TypeName(sRtn) returns 'String'

Other languages, such as JScript, implicitly assign the object type to the variable, so there is no need to use a special keyword.

// ClassName(oObj) will return 'X3DObject'
var oObj = CreatePrim( "Arc", "NurbsCurve );

Example: Returning objects using scripting commands

' Using the Set keyword allows you to create variables 
' that point to objects.
Set oSphere = CreatePrim("Sphere", "NurbsSurface")

Example: Returning objects using the object model

Set oRoot = ActiveProject.ActiveScene.Root
Set oSphere = oRoot.AddGeometry("Sphere", "NurbsSurface", "sphere")
LogMessage oSphere.Name & " has a position in X of " & oSphere.posx.Value

Simple Objects versus Collections

When you get a returned object, it is important to remember that it could be either a simple object or a collection. This affects how you test and use the returned object — for example, simple objects have Name and Type properties, while collections have Count and Item properties.

The default property for an object is the Name property, which means that when you use an object variable oSphere in a code statement, it can be interpreted either as oSphere or as oSphere.Name, depending on the context:

' These two LogMessage statements are equivalent
' since LogMessage is looking for a string
Set oSphere = CreatePrim( "Sphere", "NurbsSurface" )
LogMessage oSphere
LogMessage oSphere.Name

Note

For more information about objects, see About the Structure of the Softimage APIs.

The default property for a collection is the Item property, which means that when you use an object variable oOwners in a code statement, it can be interpreted either as oOwners or as oOwners.Item, depending on the context:

' These four LogMessage statements are also equivalent
' because the Item actually identifies the object 
' that is the first member of the collection, both
' are interpreted as oOwners.Item(0).Name
Set oSphere = CreatePrim( "Sphere", "NurbsSurface" )
Set oOwners = oSphere.Owners
LogMessage oOwners(0)
LogMessage oOwners(0).Name
LogMessage oOwners.Item(0)
LogMessage oOwners.Item(0).Name

To check whether the return value is an object or a collection

The following code tests to see whether a mystery object is a collection or a simple object.

' Continue processing if there is an error in the next block
On Error Resume Next

' Test to see if it is a collection
myCount = mysteryObj.Count
if (Err.Number = 0) then 
	if (myCount = 0) then
		LogMessage "Empty collection."
	else
		LogMessage "Collection contains:"
		for each myItem in mysteryObj
			LogMessage myItem.Name & " is a " & myItem.Type
		next
	end if
	
' Test to see if it is a simple object
else
	Err.Clear
	myName = mysteryObj.Name
	if (Err.Number = 0) then
		LogMessage "Object: " & myName & " is a " & mysteryObj.Type
	else
		LogMessage "Unknown"
	end if
end if

'Stop processing if there is an error in the remainder of the script
Err.Clear
On Error GoTo 0