Checking Return Values for Type

Checking to see what type of object you are working with can be very tricky, because there's a lot of "type" information to find in Autodesk Softimage SDK. For example, there's the ClassName (Application) property that every Softimage object implements, which differs from the ClassName (Application) method, which identifies which interface or class the item belongs to.

Note

The Application.ClassName method is similar to the VBScript TypeName function which returns the subtype, or what kind of scene item it is (such as X3DObject). The Application.ClassName method allows non-VBScript programmers to test for the interface name.

However, the behavior of the Application.ClassName method differs from the VBScript TypeName function in that TypeName can test for standard data type (string, boolean, integer, etc.) as well as class name but Application.ClassName cannot. For example, in JScript you would have to test with the typeof operator to figure out the data type of a return value.

The table below provides an overview of several Softimage objects and what they return depending on whether you are working with the Type property or the ClassName method:

Item to Test	What the Type Property Returns	What LogMessage Shows for Object.Type	What LogMessage Shows for ClassName(Object)
XSICollection	Softimage collection type.	"XSICollection"	"Object"
CollectionItem	Object type as a string. This could describe the kind of geometry, or indicate that it is a pass or a light or a camera, depending on what the CollectionItem is.	"camera", "polymsh", etc.	"CollectionItem"
Camera Rigs (Camera_Root, Telephoto_Root, etc.)	Primitive type (for camera rigs, there's only one type).	"CameraRoot"	"CameraRig"
Cameras (Camera, Telephoto, etc.)	Primitive type (for cameras, there's only one type).	"camera"	"Camera"
Light Rigs (Light_Box_Root, Spot_Root, etc.)	Primitive type. (for light rigs, there's only one type).	"SpotRoot"	"LightRig"
Lights (Light_Box, Spot, etc.)	Primitive type (for lights, there's only one type).	"light"	"Light"
OGLLight	Light type as an siLightType constant value: 0 for siLightPoint 1 for siLightInfinite 2 for siLightSpot 3 for siLightSun	"0", "1", "2", etc.	"OGLLight"
Passes (Default_Pass, etc.)	Object type (for passes, there's only one type).	"#Pass"	"Pass"
Layers (Default_Layer, etc.)	Object type (for layers, there's only one type).	"#Group"	"Layer"
Nulls	Primitive type.	"null"	"Null"
Mesh surface objects (cone, cube, cylinder, disc, grid, sphere, torus, *hedron, soccer ball)	Geometry type.	"polymsh"	"X3DObject"
Implicits (arc, circle, spiral, square, cone, cube, cylinder, disc, grid, sphere, torus)	Implicit type.	"arc", "circle", "cone", etc.	"X3DObject"
Nurbs surface objects (cone, cube, cylinder, disc, grid, sphere, torus)	Geometry type.	"surfmsh"	"X3DObject"
CurveList (arc, circle, spiral, square)	Geometry type.	"crvlist"	"X3DObject"
Primitive	Geometry type.	"polymsh", "surfmsh", "crvlist", etc.	"Primitive"
SubComponent	Subcomponent's Cluster type as a string. Format is: cluster_type + "SubComponent"	"pntSubComponent", "edgeSubComponent", "polySubComponent", etc.	"SubComponent"
Operator	Operator type. Note See Operator Presets for a list of available operators.	"twistop", "geom", etc.	"Operator"
FCurve	FCurve type as an siFCurveType constant: 0 for siUnknownFCurve 0 for siDefaultFCurve 10 for siBooleanFCurve 15 for siIntegerFCurve 20 for siStandardFCurve 30 for siRawDataFCurve	"0", "10", "20", etc.	"FCurve"
Geometry0D Geometry1D Geometry2D	Subcomponent's Cluster type as a string. Note These objects and their components are obsolete.	"pntSubComponent", "edgeSubComponent", "polySubComponent", etc.	"Geometry0D", "Geometry1D", "Geometry2D", etc.
Kinematics, Global / Local Transform, Scene_Material (specific parameter sets)	Parameter (property) set type.	"kine", "CompoundParameter", "material", etc.	"Kinematics", "KinematicState", "Material", etc.
Scene Colors, Ambient Lighting, Display, Geometry Approximation (general parameter sets)	Parameter (property) set type.	"Scenecolors", "AmbientLighting", "display", "geomapprox", etc.	"Property"
Parameters (PosX, Green, Length, U Subdivisions, etc.)	Parameter.	"Parameter"	"Parameter"
Constraints	Constraint name	"dircns"	"Constraint"
EventInfo	Event type as a string. For all Softimage events, this is XSIApplication.	"XSIApplication"	"EventInfo"

Tip

This list contains only a sample of the possible return values for the Type property. For specific information on Type and ClassName, see What Does the Type Property Test For? and What Does the ClassName Method Test For?.

What Does the Type Property Test For?

The Type property returns different kinds of information depending on the object you are checking. For example, if you are checking a 3d object or collection item, it returns the primitive type. If you are checking an fcurve or an OGL light, it returns a numeric value corresponding to the type of fcurve or OGL light.

Tip

For more information, see the comparison table at the beginning of Checking Return Values for Type.

Example: using the Type property

' Set up some items to test
Set oObj = ActiveSceneRoot.AddGeometry( "Cube", "MeshSurface" )
Set oColl = CreateObject( "XSI.Collection" )
oColl.Add oObj

' Is there any difference between the CollectionItem
' and the object it refers to?
printInfo oObj
printInfo oColl.Item(0)

' What about fcurves?
printInfo oObj.posx.AddFCurve

' Getting the operator type
ApplyOp "twist", oObj
Set oOpStack = oObj.ActivePrimitive.ConstructionHistory
For Each oOp in oOpStack
	printInfo oOp
Next

' Testing parameters and properties
printInfo oObj.Properties(0)
printInfo oObj.Parameters(0)

' What about the model?
printInfo ActiveSceneRoot

' Pass and Layer info
printInfo GetValue( "Passes.Default_Pass" )
printInfo GetValue( "Layers.Layer_Default" )

' CameraRig & primitive
Set oCamera = ActiveSceneRoot.FindChild( "camera" )
printInfo oCamera
Set oCameraRig = oCamera.Parent
printInfo oCameraRig

function printInfo( in_object )
	logmessage in_object.type
end function

' Output of above script is:
'INFO : "polymsh"
'INFO : "polymsh"
'INFO : "20"
'INFO : "twistop"
'INFO : "geom"
'INFO : "kine"
'INFO : "Parameter"
'INFO : "#model"
'INFO : "#Pass"
'INFO : "#Group"
'INFO : "camera"
'INFO : "CameraRoot"

What Does the ClassName Method Test For?

The ClassName method returns the name of the Softimage Object Model interface, or the most derived class (the leaf on the class hierarchy tree). This is similar to using the TypeName() function in VBScript, but this method is available to any language Softimage supports:

Example: calling the ClassName method using JScript

// JScript example : display the class name of an object
var oObj = ActiveProject.ActiveScene.Root.AddGeometry("Sphere", "NurbsSurface");
LogMessage( "Object typename = " + Application.ClassName(oObj) );

Example: testing both Type and ClassName on a sphere

For example, if you run the following code fragment:

' Set the workspace
Set oRoot = ActiveProject.ActiveScene.Root

' Create a polymesh sphere 
Set oSphere = oRoot.AddGeometry( "Sphere", _ "MeshSurface" )
Set oPrim = oSphere.ActivePrimitive

' Use the Type property (Softimage type)
LogMessage "Type property gives: " & oSphere.Type

' Use the ClassName method (interface name)
LogMessage "ClassName method gives: " & _ ClassName( oSphere )

The following messages appear in the History pane of the Script Editor:

' INFO : "Type property gives: polymsh"
' INFO : "ClassName method gives: X3DObject"

However, the Type property behaves differently depending on the object and the context. For more information on what the Type property is checking for, see What Does the Type Property Test For?.

Other Tests: BelongsTo, Owners, Parent, and Parent3DObject

The BelongsTo property accesses the family information (which family of objects the current object belongs to—for more information on families, see What are Families?).

The Owners property returns the parent object of the current object (that is, the parent as far as Autodesk Softimage is concerned)—for more information on owners, see What Are Parents And Owners?.

The Parent property returns either the parent object of the current object or the parenting geometry of the current subcomponent. Softimage knows whether the object you are asking about is an object or a subcomponent and returns the appropriate value.

The Parent3DObject property returns the parenting object of the current subcomponent—for more information on parents, see What Are Parents And Owners?.

For more information on objects and subcomponents, see Accessing Scene Elements.

What are Families?

Families are a way of linking objects that may share some properties or methods but aren't siblings in the object hierarchy. That is, the "family" sets up explicit relations between objects that do not fall on a straight line in the inheritance trees. To see a hierarchical representation of the object model, see the Object Model Hierarchy.

In simpler terms, the Autodesk Softimage SDK developers used the family to set up explicit relations between objects that share properties, methods, and events.

Tip

For a complete list of families see the documentation for the siFamily constant.

Example: finding the family of an action source

You can use the Families property to access the family information. In this example, the code fragment creates a simple action (so that there is an action source to find) and then uses the Families property to print a list of the families it belongs to:

' Set up my workspace
Set oRoot = Application.ActiveProject.ActiveScene.Root

' The commands create a simple actionsource from some ' animation on the nulls position
Set oNull = GetPrim( "Null" )
sPosParams = oNull & ".kine.local.posx," & oNull _
	& ".kine.local.posy," & oNull & ".kine.local.posz"
Translate oNull, -8.153, 7.015, -0.702, siRelative, _
	siView, siObj, siXYZ
SaveKey sPosParams, 1.000
Translate oNull, 8.350, -8.935, 0.894, siRelative, _
	siView, siObj, siXYZ
SaveKey sPosParams, 50.000
Translate oNull, 9.413, 8.935, -0.894, siRelative, _
	siView, siObj, siXYZ
SaveKey sPosParams, 100.000
StoreAction oRoot, sPosParams, 2, "StoredFcvAction", _
	True, 1, 100
	
' Get the action source from the model
Set oSources = oRoot.Sources

' Print the names and families of each source
For Each s In oSources
	LogMessage s.name & ": " & s.Families
Next

To find out the family information for the currently-selected object

' Test to see if the object is a 3D Object
If oSel.BelongsTo( "3D Object" ) Then
	LogMessage "BelongsTo property = True (for 3D Obj)"
Else
	LogMessage "BelongsTo property = False"
End If

' Print family id
LogMessage "Families property = " & oSel.Families

What Are Parents And Owners?

An object's parent is the node directly above that object in the Softimage hierarchy. An object can have only one parent, but its parent may also have a parent and so on up the explorer tree. For example, in this image, "cube3" is the parent of "sphere1" and "Scene_Root" is the parent of "cube3".

For subcomponents (points, segments, and facets), either the parenting geometry or the parenting object of that subcomponent can be considered its parent.

An object's owners are any other nodes in the Softimage hierarchy which use that object. Often the parent of an object may also be its owner. For example, in the image above, "cube3" is both a parent and an owner of "sphere1". In addition, "sphere1" is also a member of the default layer and the default background objects partition, so it appears under ProjectLayersLayer_Default and ProjectPassesDefault_PassBackground_Objects_Partition.

To find the owner of the currently-selected object

' Get the selection
Set oSelected = Selection

' Find the owner & print its name
For Each s In oSelected
	LogMessage s.Owners.Count & " owner(s) for " & s
	Set oOwner = s.Owners
	For i = 0 To oOwner.Count - 1
		Set o = oOwner(i)
		LogMessage "Owner #" & i + 1 & " is " & o
	Next
Next

To find the parent of the currently-selected object

' Get the selection
Set oSelected = Selection

' Find & print the parent's name of each selected item
For Each s In oSelected
		LogMessage s & "'s parent is " & s.Parent
Next

Important

When using the Parent property on the scene root, don't forget that the scene root gets returned because the root is the highest node in the scene hierarchy.

To find the parent information of the currently-selected subcomponent

' Get the selection (assuming it's a subcomponent)
Set oSelected = Selection(0)
Set oSubSel = oSelected.SubComponent

' Find the Parenting Geometry
LogMessage oSubSel & "'s parenting geometry is " & _
	oSubSel.Parent
	
' Find the Parent Object
LogMessage oSubSel & "'s parent object is " & _
	oSubSel.Parent3DObject

Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License