About Scripted Operators

 
 
 

Before you begin, you should understand some basic concepts about scripted operators, connections, and variables.

What Are Scripted Operators?

Scripted operators are object-model scripts that are called to update data in a scene. A scripted operator can be applied to one or more animatable parameters, to properties, or even to geometric objects to deform their shapes.

Scripted operators have several uses:

At the same time, scripted operators have some disadvantages:

For these reasons you may prefer to use scripted or compiled self-installing custom operators instead of scripted operators — see Custom Operators [SDK Guide]. You can think of scripted operators as providing an intermediate solution between expressions and self-installing custom operators.

Connections

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

You can connect a scripted operator to animatable parameters, properties, objects, or a combination. 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.

Parameter, Property, and Geometry Connections

You can connect a scripted operator to animatable parameters, properties, 3D geometry, or a combination.

A scripted operator connected to a parameter is similar to an expression. One important difference is that a scripted operator can be connected to multiple parameters so that a single script can be used to update several parameters with different values.

You can also connect a scripted operator to a property like Visibility or Local Transform. This means you can access any of the property's parameters without the need to define multiple connections to individual parameters.

In addition, scripted operators can be connected directly to geometry such as polygon meshes, surfaces, curves, particle clouds, and hair. This lets you modify a 3D object's shape to create your own custom deformation.

Input and Output Connections

There are two types of connection:

  • Output connections are those elements that your script is responsible for updating. When the scene needs to be updated, your script is called to calculate the new values.

  • Input connections let your script access data from the scene. You can create an input connection for any scene data that your script requires in its calculations.

The connections must be properly defined for the operator to be evaluated correctly. Any scene data that is used in the computation should be added as an input connection; otherwise, the operator will not be called to update when the input changes. Similarly, any scene data that is set by the script should be added as an output connection; otherwise, the operator will not be called when an updated value is required.

The same element can be connected as both an input and an output in the same operator. For example, if you create a custom deformation, you must get a 3D object's geometry to get its list of points (input) and then update the geometry with the new positions of those points (output).

In the case of a parameter input connection, the scripted operator is passed the final value of that parameter for the appropriate frame including the effect of animation from any other source (function curve, expression, action, constraint, or inverse kinematics).

If a parameter is both an input and an output connection, then the scripted operator is passed the current value of that parameter. This could be the last value set, or it could be the value from a previously-applied function curve or expression. If there are multiple scripted operators, then the output of one is the input of the next in the order in which they were applied (not the order in which they were created).

If there are multiple parameters that are connected as both inputs and outputs to a single scripted operator, the scripted operator is called to update them individually as needed. In particular, the order in which they are updated may change; when your operator is called to update one parameter, you cannot be certain which, if any, of the other inputs have already been updated.

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.

Variables

Scripted operators can have variables as well as connections. Variables are custom parameters that belong to the scripted operator and can be used to control its effect. You can edit and animate variables just like any other custom parameter in a scene. In addition, the variable is available to the scripted operator in its calculations.

For example, if you create a custom deformation, you could define a variable to control the amplitude of the deformation. You can then animate the amplitude using keys, expressions, actions, and so on.

Main Update Routine

The main update routine is where you write the code to calculate new values for all your output connections. It is contained in the middle panel of the scripted operator editor. This code is parsed when you apply a scripted operator as well as when a scene with a scripted operator is loaded.

You can write scripted operators in any language supported by Softimage. The language that is used to parse a particular scripted operator is the language that is set on the Scripting page in the Preferences window when the scripted operator is first created.

You cannot use scripting commands in your code. You are restricted to a subset of object model statements. The properties and methods that you are allowed to use in scripted operator code are listed in the SDK Guide.

The scripted operator editor manages the header of the main update routine automatically for you, so the Sub Update() and End Sub lines are read-only. The following arguments are passed to the main update routine:

Extra Code

The bottom pane of the scripted operator editor can be used to hold extra code needed by your scripted operator, such as helper routines and global variable declarations. In addition, it can be used to define Init and Term procedures that allow you to access private user data — see Using Private User Data in Scripted Operators.

As with the main update routine, this code is parsed when you apply a scripted operator as well as when a scene with a scripted operator is loaded.

Note

In VBScript, you can force all variables (including the variables in the main update routine) to be defined before they are used by adding the following statement to the global code in the bottom pane.

Option Explicit

Limitations

Scripted operators have a few limitations: