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.

Inheritance Information

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"

Dependency Information

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.

Description

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):

Application.ActiveProject.ActiveScene.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)


Description

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"

X3DObject

Description

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,"

Primitive

Description

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


Description

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"

This page was last modified 18:56, 2 Nov 2010.
This page has been accessed 12507 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy