Connections

 
 
 

Connections represent the points at which your scripted operator communicates data with Softimage. You do not have access to data unless you create a connection.

You can connect a scripted operator to animatable parameters, properties, geometries, or a combination of these. Each connection is one of two types: input or output. A single scripted operator can have any number of connections, almost anywhere in the scene.

You manage connections using the grid in the top pane of the scripted operator editor. To see the connections, make sure to select Connections from the list in the upper left.

A

Select Connections.

B

Create a new connection.

C

Remove the highlighted connection.

D

Move the highlighted connection up or down in the list.

E

Name of the connection to use in your code.

F

Type of connection: input or output.

G

Element to connect to.

H

Browse to connect to a new element.

TipUsing the Softimage SDK instead of the scripted operator editor, you can define port groups to create an operator with a variable number of connections. See Custom Operators [SDK Guide] for more details.

Making Connections

You can make a connection to a scripted operator either by using the New button or by dragging and dropping from an explorer.

In either case, if the Value column does not accept your changes, the element you specified is not supported for connections.

To add a connection using the New button

  1. Make sure that Connections is selected in the list in the upper left of the scripted operator editor.

  2. Click the New button.

    A new row is added to the grid, and a pop-up explorer opens.

  3. Use the explorer to select a scene element to which you want to connect.

    • To connect to a parameter, simply select it.

    • To connect to a property, simply select the property node. Note that you cannot connect to kine because it is not a real property; however, you can connect to either the local or global transform.

    • To connect to an object's geometry, select its primitive node beneath the object, for example, polymsh, srfmesh, crvlist, lattice, cloud, or hair.

    • To connect to the text string of a text object, select the text node below the TextToCurveList operator.

    • To connect to a color, show parameters in an explorer and connect to the individual R, G, B, and A channels.

    You can change the connected element at a later by clicking on ... in the Edit and selecting a new element, or by typing directly in the Value column.

  4. For an output connection, click in the Access column and select Out.

  5. If desired, change the name in the Name column. This is the name used to refer to the connection in the code of your scripted operator. The default name is based on the type of connection and the parameter to which it is connected.

To make a connection by dragging and dropping

  1. Click on an element in an explorer.

  2. Drag and drop it onto the scripted operator editor:

    • To create a new connection, drop it onto the space below the last connection in the list.

    • To change an existing connection, drop it into the corresponding row of the Value column.

Retrieving and Using Input Connections

To use the value of an input connection in your scripted operator, simply use the name of the connection as defined in the Name column in the top pane of the scripted operator editor.

To speed up the execution, it's a good idea to copy the input values into local variables at the beginning of your code and then work with the local variables. In this way, you minimize the overhead between the scripting engine and Softimage.

Example 1: Getting Input Connections on Parameters

If an input connection named InRad is connected to the sphere.radius parameter of a 3D object in your scene, you can enter the following lines:

dim i_rad
i_rad = InRad.Value

Then use i_rad wherever you need to work with the object's radius in your code.

Example 2: Getting Input Connections on Properties

When an input connection is on a property, you get the individual parameters using their scripting names. For example, if an input connection named InXform is connected to the Local Transform property, you can get the value of the Pos X parameter as follows:

myPosx = InXform.Value.Parameters("posx").Value

You can also use the shorter form:

myPosx = InXform.Value.posx.Value

Example 3: Getting Input Connections on Geometry

If an input connection named InGeom is connected to a 3D object's primitive property, use the following lines to get an array holding the positions of the object's points:

myPnts = InGeom.Value.Geometry.Points.PositionArray

You can then loop through the point positions using VBScript syntax as follows:

For i = 0 to UBound(myPnts,2)
	' Do something with myPnts(0,i) (X position)
	' Do something with myPnts(1,i) (Y position)
	' Do something with myPnts(2,i) (Z position)
Next

Example 4: Getting Input Connections on Particle Clouds

Getting the position array of a cloud's particles is slightly different than getting it for a geometric object's points. If an input connection named InCld is connected to a cloud's primitive property, use the following lines to get the particles' position array and count:

set myParts = InCld.Value.Particles
myPartsPos = myParts.PositionArray
myPartsCount = myParts.Count

You can then loop through the particle positions using VBScript syntax as follows:

For i = 0 to myPartsCount - 1
	' Do something with myPartsPos(0,i) (X position)
	' Do something with myPartsPos(1,i) (Y position)
	' Do something with myPartsPos(2,i) (Z position)
Next

Updating Output Connections

The primary purpose of the main update routine is to evaluate and return new values for the output connections. To return a new value, you must set Out.Value.

Example 1: Setting an Output Value on a Single Parameter Connection

If there is only one output connection and it is on a parameter, the following example sets it to the value of myNewValue:

Out.Value = myNewValue

Example 2: Setting an Output Value on a Single Property Connection

If there is only one output connection and it is on a Local Transform property, the following example sets the Pos X parameter to the value of myNewValue:

Out.Value.Parameters("posx").Value = myNewValue

You can also use the shorter form:

Out.Value.posx.Value = myNewValue

Example 3: Setting an Output Value on a Single Geometry Connection

For a single output object connection, you would update the position of its points as follows:

Out.Value.Geometry.Points.PositionArray = myPnts
Important

If you use an output connection to write to an object's geometry, make sure that you also have an input connection for the geometry.

If you don't have an input connection for the geometry, then your scripted operator may stop working when you reload the scene. This is because the initial geometry has not been updated and is empty when your scripted operator is evaluated.

An input connection ensures that the geometry is updated before your scripted operator is evaluated.

Example 4: Setting an Output Value on a Single Particle Cloud Connection

For a single output cloud connection, you would update the position of its points as follows:

Out.Value.Particles.PositionArray = myPartsPos

Example 5: Setting an Output Value for Text

Use the following general syntax to update the text string of a text object:

Out.Value.Parameters("text").Value = myNewString

Example 6: Setting Output Values on Multiple Connections

If there are multiple output connections, you should test Out.Name and return the correct value using conditional statements (such as If or Select Case in VBScript). For example:

if Out.Name = "OutRadius" then
	Out.Value = InSphere.Value
elseif Out.Name = "OutHeight" then
	Out.Value = 2 * InSphere.Value
else
	LogMessage "Unknown output"
end if

Viewing the Graph of Output Connections

You can view the graph of your parameter output connections in the bottom pane of the scripted operator editor by choosing View Show Graph or pressing Ctrl+G. Repeat to return to viewing code.

NoteIt can take some time to display the graph because your scripted operator must be evaluated for every frame.

Removing Connections

To remove an unnecessary connection from a scripted operator

  1. Make sure that Connections is selected in the list in the upper left of the scripted operator editor.

  2. Select a connection by clicking anywhere in the associated row.

  3. Click the button.

Note

If you delete the last output connection from your operator, the operator will be removed from your scene when you next apply it.

However, the data in the scripted operator editor will not be cleared, so you can add a new connection without losing your script.

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