Accessing Parameter Values

If you are using scripting commands to work with parameter values, you can use the SetValue and GetValue commands. To use these commands, you need to know a parameter's scripting name—see Finding Parameter Names.

If you are using the object model, you can get and set the parameter values directly from the any project item by using the ParameterCollection.

Tip

With either of these two approaches, you can use Shortcuts, which provide a way to bypass the usual, more verbose style of specifying parameter names and are available on a select set of parameters. For more information, see Using Shortcuts.

Getting Parameter Values

To get the value of a parameter, first identify the object that you are interested in and then the parameter. You can then either store the value in a variable or work with the value directly.

You can use the GetValue command which takes the full name of the parameter as its argument like so:

rtn = GetValue( "light.Name" );

You can use the Parameter.Value property on the parameter like so:

// Get a pointer to the parameter first
var p = oObject.Parameters( "Name" );
rtn = p.Value;

// Or just get the value directly
rtn = oObject.Parameters( "Name" ).Value;

Whether you use commands or the object model, you need to figure out the full path to the parameter. For more information, see Finding Parameter Names.

Example: getting the camera's field of view angle using native Softimage commands

' Get an object containing the camera's fov
lFOV = GetValue( "Camera.camera.fov" ) 

' Display the value
LogMessage "Camera's field of view = " & lFOV

Example: getting the camera's field of view angle using the object model

' Get an object containing the camera's fov
set oCamera = ActiveSceneRoot.FindChild( "Camera" )

' Display the value
LogMessage oCamera.ActivePrimitive.Parameters( "fov" ).Value

' Or, the identical approach using shortcuts:
LogMessage oCamera.fov.Value

Example: getting the camera's position at a given frame using native Softimage commands

' Store the position value in a variable and then display the variable
iPos = GetValue( "Scene_Root.Camera.kine.local.pos.posx", 24 )
LogMessage "Camera's X position at frame 24 is " & CStr( iPos )

Example: getting the camera's position at a given frame using the object model

' Store the position value in a variable and then display the variable
set oCamera = ActiveSceneRoot.FindChild( "Camera" )
iPos = oCamera.Kinematics.Local.Parameters( "posx" ).Value(24)
LogMessage "Camera's X position at frame 24 is " &CStr(iPos)

Setting Parameter Values

Setting values is similar to getting values, except you also have to specify a value to set in addition to the reference to the parameter you want to change.

Setting a Value on a Single Parameter

You can use the SetValue command which takes the full name of the parameter as its first argument and the new value to apply like so:

SetValue( "light.Name", "Sparky" );

You can use the Parameter.Value property on the parameter like so:

// Get a pointer to the parameter first
var p = oObject.Parameters( "Name" );
p.Value = "Sparky";

// Or just set the value directly
oObject.Parameters( "Name" ).Value = "Sparky";

Whether you use commands or the object model, you need to figure out the full path to the parameter. For more information, see Finding Parameter Names.

Setting the Same Value on Multiple Objects at Once

When using native Softimage commands to set values, you can change values relatively, use ranges of values, use random values, and so on. The object model allows you to change values on a whole collection of objects, provided that the values are relevant to the entire collection.

To translate several spheres at once using native Softimage Commands

This example uses the wildcard in the string "sphere*" to target all objects that start with the word sphere. The string ".kine.local.posy" that follows the target indicates that the parameter value to be changed is the local position in Y. Finally, the last argument increases the current value by 10 units. To set the current value to the number 10 instead, you would use the number without the plus sign.

SetValue "sphere*.kine.local.posy", "10+"

To translate several spheres at once using the object model

This example is a little more precise in that it doesn't rely on the names (because you could name a sphere "Buck" or name a cube "sphere") of the objects, but instead builds a collection out of all the spheres in the scene. Then, one by one, it increments the value of the local position in Y of each sphere in the collection by adding 10 to the existing value.

' Find all the spheres under the Scene Root
Set oRoot = ActiveProject.ActiveScene.Root
Set oSpheres = oRoot.FindChildren( , "Sphere" )

' Loop through the whole collection and add 10 to 
' each sphere's position in Y
For Each s in Spheres
	s.posy = s.posy.Value + 10
Next

The parameter value for the local position in Y is represented by "posy" in this example, which is its shortcut name—see Using Shortcuts for more information on shortcuts and how to use them.

Finding Parameter Names

The parameter name for coding is the same name as that which appears in the marked-parameter box on the Animation panel. How you refer to that parameter by name in your code depends on whether you are using it in a native Softimage command or with the object model.

Native Softimage commands use string expressions to identify the scene object you want to target, and you can simply extend that string expression to include the parameters found on those objects.

Note

For parameters, the scripting name is not always the same as the path that is shown in the explorer. Scripting names are internal names that cannot contain spaces, while the explorer displays user interface labels.

For more information on the difference between scripting names and interface labels, see Parameter.ScriptName. For information on how to display scripting names in the explorer, see Using the Scene Explorer to Determine Parameter Names.

Example: parameter name in a native Softimage command

SetValue "myModel.cone.kine.local.ori.euler.rotx", 90

where:

myModel is the model. This can be omitted in the case of Scene_Root.
cone is the object. For the current selection, you can omit the object name and put a period before the rest of the parameter name. For example, .kine.local.ori.euler.rotx specifies the local X rotation of the currently selected object.
kine.local.ori.euler contains a complex of elements that break down in the following way:
- kine.local is the KinematicState object which is composed of a property set (kine) and a compound parameter (local).
- ori.euler is a special kind of compound parameter containing ori.euler.rotx as the precise path of the parameter.
In certain cases, parts of this complex path may be omitted—see Using Shortcuts.
rotx is the parameter.

The object model uses the ParameterCollection to access information about most of the parameters of any project item. Like native Softimage commands, you first identify the target and then access its parameters as a collection.

As with all collections in the Autodesk Softimage SDK, you can use a member's index (position by number starting at 0) or its name to identify it. In the case of the ParameterCollection, you can use the parameter's scripting name as you would use in a native Softimage command.

Example: full parameter name in the object model

Set oRoot = ActiveProject.ActiveScene.Root
Set oCone = oRoot.AddGeometry("Cone", "MeshSurface")
oCone.Kinematics.Local.Parameters("rotx") = 90

where:

oCone is the object variable.
Kinematics.Local is the property set.
Parameters is the collection of parameters in the property set.
rotx is the specific parameter being called.

Shortcuts allow you to omit some of the hierarchy between the object and its parameters. For more information, see Using Shortcuts.

Example: parameter shortcut name in the object model

Set oRoot = ActiveProject.ActiveScene.Root
Set oCone = oRoot.AddGeometry("Cone", "MeshSurface")
oCone.rotx = 90

where:

oCone is the object variable.
rotx is the shortcut to the parameter.

Using the History to Determine Parameter Names

One way to determine a parameter name is to change its value in a property editor and see what gets logged in the command history:

Select an object (or any node in the explorer—use the scope and filter options to find the object you want).
Press Enter to open a property editor with the object's properties, or press Alt+Enter to open a property editor with all the object's properties.
On the appropriate property page, modify a parameter.
View the resulting command in the history pane of the script editor. It should resemble the following:
```
SetValue "[Model.]Object.Property.Parameter", Value
```
Note
You can also determine a parameter name by marking a parameter in the explorer, then checking the argument in the resulting SetMarking command. However, the name that is logged is relative to the currently selected node and may not show the whole property set.

Using the Scene Explorer toDetermine Parameter Names

Another way to determine a parameter name for scripting is to display script names in the explorer with the scope set to either Selection or Scene.

Selection displays only nodes related to the currently selected element(s).
Scene displays all scene element and property nodes from the scene root.

You can choose which part of the scene structure to display by selecting an item from a menu in the explorer window:

A	Click the scope button to select the part of the scene structure you want to view.
B	The bulleted item in the menu indicates the currently selected view.
C	The bold item in the menu indicates the last selected view. Middle-click the scope button to quickly select this view

Choose ShowUse Script Names to use script names for nodes and parameters. For example, using script names for Kinematics > Global Transform > Pos > X would result in kine > global > pos > posx.

When the hierarchy is flattened, you can see the property path and name of a parameter by hovering the mouse pointer over a parameter — a tooltip opens with the parameter's path and name. If Use Script Names is on, the tooltip shows the scripting path and name. Strings that are unnecessary for scripting (such as kine) are omitted from the path displayed in the tooltip.

Referencing Multiple Properties with the Same Name

There are some cases where you need to access a parameter that belongs to one of several property sets that have the same name. For example, you can apply several constraints of a single type (such as a position constraint) to a scene object. You could have 3 of these on your constraints stack and they are all called "Position Cns".

To differentiate which position constraint you want to access (for example, to mute it), you need to specify the index number (starting at 0) that appears beside it in the scene explorer.

To reference multiple properties using native Softimage Commands

If there are multiple properties with the same name, you can identify them by their index number in square brackets. For example, the following line mutes the third positional constraint under an object called "ball":

SetValue "ball.kine.poscns[2].active", false

To reference multiple properties using the Object Model

If there are multiple properties with the same name, you can identify them by their index number in parentheses. For example, the following line mutes the third positional constraint under an object called "ball":

Set oBall = ActiveSceneRoot.FindChild( "ball" )
oBall.Kinematics.Constraints.Filter( siPosCnsType )(2).Active = false

Using Shortcuts

A complex object in Softimage might be described by hundreds or even thousands of individual parameters. These parameters are distributed throughout the hierarchy of properties, operators, primitives, shaders and other elements that describe the object.

The object model provides ways to traverse through this hierarchy to visit each ProjectItem object and find its parameters. However, for convenience some of the most common parameters are also promoted so that they act as if they are parameters directly on the X3DObject parent. These are what we call shortcuts.

You can use shortcuts in your scripts or use the full property and parameter name syntax, although compiled code only supports the full parameter name syntax. Using shortcuts allows you to omit the names of the intermediate nodes as an alternative to specifying the full name and are available when scripting with both commands and the object model.

Important

Kinematics shortcuts refer to only the parameters nested under the Local Tranform node. For example, the expanded version of oCone.posx is always oCone.Kinematics.Local.Parameters("posx").

If you need to access a Global Transform parameter, you must use the full parameter syntax (for example, oCone.Kinematics.Global.Parameters("posx")).

Using Shortcuts with Property-set and Parameter Names

The following node names can be omitted in property-set names:

surfmesh, polymsh, crvlist, and other geometry types in native Softimage commands.
local or global coordinate systems for transformations. If this is omitted, local is used by default.
for transformations, any other nodes (such as euler) between kine or Kinematics and the parameter itself.

For example, if cone is selected, then the following statements are equivalent:

SetValue "cone.kine.local.ori.euler.rotx", 90
SetValue ".kine.rotx", 90
Selection(0).Kinematics.Local.Parameters("rotx").Value = 90
Selection(0).rotx.Value = 90

Referring to Shortcuts in Compiled Code

Unfortunately, you cannot use shortcuts in C++. You must refer to a parameter using the normal syntax (including those parameters that are exposed as shortcuts).

For example, you can use the following snippet to print out the name and value of each parameter of the "cube" object:

using namespace XSI;
Application app;
Model root = app.GetActiveSceneRoot();

X3DObject myCube;
root.AddGeometry( L"Cube", L"MeshSurface", CString(L"MyCube"), myCube );

// print the names of all parameter exposed by the cube object
CRefArray params = myCube.GetParameters();

for (long i = 0 ; i < params.GetCount(); ++i )
{
	Parameter param(params[i]);
	app.LogMessage
	( 
		param.GetScriptName() + L" = " + param.GetValue().GetAsText() 
	);
}

Getting More Information on Using Shortcuts with the Object Model

There are several types of elements that support shortcuts in the object model:

3D objects (for example, cameras, control objects, lattices, lights, the model presets—such as the preset for the skeleton of a man—and primitives)
Operators (for example, Curve Generator, Deform, Surface Generator, and Topology)
Scene properties (for example, Ambient Lighting, Annotation, Display, Geometry Approximation, Material, Texture Projection, Visibility, and Weight Maps)
All custom properties
All shaders (for example, Anisotropic, Blinn, Constant, Cook-Torrance, Lambert, Phong, and Strauss)
Skeletons (for example, ChainBone, ChainEffector, and ChainRoot)
Constraints (for example, 2 Points, 3 Points, Bounding Volume, Curve Path, Direction, Distance, Object To Cluster, Orientation, Pose, Position, Scaling, Surface Path, and Up Vector)

Not all parameters are supported by every object. The Shortcut Reference describes the available properties for each of these categories.

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