Softimage SDK Programmer's Guide > Script Development > Data Types and Return Values >

# 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 Project Layers Layer_Default and Project Passes Default_Pass Background_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