Menu Cells

Expressions

The Expressions menu cell commands in the Motion module let you set mathematical expressions for anything that can be animated in SOFTIMAGE 3D. For a list of parameters that can be animated, see the SaveKey menu cell, starting on SaveKey -> Object. When you animate a parameter, a function curve of the same name is created to represent these values.

For an overview of expressions and some examples, see the Expressions section of the Animating User's Guide.

There are three ways to use expressions: as a custom constraint (as explained in this section), to generate or edit a function curve, or to use with Channels. These methods correspond to these commands:

The Expressions -> Edit command for creating a custom constraint.
The FcrvEdit -> Expression command for generating or editing a function curve.
The Expressions button in the Channel -> Connection Setup dialogue box for use with Channels section.

Edit

The Expressions -> Edit command opens the Expression Editor dialogue box which provides various tools to help you create and edit expressions. You can build an expression by picking scene elements and functions from menus, cutting and pasting sections from other expression files, or loading predefined expressions from libraries.

Procedure

1. Select an element to constrain; it can be an object, a light, a camera, etc. This is considered the "affected element."

Note:

For materials and textures, you need to select them as elements from the Schematic window in the Matter mode.

2. Choose the Expressions -> Edit command.

The Expression Editor dialogue box is displayed.

There are many possible ways of using the options in this dialogue box. The following example shows the basic steps.

3. By default, the element selected in the scene appears in the Affected Element text box.

4. Add the affected element's parameter to be constrained. Click at the end of the affected element's name (after the period) and then click Fcurve. Select one of the possible parameters (whose values are represented by a function curve of the same name) from the Function Curves dialogue box that appears.

Tip:: If you know the exact name of the element's parameter, you can type it in.

The parameter name corresponding to that function curve is added to the end of the affected element.

5. Now create your expression. If there is a predefined expression you want to use, click Select and choose that expression from the browser that appears.

To create an expression from scratch, follow these steps.

6. Click in the Expression text box and either type the expression directly or click the Scn Element button.

If you do the latter, the Select Element browser appears in which you can choose any element from the scene to which you want to constrain your affected element's function curve.

7. Add the scene element's parameter that acts as the constraint. Click at the end of the element's name (after the period) and then click Fcurve. Select one of the possible parameter names (function curves) from the Function Curves dialogue box that appears.

8. At this point, you could leave this expression as it is for a very simple constraint. To make a more complex one, you could refer to more elements or add an operator and some numeric values to this expression, such as + 3. You could also use the predefined math Functions, such as cosine, logarithm, and conditional, or Variables such as current frame, first frame, or a random value.

9. If segments of your expression are repeated, you can put them in the Local Variables text boxes to simplify the main expression.

10. Click Validate to make sure you have a valid expression. If there is a syntax error, the error is highlighted, and a message is displayed at the bottom of the dialogue box.

11. If you want to save the expression to a file, click Save, and specify a name for it in the Save Expression dialogue box that appears.

12. Click Ok to apply this expression to your affected element or click Cancel to exit without saving any changes.

Parameters

Select

Opens a browser from which you can load a previously saved expression file from the EXPRESSIONS chapter of any database. When loading an expression file that contains more than one expression, the first one is used.

The name of the expression file you choose appears in the text box beside the Select button.

If there are any particular scene variables contained in the expression, they are replaced by question marks (???) that you must substitute with valid elements and parameters from your current scene.

Affected Element

This represents the element and parameter being affected by the expression (such as cube.etrnx, sphere.rotx, or camera.roll). This is the object currently selected in a scene.

If you're using the Expression Editor dialogue box with the Fcurve editor (FcrvEdit -> Expression), the affected element cannot be changed. This is because it refers to the parameter (or parameters) you have already selected to be affected by the expression.

Note:: You can assign one expression per parameter. For example, cube1 can have many parameters (such as rotx, roty, rotz) each with its own expression.

Returns to the previously validated expression for the element. The current expression is validated and accepted. If there is no previous expression, the Expression text box is empty, and you can enter a new expression.

The number of the expression is shown above this button. For example, 1 of 2 means this is the first expression of two that are defined for the affected element.

The Previous button cannot be used when using expressions with the Fcurve editor (FcrvEdit -> Expression).

Goes to the next validated expression for the given element. The current expression is validated and accepted. If there is no next expression, the Expression text box is empty, and you can enter a new expression.

The Next button cannot be used when using expressions with the Fcurve editor (FcrvEdit -> Expression).

Operator

This button defines which operation to perform on the result of the expression you define. For example, if you use the + operator, the result of the expression you create in the Expression text box is added to the affected element, whereas if you used the = operator, the element would be equal to the result of the expression.

Tip:: These operators are not the ones used within the Expression text box. If you want to insert operators into your expression, you must type them.

For creating constraints, the operator is always equal (=) because the affected element must be equal to the resulting value of the expression to create the constraint. If you use the Expression Editor dialogue box with the Fcurve editor (FcrvEdit -> Expression), you can use any of the operations:

= (equal) overrides the contents of the selected parameter with the result of the expression making the affected element equal to the result of the expression.

+ (add) adds the result of the expression to the affected element's function curve.

- (subtract) subtracts the result of the expression from the affected element's function curve.

* (multiply) multiplies the affected element's parameter by the result of the expression.

/ (divide) divides the affected element's parameter by the result of the expression.

If there are no parentheses in the expression, operator priorities are always determined with division having the highest priority, then multiplication, then subtraction, and then addition.

Expression

The text box in which you enter the expression, which can consist of:

Scene elements such as cube1., mat1., or cam.
Parameters or function curves, such as etrny, rotx, or transz.
Math functions, such as sine, exponential, or condition.
Variables such as Current Frame (Fc), End Frame (Fe), or user-defined random values.
Constants (also called values) such as 5, -1.2, 0.3, or 3335.
Operators such as + (plus), - (minus), * (multiply), and / (divide), % (modulo)
Local variables as defined in the A, B, C, D text boxes.

For example, this expression is a combination of a math function (sin), a variable (Fc), operators (* and +), and values (20 and 50).

sin( Fc * 20 ) * 50 + 50

Note:: Note that spaces between elements in the expression do not matter. For example, you could write ( Fc * 20 ) or (Fc*20).

Scene elements in an expression are always written with the following syntax:

[chapter] <full name of element>.<name of parameter>

where:

[chapter] is a code that indicates which chapter the element belongs. By default, no chapter code indicates the element is a model. This is required to distinguish between elements of the same name in different chapters (such as LIG light and MOD light). See Scn Elements for more information.

<full name of element> is the name of the scene element to which you want to refer. In the case of spot lights and cameras, the interest element is not distinguished from a light or a camera. The name light or camera is used.

Note:: A name that starts with a numerical character (such as 10w) is not accepted as part of an expression.

<name of parameter> is the name for the desired parameter whose values are represented by a function curve of the same name.

For a full description of all syntaxes you can use in the Expression text box, see Expressions Syntax.

All animatable parameters can also be referenced or modified (some restrictions apply) in an expression. Codes are the same as the ones used in the Fcurve editor, Channels, and the library keys filter dialogue box (Get -> Track Filter). When the element is a model, some qualifiers may precede or be appended to the name of the parameter, depending on the type of parameters used. For example, the coordinate system used for an object's position would be cube.G.posx for the global position, and cube.L.posx for the local position.

Local Variables (A, B, C, or D)

The Local Variable text boxes allow you to enter an expression which can then be referred to in the Expression text box as a variable. Local variables make it easier to read a complicated expression because you can separate it into sections and paste them into the A, B, C, or D text boxes. When you want to reference the local variable in the Expression text box, simply use its letter. For example, if you define a variable in the A text box, you would reference this variable in the Expression text box:

sin( Fc * 20 ) + A

Local variables are also very useful for repeated segments in an expression. You only have to modify the local variable once, and it is updated each time it is used in the expression.

Note:: You cannot reference a local variable within another local variable; that is, the expression in variable A cannot reference variable B.

Token

The four options in this section (Scn Elements, Fcurves, Functions, and Variables) are used as tools to insert strings into the expression. For instance, instead of typing sin() in the Expression text box, you can select the Sine command from the Functions menu to insert the proper syntax string for you (click Insert).

In many cases, these menus do not work unless the cursor is inserted in a valid place within the expression, which depends on the context. For example, to use the Fcurves menu, you must place the cursor after an element name, followed by a period (such as cube1.).

Insert

When you select an option from the Functions or Variables menu, its syntax appears beside the Insert button. Click Insert to paste this syntax at the cursor's location in the Expression text box and add the desired values and/or operators to this function or variable.

Scn Elements

The scene elements are elements in your scene that you can choose to include in your expression. When you click the Scn Elements button, it opens the Insert Element dialogue box.

In this dialogue box, you can select one scene element to be added to the expression. The chapter code is automatically inserted for elements that are not models. A chapter code is an identifier that represents a particular type of element, such as MAT for materials or CAM for the camera. If you have already typed the chapter code in the Expression text box, the dialogue box presents the appropriate list of elements for that chapter. For example, LIG displays the LIGHTS chapter.

These are the chapter codes used:
Chapter syntax Type of element
MOD Models (optional)
LIG Lights
CAM Camera
MAT Materials
T2D 2D textures
T3D 3D textures
WAV Wave
CHN Channel

The buttons in the Insert Element dialogue box let you set up your database in which you select the element.

Fcurves

This button lets you select a parameter (whose values are represented by a function curve of the same name) for the corresponding scene element. To select the parameter name to be referenced, you must have the cursor already placed after the element name and its period (such as in cone.). When you click Fcurves, the Function Curves dialogue box is displayed:

The list of available parameters displayed depends on the type of element preceding the cursor. For example, LIG light1. brings the list of all valid parameters (function curves) for lights. When a parameter from that list has already been affected by an expression, it appears dimmed, which means you cannot select it.

When you select a parameter and click Ok, it is added after the element's period.

Functions

This menu lets you select a math function to be inserted into the expression. These are the supported math functions.

Math function	Syntax
Sine	sin( )
Cosine	cos( )
Logarithm	log( )
Exponential	exp( )
Absolute	abs( )
Square root	sqrt( )
Power (x to the power of y)	pow( <x>, <y> )
Minimum value (between x and y)	MIN( <val1 , <val2> )
Maximum value (between x and y)	MAX( <val1>, <val2> )
Average (of two to n values)	av( )
Conditional (where <true_expr> is used if <cond> is true, and <false_expr> is used if <cond> is false)	cond( <cond>, <true_expr>, <false_expr> )
Time offset	at_time( <T-1.0>, <elm.fcv> )
Frame offset	at_frame( <Fc-30>, <elm.fcv>)
Centre distance	ctr_dist( <elem1>, <elem2>)
Distance to camera	ctr_dist_cam( <elem1>)
Distance to camera interest	ctr_dist_cam_int( <elem1>)
Sinus	sinus( <period>, <amplitude>, [<offset>])
Oscillation	oscill( <sf>, <ef>, <sp>, <ep>, <interp>, <sa>, <ea>, <interp>)
Ease in	ease_in( <start frame>, <end frame>, <interp>)
Ease out	ease_out( <start frame>, <end frame>, <interp>)
Noise	noise( <x>, <y>, <z>)
Fmod	fmod( <val1>, <val2>)
Has Relation (used in the Spreadsheet Query Expressions Editor)	has_relation( <elem1>, <relation name>, <direction>)

Arguments of these functions can be another expression, such as
sin( min (a, b) ). For the trigonometric functions, the argument is considered as degrees.

To create complex behaviour in your animation, you may find the Conditional function especially interesting and useful. This function opens up many possibilities since you can specify the conditions in which an object does something. For example, you can have a foot kick a ball up in the air if they make contact; if not, the ball stays on the ground. You could also have a spinning top turn blue when it is at a certain distance from the camera. The possibilities are infinite.

Variables

This menu allows you to select a predefined variable to be inserted into the expression. A variable is a predefined value in SOFTIMAGE 3D that you can use in your expression. For example, if you select Current Frame (Fc), its value changes as the current frame changes.

Variable	Syntax
Current Frame	Fc
First Frame (start)	Fs
Last Frame (end)	Fe
Current Time	T
Random: 0 or 1	randBool( <seed> )
Random: 0.0 to 1.0	rand_0_1( <seed> )
User defined Random	RAND( <seed>, <min>, <max> )
Linear Interp	LinearInterp
Spline Interp	SplineInterp
FORWARD	FORWARD
BACKWARD	BACKWARD
PI	PI
E	E
TRUE	TRUE
FALSE	TRUE

The Current Time (T) variable is the same as the Current Frame (Fc) variable except the animation is expressed in seconds, not frames.

Random Values

If a <seed> is specified, a sequence of values are precalculated; that is, one value per frame. When replaying the animation, the value returned by a Random function at a particular frame is always the same as long as the first frame is not modified, which causes the regeneration of the sequence of values. If no seed is specified, there is no sequence.

For the User-defined Random variable, the random value is between a minimum and maximum value: if <min> and <max> are integer values, the returned value of this random function is a finite number in that range; otherwise it is a floating point value.

Status

This area shows the current status of the expression. Error and confirmation messages appear here, such as "Valid expression" for an expression that has been validated. If an invalid expression is created, you are also warned. If a message appears stating that the expression must be deleted because a cycle has been detected, the dialogue box does not disappear and you must delete that expression.

For a list of error messages that may appear in the status area, see Expressions Syntax.

Copy

Copies the currently selected string to a buffer, so that you can paste it (using the Paste button) in a different expression within the Expression Editor (using the Previous or Next buttons, or in the Local Variables text boxes). The contents of the buffer are overwritten when you click Copy again.

Paste

Pastes the contents of the current buffer (created when you clicked Copy) wherever the cursor is inserted. You can paste these contents as many times as desired until you click Copy again.

Validate

Validates the syntax of the expression. This is useful for checking typographic errors in an expression before you click Ok, even though expressions are always validated before they are accepted (with Ok, Previous, or Next). If an error is found in the expression, a message appears in the status line. The error is highlighted in the expression, but this is not necessarily where the error is located.

The only error that may occur, which is not detected by the Validate button, is when a cycle is detected. To see whether there is a cycle, first click Ok to accept the expression. If a message in the status line appears stating that the expression must be deleted because a cycle has been detected, it means that the new expression you entered caused a cycle of dependencies with some other element in the scene. The dialogue box does not disappear and you must delete the expression.

Save

Allows you to save the current expression into a file for later use (click Select to open the browser). When you click Save, a dialogue box appears in which you can choose a name and location for the expression file. It can be saved to any EXPRESSIONS chapter. Since the expression is automatically saved with the scene, save an expression if you want to disassociate it from an affected element, and keep it for later use.

Delete

Deletes the current expression from the Expression text box for the affected element.

Cancel

Exits the Expression Editor dialogue box without saving any changes made to the current expression(s).

Ok

Accepts the current expression if it is valid. Click the Validate button if you want to make sure the expression is valid before accepting it.

Copy

The Expressions -> Copy command lets you copy the expressions affecting one element to another element of the same type (in the same chapter). The selected element inherits the expressions affecting the element that you have selected.

If the expression to be copied affects a parameter that is already referenced in the destination element, this expression is not copied. If an expression generates a cycle, it is not copied either.

Procedure

1. Select the element you want to receive the expression (the destination element).

2. Choose the Expressions -> Copy command. This puts you in the Copy Expression mode.

3. Pick the element whose expression you want to copy. You can pick more than one element.

The destination element inherits the expressions from the elements you pick.

4. Right-click or press Esc to end the Copy Expression mode.

SOFTIMAGE 3D Reference - 19 APR 1996

Chapter syntax	Type of element
MOD	Models (optional)
LIG	Lights
CAM	Camera
MAT	Materials
T2D	2D textures
T3D	3D textures
WAV	Wave
CHN	Channel