Expression Controller

Main toolbar > Open Track View > Select a track in the Track View Hierarchy. > Track View toolbar > Assign Controller > Expression

Graph Editors > Track View > Open Track View > Select a track in the Track View Hierarchy. > Track View toolbar > Assign Controller > Expression

Interface Procedures

With the Expression controller you can use mathematical expressions to control the following animation aspects:

• Object parameters, such as length, width, and height

• Transform and modifier values, such as an object's position coordinates

  You can constrain values by basing them on the controller values of other objects in the scene.

An expression is a mathematical function that returns a single value. gmax evaluates the expression once for each frame of an animation, generating values that can change from frame to frame.

You create and manage expression controllers in Track View. You can assign expressions to the following kinds of animation controllers:

Creation parameters	Any numeric creation parameter
Transforms	Position [X, Y, Z] X Rotation Y Rotation Z Rotation Scale [X%, Y%, Z%]
Modifiers	Any numeric modifier parameter (including creation parameters)
Materials	Colors [R, G, B] Any numeric material parameter

Note: Expression controllers can work only with the individual XYZ components of Euler rotation. You can't assign an expression to TCB rotation or other kinds of rotation controllers.

Expression Return Types

Operators

Variables

Functions

Expression Return Types

The type of value returned by an expression depends on the kind of controller:

• Float expressions return a floating-point scalar value (For example, 5.617). Scalars are used in the animation controllers of numeric parameters.

  If the parameter has an integer value, the expression rounds the float value to the nearest integer.

• Position, Scale, and Point3 expressions return a three-component vector. For example, [5, 18, 24]. The vector can represent an object's X,Y, Z location, percent scaling in X, Y, and Z, or a color (RGB values) in a material.

Operators

In the following tables, p and q are any scalar value or expression, V and W are any vector value or expression. (The character "x" is used as the vector cross-product operator.)

Scalar Operators

These are the arithmetic operators for scalar values:

Operator	Use	Meaning
+	p+q	addition
-	p-q	subtraction
-	-p	additive inverse
*	p*q	multiplication
/	p/q	division
^	p^q	power (p to the power of q);
**	p**q	^ and ** are the same operation

You can also use logical (Boolean) operators with scalar values. These operators all return 1 if true, 0 otherwise:

Operator	Use	Meaning
=	p=q	equal to
<	p<q	less than
>	p>q	greater than
<=	p<=q	less than or equal to
>=	p>=q	greater than or equal to
|	p|q	logical OR, returns 1 if either p or q is non-zero; otherwise, returns 0
&	p&q	logical AND, returns 1 if p and q are both non-zero; otherwise, returns 0

Note: Logical operators are useful with the "if" function.

Vector Operators

For vectors that have a variable name, you can use a special component operator (.) to refer to the three scalar components of the vector:

Use	Meaning
V.x	first component (X)
V.y	second component (Y)
V.z	third component (Z)

These are the operators for vector arithmetic:

Operator	Use	Meaning
+	V+W	addition
-	V-W	subtraction
*	p*V	scalar multiplication
*	V*p	scalar multiplication
*	V*W	dot product
x	VxW	cross product
/	V/p	scalar division

Operator Precedence

gmax expressions use eight levels of precedence. The higher the operator is on the list, the earlier it is evaluated.

Operator	Level of Precedence
- +	as unary operators; e.g., -8, +25
.	the component operator, as in V.x
** ^
x	cross product
* /
+ -
= < > <= >=
| &

Parentheses are a special case. They are a grouping or subexpression operator that is provided so you can override the precedence order of the other operators.

Variables

In gmax expressions, variables are represented by symbolic names. You create them to contain constant or variable values in your expressions. gmax also provides several predefined variables that have constant or variable values.

Predefined Variables with Constant Values

These are the predefined variables that have a constant value in gmax expressions (variable names are case-sensitive):

Variable Name	Constant Value	Use
pi	3.14159	Ratio of a circle's circumference to its diameter.
e	2.71828	Base of natural logarithms.
TPS	4800	Ticks per second; the basic time unit of gmax animation.

Predefined Variables with Variable Values

These are the predefined variables that have a variable, time-based value in gmax expressions (variable names are case sensitive):

Variable Name	Meaning
F	Frame number. For each frame, F equals the current frame number, counting from zero. The range of frames can vary depending on the number of frames in the active time segment.
NT	Normalized time. By definition, normalized time (NT) ranges from 0 to 1 over the active time segment, regardless of how many frames are in the segment. If you base an expression on NT, its effect happens exactly once over the range. You can also multiply NT by a factor for the expression's effect to occur a certain number of times (for example, 2*NT causes the expression's effect to occur twice). Expressions based on NT speed up or slow down if you change the length of the time segment.
S	Seconds (elapsed time in seconds). Elapsed time is measured from the first frame to the current frame. The range of seconds can vary depending on the total time of the active time segment.
T	Ticks (elapsed time in ticks). There are 4800 ticks per second. Elapsed time is measured from the first frame to the current frame. The range of ticks can vary depending on the total time of the active time segment.

Rules for Variable Names

• Variable names can contain as many alphanumeric characters as you like, their length is not limited.

• Variable names cannot contain spaces.

• The variable name must begin with a letter. Numbers are valid within a variable name (as in "Pos1" or "M23").

• Variable names are case-sensitive. For example, "pos", "Pos", and "POS" designate three different variables.

• You can't create a variable with a name that duplicates another name, including the variable names that are predefined.

Variables and Controllers

You can create a variable whose value varies over time by assigning a controller to it. The controller must be one of the tracks of a different object. The value of the variable will then vary according to how the other object's track varies over time.

There is one exception to the rule that the controller must belong to a different object; you can also assign Transform expressions to the same object's base parameters, and vice versa.

Vector Variables and Objects

You can assign vector variables to objects as well as controllers, making the result of the expression absolute to the local object. The value returned is the absolute value of the object relative to the world.

When you click Assign to Controller, the Hierarchy list is displayed with the valid controller and the valid objects in boldface text.

Global Variables

Use Global Tracks in the Track View Hierarchy to create global variables. Using expression controllers, you can point to a controller in the Global Tracks from several other tracks. Then, to change all of the other tracks, alter the expression in the Global Tracks.

Functions

Following is a list of functions provided for gmax expressions. In this list, p, q, and r represent scalar values or scalar expressions. V and W represent vector values or vector expressions.

To use a function in an expression, enter the name of the function and appropriate arguments to it.

Trigonometric Functions

The sine, cosine, and tangent functions take an angle in degrees and return a floating-point value. The arc functions take a floating-point value and return a value in degrees.

Function	Meaning
sin(p)	sine
cos(p)	cosine
tan(p)	tangent
asin(p)	arc sine
acos(p)	arc cosine
atan(p)	arc tangent

Hyperbolic Functions

Hyperbolic functions take a floating-point value and return a floating-point value.

Function	Meaning
sinh(p)	hyperbolic sine
cosh(p)	hyperbolic cosine
tanh(p)	hyperbolic tangent

Conversion Between Radians and Degrees

Rounding Functions

Standard Calculations

Conditional Functions

Vector Handling Functions

Note: The comp function is an alternative to the notation V.x, V.y, V.z.

Special Animation Functions

The arbitrary values p,q and r, are used as a random-generation seed. Re-use these values to ensure that noise() returns the same value.

See also

Expression Controller Techniques

Trigonometric Functions

Vectors

Procedures

To assign a constant value to a variable:

1. Highlight the variable name in the Scalars or Vectors list.

2. Click Assign to Constant.

3. In the dialog, enter the new value of the constant, and then click OK.

To assign a controller to a variable:

1. Highlight the variable name in the Scalars or Vectors list.

2. Click Assign to Controller.

   The Track View Pick subdialog is displayed, showing the track hierarchy. The display in the dialog is similar to the Track View Hierarchy.

3. Select the track for the variable to use, and then click OK.

Example: To create an expression that moves a sphere in a precise circle:

1. Create a sphere 30 units in diameter.

   Use Track View to create the Expression controller.

2. On the Main toolbar, click Track View.

3. In the Hierarchy list, expand Objects/Sphere01 so the sphere's Position track is visible. Select this track by clicking the Position label once to highlight it.

4. Click Assign Controller on the Track View toolbar.

   The Assign Controller dialog is displayed.

5. Select Position Expression from the list of controller types, and then click OK.

6. In the Expression Controller dialog, create the expression.

7. On the Track View toolbar, click Properties.

   The Expression Controller dialog is displayed.

8. Replace the default expression by typing the following position expression in the Expression field:

   [100*cos(360*NT), 100*sin(360*NT), 0]

9. Click Evaluate.

10. Play the animation. The sphere moves in a circle about the world origin (0,0,0). The radius of the circular path is 100 units.

    You've now specified a circular path for the sphere. NT is a variable that means normalized time. Movement based on NT happens exactly once per the active time segment, regardless of how many frames are in the animation.

Example: To change the radius of the circle:

The two 100s in the position expression from the previous procedure specify the radius. To adjust the radius of the circle's path, create a symbolic variable to represent the radius. The variable has a constant value that is easy to edit.

1. Make Track View visible again.

2. In the Expression Controller dialog, type radius in the Name field. Click Scalar, and then click Create.

   "radius" is displayed in the Scalars list in the lower-left of the dialog.

3. Click Assign to Constant.

   A dialog titled "radius" is displayed.

4. Type 150 in the value field, and then click OK.

   The radius variable is now 150.

   Now use the new variable in the expression.

Example: To replace the literal value with the variable name:

1. In the Expression field, change 100 to radius in both places. The expression should now look like this:

   [ radius*cos(360*NT), radius*sin(360*NT), 0]

2. Click Evaluate.

3. Play the animation. The sphere moves in a circle about the world origin (0,0,0). The radius of the circular path is 150 units.

Example: To make the sphere rotate about a box:

1. Create a box about 40 units square, and animate its position over three or four keyframes.

2. In the Expression Controller dialog, type boxposn in the Name field. Click Vector, and then click Create.

   The name "boxposn" is displayed in the Vectors list in the lower-left part of the dialog.

   Variable names are case sensitive; the variable name should be lower case.

3. Click Assign to Controller.

   The Track View Pick dialog is displayed. It shows the object hierarchy as it appears in the left side of Track View.

4. In the Hierarchy list, highlight the Position controller for Box01 and then click OK.

5. In the Expression field, add boxposn as an offset:

   [radius * cos(360*NT),
   radius * sin(360*NT), 0] + boxposn

6. Click Evaluate, and then click Close.

   Play the animation again. The sphere moves in a circle around the box and follows the box wherever it moves.

Interface

Create Variables group

Name: Contains the variable.

Scalar: Selects the type of variable to create.

Vector: Selects the type of variable to create.

Create: Creates the variable.

You must enter a name and specify a type before clicking Create.

Delete: Select a variable in the Scalar or Vector list, then click to delete it.

Variable Parameters group

Tick Offset: Contains an offset value.

A tick is 1/4800 of a second. If a variable has a non-zero tick offset, that value is added to the current time.

Expression group

Type an expression in the Expression box.

The expression must be a valid mathematical expression. The result is either a three-value vector for a vector expression (position, scale, or point3) or a scalar value for a float expression.

Description group

Type text in this group to document an expression. For example, you can describe user-defined variables.

Function list: Displays a list of Expression controller functions.

In the list, p, q, and r represent scalar values or scalar expressions; V and W represent vector values or vector expressions.

Save: Saves an expression. Expressions are saved as files with a .xpr file name extension.

Load: Loads an expression.

A saved expression does not save variable definitions or values. After loading the expression, you need to redefine them.

Debug: Displays the Expression Debug window.

This window displays the values of all variables, and the value of the expression. When you change the variables or move the time slider, the Debug window automatically updates so you can interactively view what's happening with the expression. The values for frames (F), normalized time (NT), secs (S), and ticks (T) are also displayed.

Evaluate: Evaluate the expression for each frame in the animation.

There is no explicit assignment (= or := operator) as in a conventional programming language; the assignment is implicit and takes place over time.

If the expression has a syntax error, an error message is displayed. The error message is the first part of the expression itself. The last character in the error message is the point of the error. This is usually where the error actually is, unless the problem is that opening and closing parentheses (or the braces for vectors) don't match. In this case, evaluation may proceed further before the error is detected.

Close: Closes the Expression Controller dialog.