Writing Expressions

 
 
 

Once you have the expression editor open, you can write an expression by typing it in the expression pane. To write an expression:

  1. Select the target parameter. This step is only necessary if you opened the expression editor using the Expression Editor command instead of the Set Expression command — see Selecting or Changing the Target.

  2. Enter the expression in the expression pane. For a description of expression syntax, see Expression Syntax.

    Enter an expression by typing or choosing items from the menus on the command bar. The expression shown here applies a simple randomize function to the null's Y position.

  3. Validate and apply the expression — see Validating and Applying Expressions.

To write an expression:

  • Click the Function button or press Ctrl+F to add a function or constant at the insertion point (see Entering Functions and Constants).

  • Click the Object button to add an object or parameter name at the insertion point (see Entering Object Names).

  • If you have already typed part of a branch name followed by a period, click the Param button to choose a child node to add at the insertion point (see Entering Parameter Names).

  • On Windows systems, you can cut, copy, and paste from another editor (such as Notepad), as well as drag-and-drop text from programs that support that feature.

Resulting Value of an Expression

The value of an expression is always a floating-point value (meaning it can be a number like 12.345 instead of an integer like 12). The expression editor always shows the mathematically correct value. However, some parameters can only accept integers or values in a specific range. In these case, the value returned by the expression is automatically rounded off or clamped before being used.

Tips for Writing Expressions

Here are a few tips to make writing expressions a little easier:

  • Copying, cutting, and pasting use standard keyboard shortcuts (Ctrl+C, Ctrl+X, and Ctrl+V, respectively).

  • You can preview the result of an expression as a graph. To switch between displaying the message pane and the graph view, press Ctrl+G or choose View Show Graph in the expression editor.

  • If you want to manually edit expressions in a bigger pane, press Ctrl+E or choose View Text Editor to open another text editor, as described in Using Another Text Editor.

  • While you can't add comment lines to an expression as you can with scripts, you can add comments in the Expression property editor (see Activating and Deactivating Expressions) or on the Expressions page that appears in the property editor of the parameter on which you set an expression (see Editing an Existing Expression).

Expression Syntax

Here are a few things to remember when creating expressions:

  • All object names must be followed by a parameter scripting name.

    The exceptions are the distance functions: Center to Center (ctr_dist), to Camera (ctr_dist_cam), and to Camera Interest (ctr_dist_cam_int). When you specify an object name with these functions, remember to use a period at the end of the name.

  • Parentheses must always be closed.

  • Spacing is irrelevant to how the expression is parsed. Spaces, tabs, and carriage returns make an expression easier to read, but they are ignored by Softimage.

Selecting or Changing the Target

If you opened the expression editor with the Expression Editor command from any menu (such as the Animation menu in the Animation panel or from the View > Animation menu in the main menu), you first need to select a target parameter (also called the affected element). You can also type in a definition if there is no target selected.

If you opened the expression editor using the Set Expression or Edit Expression commands, the target parameter is already selected (whatever parameter was marked when you chose the command). However, you can change the target as described below.

To select or change the target parameter

  1. Do one of the following:

    • Press Ctrl+T.

      or

    • Click the Browse (...) button in the expression editor.

      or

    • Choose Edit Change Target from the expression editor's command bar.

    • In the explorer that opens, you can navigate by expanding nodes until you see the desired parameter, then click its name.

If the desired parameter is listed nearby in the explorer, it may be quicker to use the Prev and Next buttons in the expression editor's command bar. These let you quickly apply expressions one parameter after another, such as the transformation parameters.

Alternatively, if you know the scripting name of the parameter, you can type it directly into the target parameter box. To determine the scripting name of a parameter, modify the parameter in a property editor and check the name that gets logged in the SetValue command in the Command box or Script Editor. You can also activate View Use Script Names in an explorer.

Entering Object Names

You can enter object names by typing directly in the editing pane or by clicking the Object button and selecting one from a pop-up explorer. You can expand nodes to also select children, properties, and parameters.

For example, let's say you wanted to add a null's Rotation Z parameter in the editing pane:

  1. Click the Object button and expand the following nodes in the pop-up explorer: Null > Kinematics > Local Transform > Ori > Euler.

  2. Select rotz to automatically insert the following expression into the editing pane: null.kine.ltransfo.rotz

Using the "this" and "this_model" Tokens

You can also use the this token (type this or choose Functions Node this) in an expression to have an object reference itself. This is useful when you to use the same expression on many different objects.

For example, the following always refers to the local Y position of the object whose parameter is the target:

this.kine.local.posy

You can use the this_model token (type this_model or choose Function Node this model) to refer to the current model in an expression. For example, if two models Fluffy and Sparky both contain an object named LeftPaw, you can use this_model.LeftPaw to refer to either Fluffy.LeftPaw or Sparky.LeftPaw, depending on the context.

Entering Parameter Names

You can enter parameter names in the editing pane in the following ways:

  • Typing the parameter script names directly, if you know the correct syntax.

    or

  • Drag and drop a parameter name (not its animation icon) from a property editor or explorer into the editing pane.

    To replace existing text, select it before dragging and dropping the parameter name.

    or

  • Use the F12 key or the Param menu to help complete the parameter name. These commands prompt you with a list of possible parameters in the current context. For example:

    1. Enter the following in the editing pane:

      Camera_Root.
    2. Press F12 or click the Param button to display a list of possible nodes — choose kine or press K.

    3. Type l (lowercase L) and press F12 again. The node local is automatically filled in (it's the only available node beginning with l).

    4. Type p and press F12 again. A list of available nodes that begin with p appears — choose posx.

    TipExpressions can accept custom parameter names that use a dash (as in mypset.in-out).

Entering Functions and Constants

Softimage supports several tokens representing functions and constants in expressions. You can enter these directly by typing in the editing pane or you can select them from the commands in the Function menu.

NoteFor a complete description and syntax of all the functions and constants available, refer to the Expression Function Reference [Properties Reference].

For some items you choose, only the first part of the string is entered so you must add the closing parenthesis. For example, if you choose Function Trigonometry Sine, the following is entered:

sin(

You then type any expression after it, and need to include a closing parenthesis:

sin(Fc * 10 + 5)

For other items you choose, dummy strings are entered to help you remember which parameters are required. You must replace the dummy strings with expressions. For example, if you choose Function Condition, the following is entered:

cond( <cond> , <true_expr> , <false_expr> )

Replace <cond> with a condition to evaluate as true or false, for example:

(cone.kine.global.posx <= 0)

Replace <true_expr> with an expression representing the value to use if the condition is true, for example:

0

Similarly, replace <false_expr> with an expression to use if the condition is false.

Note
  • If you are using the camera distance functions To Camera(ctr_dist_cam) or To Camera Interest (ctr_dist_cam_int) and you move the camera or interest, you may need to change the current frame to update the scene.

  • The Frame Offset (at_frame) and Time Offset (at_time) functions work only for parameters driven by function curves.

Operators

You can enter operators in an expression directly by typing in the editing pane, or you can select them from the Function Arithmetic menu.

The following operators are supported for expressions:

Operator

Meaning

+

Add

Subtract

*

Multiply

/

Divide

%

Modulo (remainder)

Operators follow the standard of precedence: items enclosed in brackets first, then * and /, followed by + and –.

You can enter the following Boolean operators in a condition, available from the Function Conditions menu:

Operator

Meaning

==

Equal to

>

Greater than

>=

Greater than or equal to

<

Less than

<=

Less than or equal to

!=

Not equal to

&&

AND

||

OR

Using Another Text Editor

You can use a different text editor to edit expressions. When you choose View Text Editor or press Ctrl+E, the current contents of the editing pane open in a separate text editor window. You type the expression in the separate window, then when you close the text editor, you are asked whether you want to update the editing pane of the expression editor.

Normally, the default text editor for your operating system is used. You can specify a different editor using the SI_TXT_EDITOR_ENV environment variable. For more information, see Setting and Using Environment Variables [Advanced Setup and Configuration].