Object Model Diagrams
The diagrams in this section are simplified graphical representations of the relationships between the objects and their properties in the object model. You can think of them as learning aids for navigating through the object model in order to create usable code.
In this section, the following terminology is used to describe the relationships between objects in the object model:
Tree: the graphical representation of the object model as a hierarchy composed of branches, nodes, and leaves.
Node: an abstract object that gives access to other nodes or leaves below it. In terms of the object model, nodes add methods or properties to its dependents.
Leaf: a concrete object that forms the terminus of the tree branch. In terms of the object model, you can access a leaf through properties of the node above it.
Reading the Diagrams
The objects that are displayed in these diagrams can be used in your code statements (provided that you follow the basic rules of the scripting or programming languages that you have chosen to use). Each box represents an object in the SOFTIMAGE|XSI SDK object model, and contains both the object’s name (white background) and the text you need to use when you refer to the object in a code statement.
The dotted lines surrounding various objects on these diagrams indicate inheritance information (what properties and methods a particular class adds to the object model). Specifically, the labels indicate which object added the functionality, and the objects inside the dotted lines indicate what that functionality is. For example, the model diagram indicates that SIObject adds the parent and application properties to any of its children (which include most of the objects in the object model, incidentally). This code snippet demonstrates how you can create a NURBS sphere, and then find out and print the name of its parent:
Set oRoot = Application.ActiveSceneRoot Set oObj = oRoot.AddGeometry("Sphere", "NurbsSurface") Application.LogMessage oObj.Parent.Name ' Output of above script is: 'INFO : "Scene_Root"
For usability purposes, the inheritance information has been de-emphasized in these diagrams. This type of diagram is often referred to as a “Has A” tree because it shows how to access one object from another in a code statement, as opposed to an “Object Hierarchy”, which shows the properties and methods that are passed down (inherited) from one class of object to another object in the model.
These are the diagrams which represent the areas of the object model that are used most often:
Starting at the Beginning: The Application Level. Moving through the Guts: Exploring the XSI Object Model. Getting to the Glory: Examining the Geometry of a 3D Object.
To find out more about these objects, you can look them up by their object names (white background on the diagrams) under Objects in the Programmer's Reference section of the
|Table of contents|
Starting at the Beginning: The Application Level
This diagram illustrates the top of the XSI SDK object model. When you write a code statement that uses the object model, you need to build the statement starting at the top of the tree and wind down through the appropriate branches until you reach the actual collection, object, property, or method you want to work with.
This diagram is the starting point because you need to access the functionality of the object model though an element on this diagram. For example, you always begin every procedure by declaring where you are working (see Defining Your Workspace for more information). In order to do that, you need to refer to the model (root):
At another time you might need to find out what is currently selected in XSI. You can use the Selection object:
' Using the CreatePrim command automatically selects the newly-created object CreatePrim "Cone", "NurbsSurface" ' Get the selection and then print out all its members Set oSel = Application.Selection For Each oItem In oSel LogMessage "My name is " & oItem.Name Next ' Output of above script: 'INFO : "My name is cone"
Moving through the Guts: Exploring the XSI Object Model
The model is a kind of a launch pad, because the majority of XSI objects appear under the Scene Root, which is an XSI model. For this reason, you always need to include a reference to the root model when you define your workspace. From the root model, you can narrow your scope of interest along various paths.
An abstract object acts as a medium for a concrete object in coding, so that you can only use the names of leaves in your code and not the names of the nodes. That is, you explicitly use leaves by naming them and implicitly use abstract objects by using the functionality of their methods and properties.
|Object Name||Description||Abstract or Concrete?|
|Model||Gives access to model-level collections like groups and sources.||Concrete (Leaf object)|
|ProjectItem||Gives access to what the ProjectItem object adds, project-level items like the lists of owners and parameters, or a nested model.||Abstract (Node object)|
|SceneItem||Gives access to what the SceneItem object adds, scene-level items like global and local properties, materials, and the model’s envelopes.||Abstract (Node object)|
|Primitive||Gives access to what the Primitive object adds, like the primitive’s geometry or a list of operators.||Concrete (Leaf object)|
|X3DObject||Gives access to what X3DObject adds, like collections of 3D objects, primitives, and nested models, as well as animation (both a concrete and abstract object).||Abstract (Node object)|
|SIObject||Gives access to what SIObject adds, like the parent and application objects.||Abstract (Node object)|
Example: accessing groups
You can create a group and add a cube to it:
Set oRoot = ActiveSceneRoot Set oGroup = oRoot.AddGroup Set oCube = oRoot.AddGeometry( "Cube", "MeshSurface") oGroup.AddMember oCube For Each oMember in oGroup.Members LogMessage oMember.Name & " is a member of the " _ & oGroup.Name Next ' Output of the above script: 'INFO : "cube is a member of the Group"
Example: finding out an object’s parent
You can create a Mesh Surface sphere and access its parent:
Set oRoot = ActiveSceneRoot Set oObj = oRoot.AddGeometry( "Sphere", "MeshSurface") LogMessage "The parent of " & oObj.Name & " is " & oObj.Parent.Name ' Output of the above script: 'INFO : "The parent of sphere is Scene_Root"
Example: finding out who owns branch material
You can find out which objects own the material for the entire branch of the cylinder you just created:
Set oRoot = ActiveSceneRoot oRoot.AddGeometry "Sphere", "MeshSurface" oRoot.AddGeometry "Torus", "MeshSurface" Set oCyl = oRoot.AddGeometry("Cylinder","MeshSurface") Set oMat = oCyl.Material LogMessage "The material on " & oCyl & " belongs to: " For Each oOwner in oMat.Owners LogMessage oOwner.Name Next ' Output of above script: 'INFO : "The material on cylinder belongs to: " 'INFO : "Scene_Root" 'INFO : "Camera_Root" 'INFO : "Camera" 'INFO : "Camera_Interest" 'INFO : "light" 'INFO : "sphere" 'INFO : "torus" 'INFO : "cylinder"
Example: getting parameter values
You can access the position in Y of a NURBS cube:
' Set up a cube Set oCube = ActiveSceneRoot.AddGeometry( "Cube", "MeshSurface" ) ' I can get the position in Y the long way... Set oPosition = XSIMath.CreateVector3 oCube.Kinematics.Local.Transform.GetTranslation oPosition LogMessage "Y = " & oPosition.Y ' ...the shorter way... set oYPos = oCube.Kinematics.Local.Parameters("posy") LogMessage "Y = " & oYPos.Value ' ...or I can use the PosY shortcut LogMessage "Y = " & oCube.PosY.Value ' Either way the output's the same: 'INFO : "Y = 0" 'INFO : "Y = 0" 'INFO : "Y = 0" Example: accessing scene properties ' You can access the first property in your scene Set oProperty = ActiveSceneRoot.Properties.Item(0) Application.LogMessage oProperty.FullName ' Or you can access a specific property by name Set oProp = ActiveSceneRoot.Properties.Item( "Geometry Approximation" ) Application.LogMessage oProp.FullName ' Output of above script: 'INFO : "Scene_Root.kine" 'INFO : "Scene_Root.geomapprox"
Predicting what name to use to call your property can be a bit tricky: the name that you see in the scene explorer is what you would use to pass to XSI in a scripting command, but you need to pass a different to XSI as a key when using PropertyCollection.Item.
Both of these names are stored on the object model: you can access the name to use with scripting commands from the FullName property; and you can access the name to use with the object model from the Name property.
For information (and a sample script) on how to extract all the property and parameter information belonging an object, see To print out a list of information on all parameters on an object.
Example: accessing envelope weights
This example demonstrates how to get at envelope weights as a 2-dimensional array where there is a row for each cluster element and the columns contain the deformer weights.
' Set up the envelope and the chain root set oRoot = Application.ActiveProject.ActiveScene.Root set oSphere = oRoot.AddGeometry( "Sphere", "MeshSurface") set oChainRoot = oRoot.Add3DChain ' Apply an envelope to the geometry set oEnvelope = oSphere.ApplyEnvelope( oRoot, siBranch ) ' Get the 2D array of element/deformer weights aWeights = oEnvelope.Weights.Array ' Log weights for the first 4 elements for iElement=lbound(aWeights,2) to 3 strElementWeights="" for iDeformer=lbound(aWeights,1) to ubound(aWeights,1) strElementWeights = strElementWeights & aWeights(iWeight,iElement) & "," next logmessage "weight(" & iElement & ") = " & strElementWeights next ' After manipulating the weight values in the array, ' you can save the new values back to the envelope oEnvelope.Weights.Array = aWeights ' Output of above script: 'INFO : "weight(0) = 50,50,50,50,50,50,50,50,50," 'INFO : "weight(1) = 32.0954895019531, 32.0954895019531, 32.0954895019531, ' 32.0954895019531, 32.0954895019531, 32.0954895019531, ' 32.0954895019531, 32.0954895019531, 32.0954895019531," 'INFO : "weight(2) = 50,50,50,50,50,50,50,50,50," 'INFO : "weight(3) = 50,50,50,50,50,50,50,50,50,"
Example: accessing operators in a stack
You can print the names of all the operators in the stack (the ConstructionHistory object acts like an Operator stack):
' Set up the cube and apply a couple of operators to it set oRoot = ActiveProject.ActiveScene.Root set oCube = oRoot.AddGeometry( "Cube", "MeshSurface" ) ApplyOp "Bulge", oCube, 3, siPersistentOperation ApplyOp "Twist", oCube, 3, siPersistentOperation ApplyOp "Shear", oCube, 3, siPersistentOperation ' You get the operator stack (construction history) from the cube's primitive set oPrim = oCube.ActivePrimitive set oStack = oPrim.ConstructionHistory ' With the ConstructionHistry object there's no Item property, so you have ' to check every member to see if it's the one you want for each oOperator in oStack if oOperator.Name = "Bulge Op" then ' At this point, you can manipulate the operator if oOperator.Port( "Port_3" ).IsConnected then LogMessage oOperator.Name & " is connected to " _ & oOperator.Port( "Port_3" ).Target.Name end if ' Once you are done with it, you can ' just exit the loop exit for end if next ' Output of above script: 'INFO : "Bulge Op is connected to Global Transform"
Getting to the Glory: Examining the Geometry of a 3D Object
This diagram displays what is available in the object model with respect to the geometry of 3D objects. The object model gives you access to the low-level objects (components) listed in the following table:
|Geometry||Components (Points, Segments, Facets)|
|Polygon Mesh||Vertices, Edges, Polygons, Polygon Nodes|
|Nurbs Surface Mesh||Control Points, N/A, Surfaces, UKnots, VKnots|
|Nurbs Curve List||Control Points, N/A, Curves, Knots|
Example: accessing the surface of a NURBS sphere
For example, if you want to access the surface of a NURBS sphere, you can use these statements:
Set oRoot = ActiveSceneRoot Set oSphere = oRoot.AddGeometry( "Sphere", "NurbsSurface" ) Set oNurbsSurfaceMesh = oObject.ActivePrimitive.Geometry Set oNurbsSurface = oNurbsSurfaceMesh.Surfaces(0) Example: accessing clusters You can access clusters through the geometry property. Clusters are returned as a collection, which you can then enumerate. set oRoot = Application.ActiveProject.ActiveScene.Root set oObj = oRoot.AddGeometry( "Cube", "MeshSurface" ) set oCluster = oObj.ActivePrimitive.Geometry.AddCluster( siVertexCluster ) set oCluster2 = oObj.ActivePrimitive.Geometry.AddCluster( siPolygonCluster ) set oGeometry = oObj.ActivePrimitive.Geometry for each oCls in oGeometry.Clusters LogMessage oCls.FullName & " has " & oCls.Elements.Count & " elements" next ' Output of above script: 'INFO : "cube.polymsh.cls.Polygon has 6 elements" 'INFO : "cube.polymsh.cls.Point has 8 elements"
Example: accessing texture uv’s
This code demonstrates how to create a cube and add a UV texture support to it so that it can print the coordinates for the texture UV points:
set oRoot = Application.ActiveProject.ActiveScene.Root set oObject = oRoot.AddGeometry( "Cube", "MeshSurface" ) BlendInPresets "Image", oObject, 1, False CreateTextureSupport oObject, siTxtUV, siTxtDefaultSpherical, "Texture_Support" set oGeom = oObject.ActivePrimitive.Geometry Set oSamplePoints = oGeom.Clusters.Filter( siSampledPointCluster ) strUVProperty = oObject.Material.Parameters("UV").Value ' Find uvprop for list of sample points for each oSample in oSamplePoints set oUVWProp = oSample.properties(strUVProperty) if TypeName( oUVWProp ) <> "Nothing" Then exit for end if next ' Output the first 5 UV text coords aUVW = oUVWProp.Elements.Array for iIndex = 0 to 4 LogMessage "UV(" & aUVW(0,iIndex) & "," & aUVW(1,iIndex) & ")" next ' Output of above script: 'INFO : "UV(0.125,0.304086714982986)" 'INFO : "UV(0.125,0.695913255214691)" 'INFO : "UV(-0.125,0.695913255214691)" 'INFO : "UV(-0.125,0.304086714982986)" 'INFO : "UV(0.125,0.304086714982986)"
Example: accessing particles
Although the object model at this time has no mechanism to create particle clouds and associate emitters with them, you can still use the native XSI commands to create these objects. Once you have created these objects, you can access information about them and control some of their properties through the object model.
This example demonstrates how to create the particle cloud and emitter and then change the color values on the first particle in the cloud.
' Setup particle cloud with emitter set oParticleCloud = CreateParticleCloud() set oParticleEmitter = CreatePrim( "Sphere", "MeshSurface", "ParticleEmitter" ) AddParticleEmitter oParticleCloud, oParticleEmitter ' Get particles in cloud set oRoot = ActiveProject.ActiveScene.Root set oCloud = oRoot.FindChild( ,"cloud" ) set oParticles = oCloud.Particles set oColor = oParticles.Find(0).Color ' Print color info on first particle LogMessage "First particle has the following color values:" LogMessage " ... Red = " & oColor.Red LogMessage " ... Green = " & oColor.Green LogMessage " ... Blue = " & oColor.Blue LogMessage " ... Alpha = " & oColor.Alpha ' Change color values LogMessage "Changing first particle color now..." oColor.Green = 0.67 oColor.Alpha = 0.05 ' Print out new color values LogMessage "First particle now has the following color values:" LogMessage " ... Red = " & oColor.Red LogMessage " ... Green = " & oColor.Green LogMessage " ... Blue = " & oColor.Blue LogMessage " ... Alpha = " & oColor.Alpha ' Output of above script: 'INFO : "First particle has the following color values:" 'INFO : " ... Red = 1" 'INFO : " ... Green = 1" 'INFO : " ... Blue = 0.498039245605469" 'INFO : " ... Alpha = 1" 'INFO : "Changing first particle color now..." 'INFO : "First particle now has the following color values:" 'INFO : " ... Red = 1" 'INFO : " ... Green = 0.67" 'INFO : " ... Blue = 0.498039245605469" 'INFO : " ... Alpha = 0.05"