Professional Documents
Culture Documents
Maya Tutorial Expressions PDF
Maya Tutorial Expressions PDF
Expressions
3 Introducing Expressions
About expressions
12
4 Quick Start
11
13
15
15
17
5 Expression Syntax
Expressions and MEL
32
43
46
47
49
Static attributes
49
Dynamic attributes
49
Custom attributes
Attribute names
50
51
51
28
45
Elements of an expression
Attributes
23
55
56
57
57
59
Expressions
Contents
Constants
62
63
Relational operators
65
Logical operators
Operator precedence
67
68
Conditional statements
if statements
69
69
if-else statements
70
else if statements
71
73
Comments in expressions
Programming features
75
75
75
63
76
77
88
90
91
93
95
95
6 Editing Expressions
Finding expressions
97
99
99
95
100
101
92
Expressions
Contents
Finding by item type
102
103
104
105
105
106
106
107
106
109
110
110
111
112
112
113
115
116
117
118
118
123
123
127
130
131
Disconnecting an attribute
132
132
135
Expressions
Contents
Renaming an object
136
137
140
141
141
142
143
8 Particle Expressions
147
148
149
149
150
150
152
153
159
159
160
162
183
183
167
169
164
189
175
172
174
Expressions
Contents
Assigning to vectors and vector arrays
List of particle shape attributes
9 Functions
193
196
203
Understanding functions
Function syntax
205
206
Data types
208
209
abs
209
ceil
210
floor
clamp
210
211
min
212
max
212
sign
212
trunc
213
Exponential functions
exp
214
log
214
log10
215
sqrt
215
Trigonometric functions
cosd
sin
sind
tan
tand
214
214
pow
cos
208
216
216
218
219
224
224
225
Expressions
Contents
acos
225
acosd
226
asin
226
asind
226
atan
227
atand
227
atan2
227
atan2d
228
hypot
228
Vector functions
229
angle
229
cross
230
dot
231
mag
rot
231
232
unit
233
Conversion functions
234
deg_to_rad
234
rad_to_deg
234
hsv_to_rgb
235
rgb_to_hsv
235
Array functions
clear
236
236
size
237
sort
237
239
noise
241
dnoise
rand
242
243
sphrand
239
244
Expressions
Contents
seed
246
Curve functions
linstep
249
249
smoothstep
hermite
254
General commands
eval
259
261
system
252
259
263
264
Expressions
Contents
10
Introducing Expressions
Expressions are instructions you type to control an object attribute over time.
An attribute is a characteristic of an object, for instance, X scale, Y translate,
visibility, and so on.
Though you can create an expression to animate attributes for any purpose,
theyre ideal for attributes that change incrementally, randomly, or
rhythmically over time.
Expressions
Eric Saindon
Expressions are also useful for linking attributes between different objects
where a change in one attribute alters the behavior of the other. For instance,
you can make the rotation of a tire dependent on the forward or backward
movement of a car.
This chapter has the following topics:
11
Introducing Expressions
About expressions
About expressions
Expressions offer an alternative to difficult keyframing tasks. In keyframing,
you set the values of attributes at selected keyframes in the animation, and
Maya interpolates the action between the keyframes. With expressions, you
write a formula, then Maya performs the action as the animation plays.
Expressions are often as simple as a few words or lines. In the following
example expressions, note the variation in length and detail (rather than
their purpose).
Example
Ball.translateX = Cube.translateX + 4;
Example
if (frame == 1)
Cone.scaleY = 1;
else
{
Cone.scaleY = (0.25 + sin(time)) * 3;
print(Cone.scaleY + "\n");
}
12
keys
constraint
motion path
Introducing Expressions
Where you create expressions
another expression
From the Channel Box, click the right mouse button in an attribute text field
and select Expressions.
From the Attribute Editor, click the right mouse button in an attribute text
field and select Create New Expression, Edit Expression, or Expression
Editor.
You cannot start the Expression Editor from every attribute text field in the
Channel Box and Attribute Editor. Use WindowExpression Editor if
necessary.
13
Expressions
Introducing Expressions
Where you create expressions
The Expression Editor follows:
The expression text field expands as you type text, so you can write
expressions of unlimited length. You can also edit expressions with a text
editor such as jot by selecting it from the Editor pull-down menu above the
text field.
14
Quick Start
The easiest way to learn about expressions is to work through examples. For
this reason, we provide the following introductory lessons. Expressions that
control particle attributes are more complex than for other objects. For
examples, see Chapter 8, Particle Expressions.
Expressions
15
Quick Start
Preparing for the examples
The General Preferences window appears.
Drag either side of the General Preferences window to expand its width. You
must do this to display the Units tab in the window.
2
In the Units tab, make sure Time is set to Film (24 fps).
This makes your animation play at the default rate of 24 frames per second.
Enter 0 for the starting frame of the Time Slider and the Range Slider, and
enter 300 for the ending frame of the Time Slider and Range Slider.
Important
For the lessons to work correctly, you must enter 0 for the starting frame of
the Time Slider and Range Slider. Press your keyboards Enter key after
each entry. Rewind the animation to frame 0. After doing the lessons, read
Notes on the predefined time variable on page 43 for details on why the
lessons require the starting frame to be 0.
Specifying a range of 300 frames gives ample time to see the effects youll
create in the examples.
6
16
Quick Start
Creating a simple expression
9
Make sure these default Expression Editor menu options are selected:
Select FilterBy Object/Attribute Name
Object FilterSelected Objects
Attribute FilterAll
Finding expressions in Chapter 6 gives details on these options.
17
Expressions
Quick Start
Creating a simple expression
Ball.scaleY = time + 1;
Enter the expression with the same upper and lowercase spelling shown.
Entries in the expression field are type case sensitive.
The semicolon (;) signifies the end of the expression statement. Each
statement in an expression must end with a semicolon. The only exception is
when the expression has a single statement.
An error message appears in the Script Editor and Command Lines
response area if the expression has incorrect syntax or typing mistakes.
Edit text the same way you edit other text fields in Maya.
18
Quick Start
Creating a simple expression
6
0.0417
0.0833
0.125
24
1.0
240
10.0
Expressions
Frame
If you ever need to change the playback rate, you can do so by choosing
OptionsGeneral Preferences. Expand the General Preferences window,
display the Units folder, and choose the desired rate from the Time menu.
Regardless of what animation playback rate you choose, you can find the
time elapsed in the animation at any frame with this formula:
frame
time = --------------rate
For example, if the frame rate is 24 frames/second and the animation is at
frame 1, the elapsed time is 1 divided by 24, or 0.0417. At frame 6, the
elapsed time is 6 divided by 24, which equals 0.25.
Using Maya: Hypergraph, Sets & Expressions
19
Quick Start
Creating a simple expression
If the frame rate is 30 frames/second and the animation is at frame 1, the
elapsed time is 1 divided by 30, which equals 0.0333. At frame 6, elapsed
time is 6 divided by 30, which equals 0.2.
Time (seconds)
Ball.scaleY (time + 1)
0.0417
1.0417
0.0833
1.0833
0.125
1.125
24
1.0
2.0
240
10.0
11.0
Maya executes the expression each frame. This causes the object size to scale
along its Y-axis, stretching its height during playback.
The scaling is smooth because the geometry stretches in synch with the small
time increments of the animation playback.
20
Quick Start
Creating a simple expression
2
remembering the name of the object and attribute you controlled with the
expression
21
Expressions
Quick Start
Creating a simple expression
Ball.scaleY = time + 1;
Use the same editing techniques you use with other text fields in Maya.
By dividing time by 2, youll make the Y scaling increase half as fast as with
the previous version of the expression.
5
Summary
In this lesson, you learned how to:
22
Quick Start
Controlling multiple attributes of an object
modify an expression
Expressions
23
Quick Start
Controlling multiple attributes of an object
This names the expression so you can find it more easily later.
3
The expression has three statements. Each statement sets an attribute to the
value of the predefined variable time.
4
24
Quick Start
Controlling multiple attributes of an object
Planet.scaleX = time;
Planet.scaleY = Planet.scaleX;
Planet.scaleZ = Planet.scaleX;
25
Quick Start
Controlling multiple attributes of an object
The advantage of this expression is that if you assign a different value to
Planet.scaleX in the first statement, the second and third statements
automatically receive the new value. In other words, youve linked
Planet.scaleY and Planet.scaleZ to the value of Planet.scaleXwhatever its
value is.
4
The expression has the same result as the previous one. The first statement
defines a variable named $increment to be used as storage for the value of a
time increment. You define it as a floating point numbera number that can
have a decimal point.
The second statement assigns $increment the value of time divided by 5. As
the animation plays and the time increases each frame, the value of
$increment increases by the value of time divided by 5. The $increment
therefore increases in smaller units than time increases.
26
Quick Start
Controlling multiple attributes of an object
The next three statements assign the contents of $increment to the three scale
attributes of Planet. The scale attributes therefore receive the value of time
divided by 5 each frame. This makes the object increase uniformly in scale
slowly as the animation plays.
2
Click Edit.
Click Edit.
Summary
In this lesson, you learned how to:
27
Expressions
Quick Start
Controlling attributes in two objects
To see an objects local rotation axes, select the object, then choose
DisplayObject ComponentsLocal Rotation Axes.
28
Quick Start
Controlling attributes in two objects
Select Can.
To control attributes in both objects, you can select either object to write the
expression. In fact, any object or node in a scene can be selected when you
write an expression to control an object other than a particle object. For
details on creating expressions to control particles, see Chapter 8, Particle
Expressions.
This assigns Cans rotateX attribute and Cones rotateX attribute to the value
of time multiplied by 10.
4
Each object rotates around its local X-axis by the degree value resulting from
time * 10. After 1 second, for example, the rotateX attribute of each object is
one degree times 10, or 10 degrees. After 2 seconds, its 2 degrees times 10,
or 20 degrees.
Maya works in degree angle units, by default. You can change the angular
units to radians by choosing OptionsGeneral Preferences and displaying
the Units folder.
29
Quick Start
Controlling attributes in two objects
With the animation playing at 24 frames per second, each objects rotateX
attribute has these values:
Frame
Time
Can.rotateX
(degrees)
0.0417
0.417
0.0833
0.833
0.125
1.25
24
1.0
10
240
10.0
100
The values in this chapter are rounded to four significant digits. The actual
values might have many more digits.
To see the degree value of Can.rotateX at different frames, select Can,
display the Channel Box, and stop the animation at selected frames. The
Channel Box updates its values after you stop the animation.
To see the degree value of Cone.rotateX at different frames, select Cone
instead of Can. The Channel Box displays values for the selected object.
2
30
Quick Start
Controlling attributes in two objects
Before starting the next example, delete the scene and create a new scene.
Summary
In this lesson, you learned how to:
31
Expressions
The advantage of using a single expression to control the attributes is that all
statements are in a single expression. You dont need to edit two
expressions.
Quick Start
Controlling attributes conditionally
Select Balloon.
32
Quick Start
Controlling attributes conditionally
Important
When you compare the value of time to a number in an expression, Maya
interprets time as seconds rather than milliseconds, minutes, or any other
unit of time. In the example, Maya interprets 2 as 2 seconds.
The expression checks whether the value of time is less than two seconds. If
so, it does the assignment Balloon.scaleY = time. If time is not less than two
seconds, the assignment doesnt occur.
Notice the indentation of Balloon.scaleY = time under if (time < 2). Maya
ignores all indentation, extra spaces, and blank lines between statements. We
used the indentation to make the expression easier to read. You could have
also written the expression as follows:
if (time < 2) Balloon.scaleY = time;
The expression executes when you click the Create button. Because the
animation is at frame 0, animation time is 0. Because time is less than 2,
Maya sets Balloon.scaleY equal to the value of time, which equals 0.
A scaleY value of 0 flattens the object in the Y dimension.
5
33
Quick Start
Controlling attributes conditionally
Time (seconds)
Balloon.scaleY (time)
0.0417
0.0417
0.0833
0.0833
0.125
0.125
24
1.0
1.0
47
1.96
1.9583
48
2.0
1.9583
49
2.04
1.9583
The if statements condition, (time < 2), is a comparison. The condition must
be surrounded by parentheses to isolate it from assignment that follows it.
34
Quick Start
Controlling attributes conditionally
The < in the condition is a relational operator. A relational operator tests
how one value relates to another. In the example, the < tested whether time
is less than 2.
Besides the < operator shown in this example, there are several other
relational operators such as >, >=, ==, and so on. See Arithmetic, logic, and
relational operators in Chapter 5.
6
35
Expressions
Quick Start
Controlling attributes conditionally
Important
Always examine the Script Editor for error messages after you edit an
expression and click the Create button. If you alter a previously successful
expression and a syntax error occurs, Maya executes the previous
successful expression when you play the animation. This might make you
believe your editing changes took effect.
4
Balloon doesnt return to the origin because the expression doesnt assign
Balloon a starting point for the beginning of the animation.
5
36
Quick Start
Controlling attributes conditionally
Note that you can put the three statements in any order in this example.
When Maya plays each frame, it executes each statement in the expression in
the order listed. In this example, the statements work independently, so their
order doesnt matter.
We put the statements in the order of time execution because its easier to
see the logic of the expression. If you ever need to change the expression,
youll be able to grasp the expressions actions more quickly.
6
Click Edit.
Click Edit.
37
Quick Start
Controlling attributes conditionally
Balloon inflates for 2 seconds, then rises slowly with time from its position at
the origin.
When time is greater than or equal to 2, the translateY position of Balloon
becomes 2 minus 2, which is 0. As time increases beyond 2 seconds, the
translateY position increases in the same increments that time increases.
Click Edit.
38
Quick Start
Controlling attributes conditionally
At any instant in the animations playback, either Balloon.scaleY = time
executes or Balloon.translateY = time - 2 executes. Under no circumstances
can they both execute. The else statement executes only when the if
condition that precedes it is false.
Note that we added a blank line between the first if statement and the if-else
statement combination. This has no effect on the execution of the statements.
We put it there to emphasize that the two if statements are unrelated.
The first if statement executes whenever time equals 0. It is unrelated to the
if-else statements.
Using else statements instead of multiple if statements makes an expression
simpler to read. If you use an if-else construction instead of a lengthy list of
if statements, youll also improve the execution speed of the expression. This
improves your animations playback and rendering speed.
Either expression is valid. If using the if-else construction seems confusing,
stick with multiple if statements.
You can accomplish most expression animation tasks with several if
statements strung after one another.
4
Click Edit.
Using Maya: Hypergraph, Sets & Expressions
39
Quick Start
Controlling attributes conditionally
3
Only one statement is different, Balloon.scaleY = time * 0.6. The asterisk (*)
multiplies time by 0.6.
40
Click Edit.
Quick Start
Controlling attributes conditionally
Click Edit.
Balloon disappears from view because its scale attributes are 0.
The scaleX, scaleY, and scaleZ attributes are 0 at frame 0 because time is 0.
Any number multiplied by 0 is 0.
41
Quick Start
Controlling attributes conditionally
As time increases, the value of Balloons scale attributes increase. Because
the expression sets scaleX and scaleZ to 50% of the value of time, these
dimensions scale slower than scaleY, which is set to 60% of the value of time.
Balloon scales faster in height than in width or depth. This is true for many
real balloons.
Summary
Using an expression is a combination of logic and experimentation. Problem
solving starts with breaking a task into smaller problems you can solve and
later refine.
In this lesson, you learned how to:
42
Quick Start
Notes on the predefined time variable
In the preceding examples we didnt include comments in expressions
because we explained them line by line. When you write your own
expressions, include comments with statements to help document how the
expression works.
This will help you or someone else understand how your expression works
later if the need to enhance it arises. See Comments in expressions in
Chapter 5.
This discrepancy means the Ball scaleY is larger than its scaleX and scaleZ
attributes in the first frame of the animation. Though the difference is not
substantial in this example, other cases might be more significant.
To start your animation at frame 1 and get the same result as the example,
you can subtract 0.0417 from the attribute:
Ball.scaleY = (time - 0.0417) + 1;
When you rewind the animation, the expression sets Balls scaleY value to
(0.0417 - 0.0417) + 1. This equals 1, its original scaleY value.
When you use the predefined time variable, be aware of the starting frame
number and the associated time value.
43
Expressions
If you rewind the animation, the expression executes and sets the initial
value of Balls scaleY attribute to time + 1, which equals 0.0417 + 1, or 1.0417.
Because Balls scaleY attribute was 1 when you created it, rewinding the
animation sets scaleY to a value 0.0417 larger than its initial value.
Quick Start
Notes on the predefined time variable
After doing the lessons in this chapter, remember to change your Time
Sliders starting frame, ending frame, and frame rate to the desired values
when you start other projects. To do this, select OptionsGeneral
Preferences and display the appropriate tabs in the General Preferences
window.
44
Expression Syntax
Expressions use the syntax of the Maya Embedded Language (MEL).
Though MEL is a scripting language, youll find the syntax easy to learn
even if youve never programmed. Mastering the rules of syntax is essential
to writing expressions without errors.
Tristan Ikuta
Attributes on page 49
Variables on page 56
Constants on page 62
45
Expressions
Expression Syntax
Expressions and MEL
Typical use
MEL command
MEL script
Expression
46
Expression Syntax
Elements of an expression
Elements of an expression
An expression is made of one or more statements. Statements follow the
rules of algebra, so theyll seem familiar if youve studied math. Each
statement has several elements as in the following example:
Assignment operator Arithmetic operator
Attribute name
Function Constant
Ball.rotateZ = sin(time) + 6;
Terminator
Statement
Variable
47
Expressions
Function
Expression Syntax
Elements of an expression
A variable is a symbolic name that stands for a changing
value. You can assign a value to a variable or read a
variables value. The variable time is a predefined Maya
variable that contains the animation time at the current
frame. You can read but not set the value of time.
Variable
Arithmetic, logic,
or relational
operator
An operation such as + or < (less than).
Constant
Terminator
Example
Heres an expression with the fewest elements possible:
Value assigned
Ball.scaleY = 5;
48
Expression Syntax
Attributes
Attributes
An attribute is a characteristic of an object or other item in a scene. There are
many ways to set attributes in Mayawith the Attribute Editor, Channel
Box, menu selections, and of course, expressions. You can set attributes to
control virtually anything in your animation.
There are three types of attributes you work with in Maya:
static
dynamic
custom
Static and dynamic attributes have a predefined purpose. They are standard
attributes Maya provides for objects and items that make up a scene. Custom
attributes are attributes you define for an object.
Static attributes
Static attributes are attributes an object has by default. They exist the
moment you create the object and throughout its lifetime.
Expressions
For example, the transform node of a NURBS sphere has static attributes
scaleX, scaleY, scaleZ, rotateX, and so on. You can set the values of these
attributes with the Attribute Editor, Channel Box, expressions, and other
techniques after you create the object.
Dynamic attributes
Dynamic attributes have predefined names and purposes, but Maya adds
them to an object in response to your user interface selections.
For example, suppose you create a particle object and display its particle
shape folder in the Attribute Editor. If you click one of the following buttons
in the Add Dynamic Attributes section of the Attribute Editor, Maya adds a
dynamic attribute to the node:
Clicking the General button lets you add a custom attribute (see the next
topic). Clicking any of the other buttons lets you add one or more dynamic
attributes with names that are the same or similar to the button name.
Using Maya: Hypergraph, Sets & Expressions
49
Expression Syntax
Attributes
An object has no dynamic attributes unless your actions cause Maya to add
them to the object. By adding only required attributes, Maya runs faster.
When you add a dynamic attribute to an object, the attribute appears in the
Attribute editor for the selected object or node.
Note
Because soft body geometry is a particle shape node coupled with
geometry, a soft body has the same static and dynamic attributes as a
particle object.
Custom attributes
Custom attributes are attributes you optionally add from the New folder of
the Add Attribute window.
50
Expression Syntax
Attributes
Such attributes have no direct effect on any characteristic of an object.
Theyre often used to control a combination of other attributes. You might
also use a custom attribute as a variablea place to store a value
temporarily to be read by other attributes.
When you add a custom attribute to an object, it appears in the Attribute
Editor and Channel Box for the object or node. Though custom attributes are
dynamically added to an object, we refer to them as custom to distinguish
them from the built-in dynamic attributes.
See Assigning to a custom attribute in Chapter 8 for details on how to add
and use a custom attribute.
Attribute names
Static, dynamic, and custom attributes follow the same naming conventions
and represent the same types of data.
A full attribute name has this format:
object.attribute
where object is the name of the object node, and attribute is the name of the
attribute. A period (.) separates the name of the object and attribute.
Example
Ball.scaleY
51
Expressions
You must spell the object and attribute name with uppercase and lowercase
letters as they appear in the Expression Editors Objects and Attributes lists.
You cannot spell attribute names with the common English spellings shown
in the Attribute Editor or by default in the Channel Box.
Expression Syntax
Attributes
Attributes youll work with in expressions have these data types:
Data type
Meaning
Example attribute
Example data
float
Balloon.scaleY
-2.3333333333
integer
Ball.sections
16
Boolean
on or off selection
Ball.visibility
on
Meaning
Example attribute
Example data
vector
array
array of vectors
FireShape.position
float
array
array of floating
point numbers
FireShape.lifespan
1.333
1.666
2.333
1.333
Note
Scientists often refer to a vector as a quantity that specifies both a
magnitude and direction. In Maya, a vector is simply a related group of
three floating point numbers that set an attribute or variable.
52
Expression Syntax
Attributes
Vector array data types are useful for animating position, velocity,
acceleration, color, and other particle attributes made of three components.
Float array attributes are useful for setting lifespan, opacity, and other
particle attributes that have a single number value.
Attributes having a vector array or float array data type are also called per
particle attributes. See Chapter 8 for details on working with particle
attributes.
If you have programming experience, note that for vector array data types,
Maya represents the specified attribute for each particle of the object with a
single element of an array. Each element is made of three floating point
numbers. In a float array, Maya represents the specified attribute for each
particle with a vector array element thats a floating point number.
Note
In expressions, you must type a vector in double angle brackets (<< >>).
For example, type <<3,0,5>> for a vector having 3, 0, and 5 as its left,
middle, and right component.
Expressions
Static and dynamic attributes have predefined data types. To learn the
attributes data type, select the node containing it. In the Attribute Editor,
find the attribute name and examine its data format.
53
Expression Syntax
Attributes
Heres an example display of attributes with floating point, Boolean, and
integer data types:
Floating point
Boolean
Integer
A floating point attribute shows a value that includes a decimal point. Most
numerical attributes in Maya are floating point.
A Boolean attribute has a checkbox or other user interface item for turning it
on or off.
An integer attribute has no decimal point. Integer attributes are rare in
Maya.
The data type of an attribute limits what type of value you can enter for the
attribute in the Attribute Editor and in expressions. For example, because a
directional lights Depth Map Filter Size attribute is an integer, you cannot
enter a decimal point in its text entry box or assign it a decimal quantity in
an expression.
For a floating point attribute, you can omit the decimal point. The Attribute
Editor automatically inserts a decimal point in the attributes text field after
you press the Enter key. For example, if you type 3 for a floating point entry,
the Attribute Editor replaces 3 with 3.0000.
54
Expression Syntax
Attributes
An expression also automatically converts an integer to a floating point
value when appropriate. See Data type conversions in Chapter 7 for
details.
Only particle objects, not geometric objects, have vector array and float array
attributes. The static vector array attributes for particle objects are position,
velocity, and acceleration. These are also called per particle attributes
because you can set the attribute for each particle to different values.
Maya has other attribute data types that are irrelevant to the use of
expressions. For example, Maya has a matrix data type that is useful only in
MEL scripting and API programming.
You can assign a value to any attribute. If the attribute is dynamic or custom,
though, you must add the attribute to the object before you can assign it a
value in an expression.
Become familiar with the purpose of an attribute by working with it in the
Attribute Editor, Channel Box, or other parts of Maya before assigning it a
value in an expression. Its best to know the behavior you can expect from
the attribute in case you write your expression incorrectly.
Note
For rigid bodies, you can read but not write the velocity, angularVelocity,
and force attributes.
55
Expressions
Because you choose the data type of custom attributes when you add them
with ModifyAdd Attribute, you do not define their data type either.
Expression Syntax
Variables
Examples
Cone.scaleY = 5.3;
This assigns the value of time to the floating point translateY attribute of
Ball.
Ball.scaleX = Ball.scaleY = Ball.scaleZ = 2;
This assigns 2 to the floating point scaleX, scaleY, and scaleZ attributes of
Ball. As the example shows, you can use an assignment operator several
times in a statement to set multiple attributes to the same value.
Variables
A variable is a symbolic name that stands for a constant or changing value.
There are two types of variables, predefined and custom.
Maya creates and maintains predefined variables. Custom variables are
variables you can create to store data in an expression.
56
Expression Syntax
Variables
Keep in mind that attributes, not variables, set object and component
behavior in Maya. You can use variables to as temporary storage for
working with the attributes.
Meaning
Examples
Defining
keyword
float
392.6, -0.667
float
integer
10, -5, 0
int
vector
vector
string
string
The most common data type of variables is floating point. Integer data types
are rarely used. Booleans are commonly used in attributes, but not allowed
in variables. Vector variables are useful in expressions for particle shape
attributes.
For a custom variable you create in an expression, you must declare the data
type as described in Custom variables on page 59.
Predefined variables
Maya maintains values in two predefined variables as an animation plays:
Variable
Contents
Data type
frame
float
time
float
57
Expressions
Expression Syntax
Variables
Your expressions can read, but not set, the value of time and frame. These
variables are floating point values that are useful for animating an attribute
as an animation plays.
The time updates as an animation plays. It contains the elapsed number of
seconds from the first frame to the current frame. The value increases with
the increasing frame number.
At the default animation playback rate of 24 frames per second, time has
these values, rounded to four decimal places:
Frame
Time (seconds)
0.0417
0.0833
0.125
24
1.0
240
10.0
frame
time = --------------rate
For example, if the frame rate is 24 frames/second, and the animation is at
frame 1, the elapsed time is 1 divided by 24, or 0.0417. At frame 6, the
elapsed time is 6 divided by 24, which equals 0.25.
If the frame rate is 30 frames/second and the animation is at frame 1, the
elapsed time is 1 divided by 30, which equals 0.0333. At frame 6, elapsed
time is 6 divided by 30, which equals 0.2.
58
Expression Syntax
Variables
Theres an advantage to writing an expression using the value of time rather
than frame: You wont need to modify your expression if you change your
animations frame rate.
Note that time is always 0 at frame 0. As each frame plays, the time increases
in increments resulting from the frame rate.
Its impossible to set time to a value other than 0 at frame 0. If you set
Mayas frame range to begin at a negative number, time has a negative
value.
Examples
Ball.translateY = time/2;
This sets the Balls Y translation equal to the value of time divided by 2 as
the animation plays. This make the Ball move in a Y direction as the
animation time increases.
Ball.scaleY = frame/2;
This sets the Balls Y scale equal to the value of frame divided by 2 as the
animation plays. The Ball scales along its Y axis as the animation frame
number increases.
Custom variables
Declaring variables
Each custom variable name must begin with a dollar sign character ($). After
the $, you can use alphabetical, numerical, and underscore characters. You
cannot include spaces in the names.
Variable names are type case sensitive. In other words, $temp is a different
variable name than $Temp.
59
Expressions
You can declare and use variables to store a constant or changing value.
These work like their counterparts in programming languages and
spreadsheet programs.
Expression Syntax
Variables
Examples
float $object_height;
Examples
float $counter = 5.3;
This declares a floating point variable named $counter and gives it an initial
value of 5.3.
$height = 6;
This declares a floating point variable named $height and gives it an initial
value of 6. This example shows you can skip declaring the variables data
type. When you assign a variable a value, Maya assumes the variable is
floating point unless you specify a different data type.
$pi = 3.1415927;
$twist = $pi;
These statements show you can assign the value of one variable to another
variable. The first statement assigns 3.1415927 to $pi. The second statement
assigns the contents of $pi, 3.1415927, to $twist.
60
Expression Syntax
Variables
Important
If you misspell an existing declared variable name and assign it a value, a
syntax error wont be generated for the undeclared variable. Because Maya
automatically provides a data type for an undeclared variable if its on the
left side of the assignment operator, the misspelled variable will be
interpreted as a newly added variable. Undeclared variables on the right
side of the assignment operator do generate error messages.
Check spellings of variables if your expression isnt working as expected.
In the following example, the misspelling in the final statement generates
an error but not the misspelling in the statement before it:
int $start;
int $end;
int $interrupt;
$starrrt = 1;
$end = $interrupppt;
Example
global float $counter;
You can thereafter set or read the value of this variable in any other
expression in the scene.
If you create a variable with the same name in two expressions, the two
variables are separate and unrelated. For example, suppose you create a
variable named $timer in two expressions. Assigning a value to one of the
$timer variables has no effect on the others value.
Using Maya: Hypergraph, Sets & Expressions
61
Expression Syntax
Constants
If you declare and initialize a global variable in a single statement, you can
initialize it to a numerical constant or string only.
Examples
global float $counter = 3;
Example
global float $counter = 3;
print($counter+"\n");
$counter = 1000;
print($counter+"\n");
Constants
A constant is an unchanging number or variable.
Examples
Ball.translateY = 6.1.
This statement sets Balls translateY attribute to the constant number 6.1.
float $pi = 3.1415927;
Ball.rotateY = $pi;
These statements set the value of Balls rotateY attribute to the value of the
variable $pi. The variable $pi represents the constant 3.1415927.
62
Expression Syntax
Arithmetic, logic, and relational operators
Arithmetic operators
Symbol
Meaning
plus
minus or negation
divided by
integer, float
remainder of division
integer, float
Examples
Car.translateX = time / 2.0;
This moves the Car in an X direction as the time increases in the animation.
By dividing time by 2.0, you move the object half as fast as if you used time
alone.
Car.translateX = 7 % 3;
This assigns Car.translateX the value 0.4, the remainder of 8.8 divided by 4.2.
The number 8.8 divided by 4.2 equals 2 with a remainder of 0.4.
Car.translateX = 0.5 % 3;
63
Expressions
For integer and floating point attributes and variables, the above arithmetic
operators work according to the rules of basic math. Note that the modulus
operator (%) calculates the remainder of division.
Expression Syntax
Arithmetic, logic, and relational operators
This assigns Car.translateX the value 0.5, the remainder of 0.5 divided by 3.
The number 0.5 divided by 3 equals 0, with a remainder of 0.5.
Vectors
For operations between vector attributes and variables, the * operator
performs the dot product. The dot product multiplies corresponding
components of each vector, then adds the components to create a single
floating point number result.
For + and - operators, each component of one vector is operated on by its
counterpart component in the other vector.
For operations between a vector and an integer or floating point number,
each component of the vector is operated on by the integer or floating point
number.
Examples
Suppose youve initialized these vectors:
vector $A = <<1,2,3>>;
vector $B = <<2,3,4>>;
vector $C;
float $myfloat;
You then use the following statements (in different expressions, not in
sequential order):
$C = $A + $B;
This assigns $myfloat the value (1*2) + (2*3) + (3*4), which equals 20.
Multiplying two vectors gives the dot product of the vectors.
$C = 3 * $A;
This assigns $C the value <<3, 6, 9>>. Each component of the vector is
multiplied by 3 to create a vector result.
64
Expression Syntax
Arithmetic, logic, and relational operators
Strings
For details on how to use the + operator with strings, see String usage on
page 90.
Note
Maya handles integer and Boolean attributes in an expression
mathematically as floating point numbers. After the expression executes,
Maya converts the floating point number to the proper data type.
If your expression does arithmetic on an integer or Boolean attribute and
you display the attributes contents in the Script Editor, youll see floating
point values. After the expression executes, Maya assigns an appropriate
integer or Boolean value to the attributes you set in the expression text
field.
Maya handles integer and Boolean variables within an expression
mathematically as integer and Boolean data types.
Relational operators
Youll often use relational operators to compare the value of variables and
attributes in conditional statements. See Conditional statements on page
69.
Meaning
<
less than
>
greater than
==
equal to
!=
not equal to
>=
<=
Expressions
Symbol
65
Expression Syntax
Arithmetic, logic, and relational operators
Examples
if (time > 10)
Sphere.translateX = 3;
When the animation time is greater than 10 seconds of play, the expression
sets the Spheres translateX attribute to 3. It stays fixed in this position
thereafter. See Conditional statements on page 69 for details on the if
condition in this and following examples.
if (Ball.scaleY == 3)
Cone.scaleY = 6;
Important
Be careful to type == rather than = for the equal to operator.
For example, suppose you type if (Ball.scaleY = 3) in the previous example.
Rather than test whether Ball.scaleY is equal to 3, the statement assigns 3 to
Ball.scaleY.
Maya evaluates the assignment statement Ball.scaleY = 3 as a true
condition, so it executes Cone.scaleY = 6. This statement doesnt cause an
error message, but it gives unintended results.
Vectors
If you use the == or != operators between two vector attributes or variables,
Maya compares the corresponding components of each vector. In contrast,
the >, >=, <, and <= operators compare the magnitude of two vectors.
Use this formula to calculate a vectors magnitude:
2
x +y +z
Examples
vector $A = <<1,2,3>>;
vector $B = <<1,2,3>>;
if ($A == $B)
Sphere.translateX = 3;
66
Expression Syntax
Operator precedence
Notice that each condition is grouped in parentheses, and the pair of
conditions are enclosed again in parentheses. If you use multiple conditions
with logical operators, you must enclose all the conditions in parentheses for
the if statement.
If you omit the outer pair of parentheses as in the following example, an
error message occurs:
if (time > 5) && (time < 10)
Ball.scaleZ = time;
Example 2
if ((Ball.translateX < 5) || (Ball.translateY > 10))
Ball.scaleZ = time;
This sets Balls scaleZ attribute to the value of time in either of two
conditions: when Balls translateX attribute is less than 5 or greater than 10.
Operator precedence
The precedence of operators in expressions follows:
Highest
() []
! ++ - * / % ^
Lowest
68
Expression Syntax
Conditional statements
Examples
Ball.scaleY = 8 + 2 * 4;
This assigns Ball.scaleY the value 10. The + executes first because its further
to the left in the statement than the -.
Conditional statements
Conditional statements set one attribute or variable based on the condition
of another attribute or variable. For example, you might increase the scale of
a balloon after frame 48 plays.
The if and if-else statements are the most commonly used conditional
statements in expressions.
Youll often use relational and logical operators in conditional statements.
See page 65 and page 67 for details.
Expressions
If you have programming experience, be aware you can use loop and flow
control statements such as while and for. See Programming features on
page 75.
if statements
The if conditional statement has this format:
if ( condition )
statement;
Example
if (time > 3)
Ball.scaleY = 2;
This sets the scale of Balls scaleY attribute to 2 after the animation plays
three seconds.
69
Expression Syntax
Conditional statements
if-else statements
The if-else conditional statement has the following format:
if ( condition )
statement1;
else
statement2;
Notice you must enclose the multiple statements between braces ({ }).
70
Expression Syntax
Conditional statements
If the animation time is less than 2 seconds, the expression sets Balloons
translateY attribute to 0, and sets its scaleY attribute to the value of time
multiplied by 0.6.
If animation time is greater than or equal to 2 seconds, the expression sets
Balloons translateY attribute to time minus 2, and sets its scaleY attribute to
1.
Important
You cannot set the same attribute in two different expressions. If you try to
do so, an error message results and your second expression has no effect.
else if statements
The else if statement works with the if-else conditional statement and has
this format:
if (condition1 )
statement1;
else if ( condition2 )
statement2;
71
Expressions
Expression Syntax
Conditional statements
Example
if (time < 3)
Ball.scaleY =
else if ((time >= 3)
Ball.scaleY =
else
Ball.scaleY =
1;
&& (time =< 6))
2;
3;
This sets Balls scaleY attribute to 1 if animation time is less than 3 seconds.
If animation time is between 3 and 6 seconds, scaleY is 2. Otherwise, when
time is greater than 6 seconds, scaleY is 3.
Note that you can add multiple else if statements and multiple statements
within braces ({ }) using this format:
if (condition1 )
{
statement;
statement;
}
else if ( condition2 )
{
statement;
statement;
}
else if ( condition3 )
{
statement;
statement;
}
else if ( condition4 )
{
statement;
statement;
}
else
{
statement;
statement;
}
72
Expression Syntax
General syntax rules
If you look closely, youll see that there are three opening parentheses, but
only two closing parentheses. The next statement causes no error:
Ball.rotateZ = deg_to_rad(-6 * (floor(time)));
Expressions
There are three matching closing parentheses for the three opening
parentheses.
When you use { and } as opening and closing braces, make sure you use
them in matching pairs:
if (time > 3)
{
Ball.rotateZ = deg_to_rad(-6 * (floor(time));
Ball.rotateY = Ball.rotateZ * 3;
}
Spaces before and after the numbers and commas are optional.
Begin any variable you use with a dollar sign ($), and do not to use spaces or
special characters other than underscores in the name. Heres an acceptable
example:
float $my_Rotate;
$my_Rotate = 3.14;
73
Expression Syntax
General syntax rules
instead of this:
if (Ball.scaleY = 3)
Cone.scaleY = 6;
You can use as many spaces, tab characters, and blank lines as you like when
separating words, operators, or statements. Maya ignores white space in an
expression.
For example, suppose youve written this expression:
if (time < 2)
{
Balloon.translateY = 0;
Balloon.scaleY = time * 0.6;
}
else
Balloon.translateY = time - 2;
You must include at least one space between any two keywords, variables,
or attribute names (or combination of these). So a space is required after the
else keyword but in no other place in this expression.
To simplify spacing considerations, remember to put at least one space
before and after a keyword, variable, operator, attribute, assignment
operator, and so on.
Consistent use of white space makes expressions easier to read. Examples
throughout this chapter show examples of good spacing style.
74
Expression Syntax
Comments in expressions
Comments in expressions
Add comments to your expressions to explain the purpose of each statement
within. Youll appreciate this later if you need to modify the expression.
Maya ignores comments.
Programming features
Expressions
After you type an expression in the Expression Editor, clicking the Create or
Edit button compiles the expression.
ANSI C has 32 keywords. The expression language has less, as listed in the
following topic.
Using Maya: Hypergraph, Sets & Expressions
75
Expression Syntax
Programming features
Mayas integer data type has the same numerical range as ANSI Cs integer
data type, -2,147,483,648 to 2,147,483,648.
Mayas float data type has the same numerical range as ANSI Cs double
data type.
float
vector
string
matrix
on
off
true
false
in
no
else
for
while
do
break
continue
default
switch
case
source
catch
alias
Other keywords
global
return
proc
The return, proc, and matrix keywords are useful for writing MEL scripts,
not for expressions. Other keywords above are described throughout this
chapter.
Type keywords in lowercase letters exactly as shown. Do not name a custom
attribute with any of these keywords.
76
Expression Syntax
Programming features
Important
Using a while, do, or for loop incorrectly might halt Maya. See Flow
control errors on page 88 for details.
while
A while loop has this format:
while ( condition )
{
statement;
statement;
...
}
Example
float $test = 0;
while ($test < 5)
{
print("$test equals: " +$test+"\n");
$test = $test + 1;
}
77
Expressions
Expression Syntax
Programming features
This expression displays the following lines in the Script Editor:
$test
$test
$test
$test
$test
equals:
equals:
equals:
equals:
equals:
0
1
2
3
4
This message indicates that a MEL command executed when you clicked the
Create or Edit button in the Expression Editor. Specifically, an expression
command executed. This is unrelated to the exact statements in the
expression.
do
A do loop has this format:
do
{
statement;
statement;
...
}
while (condition);
Here Maya executes each statement between braces, then evaluates condition.
The condition compares variable, attribute, or constant values. If condition is
true, each statement executes again. The loop terminates when condition is
false.
In contrast to a while loop, a do loop executes the statements in the loop at
least once. It tests the termination condition after the loop. A while loop tests
the termination condition before executing the statements in the loop.
Example
float $test = 0;
do
{
print("$test equals: " +$test+"\n");
$test = $test + 1;
}
while ($test < 5);
78
Expression Syntax
Programming features
This expression displays the following lines in the Script Editor:
$test
$test
$test
$test
$test
equals:
equals:
equals:
equals:
equals:
0
1
2
3
4
for
A for loop has this format:
for (initialization; condition; change of condition)
{
statement;
statement;
...
}
Example
float $i;
Expressions
equals:
equals:
equals:
equals:
equals:
0
1
2
3
4
break
The break instruction exits a loop from any point within its body, bypassing
the normal termination at the loops beginning or end. Expression execution
resumes at the next statement after the loop. You can use a break instruction
with a while, do, or for loop.
79
Expression Syntax
Programming features
Example
float $f = 0;
while( $f < 10 )
{
print("$f equals: "+$f+"\n");
if ( $f > 5 )
break;
$f = $f + 1;
}
equals:
equals:
equals:
equals:
equals:
equals:
equals:
0
1
2
3
4
5
6
The loop would execute ten times and display the numbers 0 through 9.
The break statement terminates the loop after $f is greater than 5. So the
expression displays only numbers 0 through 6.
continue
The continue instruction works inside loops. It forces the next iteration of the
loop to occur, skipping any statements between itself and the loops test
condition. The condition compares variable, attribute, or constant values.
80
Expression Syntax
Programming features
Example
float $f = 0;
for( $f = 0; $f < 10; $f = $f + 1)
{
print("$f equals: "+$f+"\n");
if( $f > 5 )
continue;
print(" got here.\n");
}
Expressions
$f equals:
got
$f equals:
got
$f equals:
got
$f equals:
got
$f equals:
got
$f equals:
got
$f equals:
$f equals:
$f equals:
$f equals:
The loop would display got here after each line of $f equals: n. Maya ignores
the continue instruction until $f increases to a value greater than 5.
When $f becomes 6 or greater, the continue instruction executes and skips
the remaining statement in the loop, so got here isnt printed.
for-in
The for-in loop is a specialized for loop that simplifies manipulation of all
elements of an array. A for-in loop with an array element variable lets you
omit the initialization, condition, and change of condition components of a for
loop.
Using Maya: Hypergraph, Sets & Expressions
81
Expression Syntax
Programming features
The for-in loop has this format:
for (array-element in array)
{
statement;
statement;
...
}
Example
string $carType[3] = {"Porsche", "Ferrari", "Fiesta"};
string $car;
for ($car in $carType)
{
print("I want a new ");
print($car + ".\n");
}
The loop executes three times, once for each array element in $carType.
The first loop execution copies array element $carType[0] into $car, then
prints, I want a new Porsche. Array element $carType[0] is Porsche.
The second loop execution copies $carType[1] into $car, then prints the
second line shown. The third execution copies $carType[2] into $car, then
prints the third line shown.
When the for-in statement finishes reading all array elements, the loop
terminates.
82
Expression Syntax
Programming features
switch
A switch instruction executes one of several groups of statements based on a
control value. The control value can be a variable value or an attribute other
than an array (per particle) attribute. The format follows:
83
Expressions
switch (control-value)
{
case value1:
statement;
statement;
...
break;
case value2:
statement;
statement;
...
break;
case value3:
statement;
statement;
...
break;
...
default:
statement;
statement;
...
break;
}
Expression Syntax
Programming features
When the expression executes a few times, it might display this random
selection of entries in the Script Editor:
Case 0
Case 1
I say!
I say!
I say!
Case 2
Case 0
Case 1
The last case instruction in a switch doesnt need a break statement because
the switch is finished. Still, its best to add the break statement to avoid
future problems that might result from adding other cases to the switch.
For details on the purpose of rand(3), see rand on page 243.
84
Expression Syntax
Programming features
When the expression executes a few times, it might display this random
selection of entries in the Script Editor:
Fight
Fight
Fight
Food
Fight
Food
Whenever Food appears, Fight also appears after it. Fight can appear
without Food being displayed.
85
Expressions
Note that you can make more than one case statement execute the same
statements:
Expression Syntax
Programming features
Example
You can use the default keyword to make a block of statements execute when
none of the case values match the control value label. Generally, you put this
label after all the case statements, though you can put it anywhere in the
switch statement.
If the switch has no default label and none of the case values match the
control value, the switch does nothing.
vector $mgb = <<1,1,0>>;
switch ($mgb)
{
case <<0,1,1>>:
print("Who?\n");// Runs if $mgb is <<0,1,1>>
break;
case <<1,0,1>>:
print("What?\n");//Runs if $mgb is <<1,0,1>>
break;
default:
print("Why?\n"); // Executes if $mgb is not
break;
// <<0,1,1>> or <<1,0,1>>
}
The expression executes the default case, which displays the following line
in the Script Editor:
Why?
?: operator
The ?: operator lets you write a shorthand if-else statement to set an attribute
or variable in one statement. Because of its cryptic appearance, many
programming style experts suggest not using it.
Heres its format:
attribute = condition? statement1: statement2;
86
Expression Syntax
Programming features
Example
Balloon.scaleY = (time < 2) ? time / 2: time * 2;
Important
If you use an integer value as statement1 and a floating point value as
statement2, the ?: operator truncates the floating point value of statement2 to
an integer.
In the expression Balloon.scaleY = (time < 2) ? 0: time;, for example, 0 is an
integer, and time is a floating point value. When time is 2 seconds or more,
Maya sets Balloons scaleY attribute to the integer value of time.
If you have problems using the ?: operator, use an if-else statement instead.
! operator
You can use the not logical operator (!) with integer, float, and vector data
types.
For vector values, ! is true only when the vector magnitude is 0. A vectors
magnitude is the value resulting from this equation:
2
x +y +z
87
Expressions
Because Maya sets scaleY to the integer value of time (without the decimal
part), scaleY jumps in one-second increments at time 2, 3, 4, and so on.
Expression Syntax
Programming features
Examples
if (!$count)
Ball.scaleY = 2;
Example 1
Suppose you create an object named Balloon and decide to use a while loop
to increase its Y scaling after three seconds of animation play.
while (time > 3)
Balloon.scaleY = time;
Though you might think this expression sets Balloons scaleY attribute to the
increasing value of time after the animation time exceeds 3 seconds, it
actually halts Maya operation as soon as time exceeds 3. At that moment, the
while condition is true, so the while loop statement Balloon.scaleY = time
executes repeatedly and endlessly.
Even though a statement sets an attribute within an expression, Maya
updates the attribute only after the expression finishes executing. Because
the expression never finishes executing, Maya halts.
Unless you change Balloon.scaleY within the while loop to a value less than
or equal to 3, the statement executes infinitely.
88
Expression Syntax
Programming features
To get the desired result without halting Maya, use this expression:
if (time > 3)
Balloon.scaleY = time;
Example 2
Suppose you create objects named Cone and Ball, then use a while statement
to link the Balls translateY attribute to the Cones translateY attribute:
while (Cone.translateY > 0)
Ball.translateY = Cone.translateY;
At first glance, the expression seems to set Balls translateY position to the
value of the Cones translateY position whenever Cones translateY is greater
than 0.
In fact, the expression halts Maya as soon as you translate the Cone to a Y
position greater than 0. At that moment, the while condition is true, so the
while loop statement Ball.translateY = Cone.translateY executes endlessly.
Nothing you do in the user interface can change the Cones translateY
position. It stays at translateY value of 0.
Unless you change Cone.translateY within the while loop to a value less
than or equal to 0, the statement executes infinitely.
if (Cone.translateY > 0)
Ball.translateY = Cone.translateY;
Example
float $x = cosd(90);
if ($x == 0)
print("This equals 0.\n");
else
print("This doesnt equal 0.\n");
89
Expressions
To get the desired result without halting Maya, use this expression:
Expression Syntax
Programming features
The expression displays the following text:
This doesnt equal 0.
String usage
A string is a sequence of alphabetical, numerical, and special characters. You
can display strings in the Script Editor, for example, to check the contents of
attributes or variables.
You can also create strings in the Expression Editor to execute MEL
commands in an expression. See Chapter 7 for details.
Guidelines for using strings follow:
90
Expression Syntax
Programming features
This displays the following text:
Balls scaleY attribute equals: 0.3333333333
The following table lists how Maya converts data types if you use arithmetic
operators with strings in an expression.
Arithmetic operation
string
string
string
Expressions
91
Expression Syntax
Programming features
The following table shows the shorthand operators and the valid data types
for each. The shorthand operators work like their counterparts in C.
Symbol
Data type
+=
-=
/=
*=
%=
integer, float
Example
$counter += 1;
Expanded syntax
++variable;
variable = variable + 1;
--variable;
variable = variable - 1;
variable++;
variable = variable + 1;
variable--;
variable = variable - 1;
92
Expression Syntax
Programming features
Examples
float
float
$crab
$crab
$crab
$eel = 32.3;
$crab = $eel++;
= $eel--;
= --$eel;
= ++$eel;
//
//
//
//
$crab
$crab
$crab
$crab
=
=
=
=
32.3;
33.3;
31.3;
32.3;
$eel
$eel
$eel
$eel
=
=
=
=
33.3;
32.3;
31.3;
32.3;
Important
To avoid unexpected results, do not use more than one shortcut increment
or decrement operator on the same variable in the same statement. The
evaluation order of the operators is unpredictable.
Arrays
You can create arrays of float, vector, integer, or string values. You can clear
an array using a clear function. You can find the size of an array with the
size function. See Array functions in Chapter 9 for details.
Expressions
When you assign a value in an array, Maya reserves memory for all
elements less than that number. This means you can exceed the capacity of
your computer with a single array declaration. For example, do not use a
statement like this:
$newarray[12312323123] = 1;
Note that an array expands its size automatically as you assign values to its
elements. You dont need to declare its size. If your array assignment
exceeds the size of the array, the array expands to that size. If you reference
an element of the array beyond the array size, a 0 is returned.
Suppose you include these statements in an expression:
int $p [];
$p[1500] = 3;
$p[2000] = 5;
93
Expression Syntax
Programming features
The second statement makes the array contain 1501 elements and assigns
element 1500 the value 3. The third statement expands the array to 2001
elements and assigns element 2000 the value 5.
The first statement creates an array of floating point variables named $fa[ ].
The next statement displays the size of the array, which has 0 elements after
its definition.
The for loop executes the statements between the braces 10 times, once for
each increment of $i from 0 to 9. The first statement between the braces ({ })
initializes and sets the value of one element of the array. Array element
$fa[0] is set to floating point value 0, element $fa[1] is set to 1, element $fa[2]
is set to 2, and so on.
The print statement between the braces displays the value of each element of
the array after you initialize it. In other words, the Script Editor displays 0
through 9.
94
Expression Syntax
Common expression errors
The for loop stops executing after $i becomes equal to 10. Then the final
print statement displays the number of elements of the initialized array, 10.
The array increased in size as you assigned values to its elements.
Example
if (Monster.visibility == on)
Lance.scaleY = time / 3;
Logic errors are mistakes in your reasoning that cause unexpected animation
results. The syntax of your expression is valid, but errors in your logic
prevent Maya from doing what you intended. In the worst cases, Maya
might halt operation because your statements lock it into a permanent loop.
Because Maya cant detect logic errors, it cant display error messages. As
such, these errors are harder to find and require more analysis to solve. To
resolve logic errors, its often helpful to display the contents of relevant
attributes and variables. See Displaying attribute and variable contents in
Chapter 7.
95
Expressions
There are two types of errors you can make when writing expressions:
syntax errors and logic errors. Syntax errors include mistakes in spelling,
incomplete attribute names, omitted semicolons, and other oversights that
prevent the expression from compiling and executing. For syntax errors,
Maya explains the error in a message to the Script Editor.
Expression Syntax
Common expression errors
Youll often need to scroll or increase the size of the Script Editor to see an
entire message.
When the Script Editor displays a syntax error, the response area of the
Command Line displays the same error with a red background.
96
Expression Syntax
Common expression errors
Before clicking the Create or Edit button to create an expression, you might
want to select EditClear History in the Script Editor to remove previous
messages in the window. This makes it easier to see when a new error
message appears.
You misspelled an attribute name, the attribute doesnt exist in the scene, or
you forgot to prefix a variable name with $.
Attribute of a particle object can only be used with
dynExpression command: particleShape1.position
You used a particle array attribute in the expression, but a particle shape
node is not the Selected Object in the Expression Editor. A particle shape
node must be selected to use particle array attributes. A particle array
attribute is also called a per particle attribute.
Attribute already controlled by an expression, keyframe, or
other connection: Balloon.tx.
constraint
motion path
another expression
You used an object.attribute name that exists in two or more parent objects.
Two objects in a scene can have the same object name if they have different
parent objects.
For example, a scene might have a child of GroupA named Ball.tx and a
different child of GroupB named Ball.tx. If you write a statement such as
Ball.tx = time;, Maya wont know which Ball.tx to set.
97
Expressions
You tried to set the value of an attribute that has already been set by one of
these techniques:
Expression Syntax
Common expression errors
To eliminate the error in this example, you must enter the full pathname of
the attribute as GroupA|Ball.tx. The pipe symbol (|) specifies that the object
to its left is the parent of the object on the right.
Cannot set 'time' or 'frame'
You can read the value of the predefined time and frame variables, but you
cannot set them.
Attributes must be of float, integer, or boolean types:
Ball.worldMatrix
You tried to set or read the value of an attribute that was a string or matrix
type. For instance, you might have tried to use an attribute named translate
rather than translateX, translateY, or translateZ attribute.
In the error message above, worldMatrix is an attribute that exists for
transforms, but you cant use it. Its for Mayas internal use.
Cannot divide by zero
Note
If you compile an expression for a particle shape node and see the same
error message once for each particle in the object, its likely that some
attribute name, variable, or function is undefined or misspelled.
98
Editing Expressions
The Expression Editor offers convenient techniques for editing the text of
expressions. There are filters that help you search for expressions you
previously created, as well as techniques for entering and modifying the text
of an expression.
Expressions
Finding expressions
After youve created an expression, you might decide later to alter it to
create a different animation result. To edit an expression, you display it in
the Expression Editor. The following sections describe how to find and
display an expression for editing.
99
Editing Expressions
Finding expressions
List of expressions
Note
For a particle shape node, you can create a creation expression, a runtime
expression, or both. Both expressions are listed under a single namethe
name of the particle shape node. You cant name or rename such
expressions.
To find such expressions, look for the particle shape nodes name in the
Expressions list.
Click the appropriate Runtime or Creation checkbox to display the desired
expression.
100
Editing Expressions
Finding expressions
Object name
Objects attributes
For an object other than a particle shape node, click the name of the attribute
controlled by the expression.
If youve forgotten the name of the attribute controlled by the expression,
choose Attribute FilterConnected to Expressions. The Attributes list
displays only the attributes controlled by expressions for the selected object.
Click each attribute in the Attributes list until you see the desired expression
in the expression text field.
You cant write a different expression for each attribute of a particle shape as
you can for other types of objects. Because you can write only one creation
expression and one runtime expression per particle shape, you dont need to
select an attribute from the Expression Editors Attributes list. See
Understanding particle expressions on page 148 for details on particle
expressions.
101
Expressions
Editing Expressions
Finding expressions
Note
The Attributes list shows only unlocked, keyable attributes. You can
choose whether an attribute is keyable or locked with ViewObject
EditorsChannel Control.
To write an expression for any nonkeyable attribute not shown in the list,
enter object.attribute name in the Selected Obj & Attr text box.
From the Object Filter menu, select the type of object or item the expression
affects.
Example
Suppose youve written an expression that controls the rotateZ attribute of a
spotlight transform node named Searchlight. Do this to find the expression:
1
102
Editing Expressions
Finding expressions
5
Expressions list
Expressions
103
Editing Expressions
Finding expressions
For a particle shape node, you dont need to select an attribute from the
Attributes list. You can create only one creation expression and one runtime
expression per particle shape node. The same expression appears for each
attribute.
When you create a new expression, you can click an object from this list to
choose the default object to which the expression applies.
When you select the default object in the Expression Editor, you can skip
omit the object name and period thats part of a full attribute name (see
Omitting an object name in expressions on page 115.)
104
Editing Expressions
Editing an expression in the text field
Important
At the point in the text where you want to copy the text, click with the
middle mouse button.
This technique takes a little practice. If you find this frustrating, you might
prefer using a text editor native to your operating system, for example, vi or
jot. See Editing an expression with a text editor on page 106.
105
Expressions
Editing Expressions
Editing an expression with a text editor
Important
To erase an expression and make sure its previous contents no longer
control an attribute, click the Edit button after clicking the Clear button.
106
Editing Expressions
Editing an expression with a text editor
There is no file on disk you can edit independently of the Expression Editor.
When you use the text editor through the Expression Editor, youre working
with a temporary file thats linked to the expression stored in the scene. You
can, however, read an independent text file containing expression text into
the temporary file.
If you save an expression without specifying a filename, Maya reads the
saved expression and stores it with the scene. Youll see it dimmed in the
expression text field while youre working with the text editor.
When you close the text editor, the expression text field entry no longer is
dim. The text expression field becomes active after you close the text editor.
If you quit the text editor without saving the expression, Maya does nothing.
Because the expression hasnt changed, Mayas copy of the expression
doesnt need to change either.
Tip
You can use a text editor to save an expression to a filename in the
directory of your choice. This gives you a way to archive an expression you
want to use in a different scene.
By default, you can start one of these editors from the Editor menu in the
Expressions Editor:
jot
vi
vim
xemacs
To run a different editor, see Using an editor not listed in the Editor menu
on page 109.
From the Editor pull-down menu in the Expression Editor, select an editor.
107
Editing Expressions
Editing an expression with a text editor
The editor appears. An example display of vi follows:
The editors title bar shows a filename thats temporarily created while you
work on the expression. When you write or save the file, its contents are
copied to the Maya scene containing the expression.
The expression text field is inactive while the text editor is open. You can
optionally close the Expression Editor window.
If you single-click the name of an object, attribute, or expression, the text
editor doesnt appear. You can single-click to browse the contents in the
expression text field without opening a text editor.
If you double-click an attribute thats already been assigned a value in an
expression, the expression that controls that attribute appears in the text
editor. For nonparticle expressions, you can assign to any attribute in the
scene, not just to the double-clicked attribute. In fact, you dont even need to
work with the double-clicked attribute at all.
If you double-click an attribute that has not yet been assigned a value, the
text editor appears with no contents. If you double-click that attribute again,
a new instance of the editor appears. After you assign a value to an attribute
in an expression, you can start the editor only once for the attribute.
108
Editing Expressions
Editing an expression with a text editor
Note
If youve created a UNIX command alias for jot, vi, vim, or xemacs, the
Expression Editor tries to launch this command. If the arguments provided
in the command alias are unusable by the Expression Editor, the editor
might operate unexpectedly or fail to launch.
Avoid using an alias to customize your editors operation settings. Do the
steps in Changing an editors operation settings on page 110.
Restart Maya.
109
Expressions
If the editor normally appears in the shell where you launched it, you must
make the WINEDITOR setting display the editor in a shell.
Editing Expressions
Editing an expression with a text editor
Restart Maya.
110
Editing Expressions
Creating a new expression
Important
If youve specified a text editor through OptionsUI Preferences or with
the Expression Editors Editor menu, starting the Expression Editor from
the Channel Box or Attribute Editor displays the text editor instead of the
Expression Editor.
Make sure you click the Create or Edit button to compile the existing
expression.
111
Expressions
Note the text editor appears when you click the New Expression button.
Editing Expressions
Deleting an expression
When you create the expression, the Expression Editor associates the object
name with the expression. This means you can narrow your search for the
expression using the objects name in addition to the expression name.
You do not need to select an attribute in the Attributes list. You can associate
the expression with an object only.
For a particle shape node, you dont need to select an attribute, as you can
create only one creation expression and one runtime expression per particle
shape. For nonparticle shape objects, you can create one expression per
attribute.
Deleting an expression
If you want to stop an expression from controlling attributes, you can delete
the expression.
To delete an expression:
1
112
Editing Expressions
Using attribute names in expressions
Example
In place of this:
Ball.translateY = time;
Each attribute has at least one acceptable abbreviation. Here are some
commonly used attribute name abbreviations for several types of object
transform nodes:
Abbreviation
translateX
tx
translateY
ty
translateZ
tz
rotateX
rx
rotateY
ry
rotateZ
rz
scaleX
sx
scaleY
sy
scaleZ
sz
visibility
Expressions
Long name
113
Editing Expressions
Using attribute names in expressions
Common English equivalents for the long attribute names appear in the
Channel Box by default. These names are different than the names you must
use in the expression text field.
If you use the long attribute name, use the name that appears in the
Attributes list of the Expression Editor. Do not use the common English
language equivalents displayed in the Channel Box.
From the Channels menu at the top of the Channel Box, select
Channel NamesShort.
The abbreviated attribute names replace the common English attribute
names in the Channel Box.
114
Editing Expressions
Using attribute names in expressions
Note
After you click Create or Edit to compile an expression, Maya converts all
attribute abbreviations in the expression to the full attribute name.
Example
Suppose youve selected Ball as the Default Object.
In place of this:
Ball.translateY = time;
translateY = time;
115
Editing Expressions
Using attribute names in expressions
Example
Suppose youve selected Ball as the Default Object.
In place of this:
Ball.translateY = time;
Maya interprets ty as being the translateY attribute of Ball, the object listed
in the Default Object text box of the Expression Editor.
Attributes of other objects must be spelled out with the full object and
attribute name.
116
Rob Tesdahl
117
Expressions
118
Example
Suppose youve given a NURBS sphere named Planet a circular, orbiting
motion in the XY plane with this expression:
Planet.tx = sin(time);
Planet.ty = cos(time);
Expressions
Note
The small balls in the preceding figure show the circular path of Planet.
Theyre in the figure only to help you visualize the motion. They arent
part of the animation or expression.
Select Planet.
119
In the Add Attribute window, enter distance in the Attribute Name text box.
120
Click Add to add the attribute, then close the Add Attribute window.
Multiplying the sin(time) and the cos(time) by the distance attribute makes
Planet circle the origin at a distance specified by the value of the distance
attribute. See Chapter 9 for details on the sin and cos functions.
You can make the expression control the distance attribute over time.
9
121
Expressions
Because you gave the distance attribute a default value of 4 when you added
it to Planet, playing the animation makes Planet circle the origin at a distance
of 4 grid units from the origin.
Tip
If an expression controls an attribute and you want to control it with
keyframes instead, delete all statements that assign values to the attribute,
then click the Edit button. Use the Channel Box to reset the attributes
value to an initial value, then set keyframes as desired.
If keyframes control an attribute and you want to control it with an
expression instead, click the attributes text box in the Channel Box, then
choose ChannelsDelete Selected. Assign values to the attribute name in
an expression as desired.
122
Reproducing randomness
If you execute the rand, sphrand, and gauss functions repeatedly in an
expression, Maya returns a sequence of random numbers. (See Random
number functions on page 239 for details on these functions.) Each time you
rewind and play your animation, the sequence of random numbers is
different. Often, youll want to generate a sequence of random numbers that
repeats each time your animation plays.
For instance, suppose you use the rand function to assign a random radius
to each particle in a stream of emitted particles rendered as Spheres. By
default, Maya gives the particles a different sequence of random radius
values each time your animation plays.
Important
When you set a seed value in an expression or MEL script, the seed value
affects the rand, sphrand, and gauss functions in other expressions and
MEL scripts. Such functions are affected by this seed value in all scenes
you open subsequently in the current work session.
This seed value is unrelated to the Seed option available through
SettingsDynamics Controller in the Dynamics menus. The seed function
therefore doesnt affect randomness created with dynamics.
123
Expressions
To create the same radius values each time the animation plays, you can use
the seed function in an expression before the rand, sphrand, or gauss
functions execute. Theres no need to execute the seed function more than
once per animation unless you need to generate several different repeating
sequences of random numbers as your animation plays.
Example
Suppose you use the rand function to position several marbles at random
translateX positions in your scene at frame 1:
if (frame == 1)
{
marble1.tx
marble2.tx
marble3.tx
marble4.tx
}
=
=
=
=
rand(-10,10);
rand(-10,10);
rand(-10,10);
rand(-10,10);
The rand(-10,10) returns a random number between -10 and 10 each time it
executes. When you rewind the animation to frame 1, Maya might assign
these values to the translateX attributes of the marbles:
124
Attribute
Value
marble1.tx
2.922
marble2.tx
5.963
marble3.tx
-4.819
marble4.tx
7.186
Value
marble1.tx
-3.972
marble2.tx
9.108
marble3.tx
-7.244
marble4.tx
-3.065
You can use the seed function to keep the sequence of random values
returned by the rand function consistent when you rewind the animation.
if (frame == 1)
{
seed(10);
marble1.tx
marble2.tx
marble3.tx
marble4.tx
}
=
=
=
=
rand(-10,10);
rand(-10,10);
rand(-10,10);
rand(-10,10);
By setting the seed value to an arbitrary number, for instance, 10, the
subsequent executions of the rand function return a repeating sequence of
random numbers.
125
Expressions
You might prefer the marbles translateX values to stay the same when you
rewind, for instance, so you can composite the marbles correctly among a
foggy backdrop.
Value
marble1.tx
8.020
marble2.tx
-2.973
marble3.tx
-7.709
marble4.tx
0.741
Each time you rewind the animation thereafter, Maya assigns these same
values to the translateX attributes of the marbles. The marbles dont move.
Each time a statement sets the seed value to 10, the subsequent executions of
the rand function return numbers from the sequence starting at the
beginning number. In other words, resetting the seed value to 10 restarts the
random number generation process to the first value in the sequence.
Suppose you alter the expression to this:
if (frame == 1)
{
seed(10);
}
marble1.tx
marble2.tx
marble3.tx
marble4.tx
=
=
=
=
rand(-10,10);
rand(-10,10);
rand(-10,10);
rand(-10,10);
When you rewind the animation to frame 1, the expression sets the seed to
10. Maya assigns values to the marbles translateX attributes as in the
previous expression.
126
Example
Suppose youve selected degrees from the Angular menu in the Units
folder. You then write this expression for an object named Ball:
Ball.rotateZ = 10;
Maya reads the 10 as being 10 degrees, then converts the value to the
appropriate number of radians to make the assignment to Balls rotateZ
attribute. The conversion happens automatically. From your standpoint,
Maya is simply rotating Ball 10 degrees.
In nonparticle expressions, these automatic conversions affect Maya
performance. Because the expression executes slower, Maya slows when you
play, rewind, or otherwise change the animation time. Saving, opening, and
other file operations on the scene containing the expression are also slower.
To boost Maya performance, you can turn off conversion to internal units. If
you do so, you must convert units in expression statements.
127
Angular Only
Example
Suppose, in the Units folder, youve set Linear units to millimeters and
Angular units to degrees. You then write the following expression:
Ball.translateX = 5;
Ball.rotateZ = 10;
128
Examples
Suppose, in the Units folder, youve set Linear units to millimeters and
Angular units to degrees.
In the Expression Editor you set the Convert Units option to None and enter
this expression:
Ball.translateX = 5;
Ball.rotateZ = 10;
When you divide floating point attributes or variables, enter the floating
point value 5.0 for an even number such as 5. This ensures that the division
works as expected. For more details, see the note in Using mixed data
types with arithmetic operators on page 145.
There are 57.3 degrees per radian. In other words, a degree is a radian
divided by 57.3. So 10 degrees equals 10 radians divided by 57.3. You
therefore use the value 10.0 / 57.3.
If you need a more precise conversion to radians, divide a degree by
57.29578 instead of 57.3. You can instead use the deg_to_rad function as
follows:
Ball.rotateZ = deg_to_rad(10.0);
129
Expressions
Important
Some other node in Maya uses the value of an attribute the expression writes
to. For example, a deformer or shader uses its value.
If you use the Move tool in the workspace to drag the sphere in an X-axis
direction, Maya executes the expression for each incremental change to the
translateX attribute as you drag.
Dragging the sphere in the X direction changes the value of the translateX
attribute in the expression. As you drag the sphere and Maya updates the
workspace display, the value of the translateY attribute changes in the
expression. This makes the expression execute.
130
Example
global float $BallHeight = 5;
print($BallHeight+"\n");
nurbsSphere1.tx = rand(1);
print(nurbsSphere1.tx+"\n");
The first statement declares and assigns a value to the variable $BallHeight,
which is not an attribute. The next statement prints the $BallHeight but
assigns no value to an attribute.
The next statement assigns an attribute a value, but the value is generated by
the random number function rand. This function doesnt read an attribute
value. For details on the rand function, see rand on page 243.
The last statement reads and prints the value of an attribute, but doesnt
assign a value to an attribute.
None of these actions causes the expression to execute when Always
Evaluate is off.
Convert to comments all statements that use the attribute name in the
expression.
131
Expressions
Always Evaluate affects only the expression youre creating or editing. You
can turn it on for one expression and off for another.
Disconnecting an attribute
If you disconnect an attribute from an expression, the expression no longer
reads or set its value. You might want to disconnect an attribute, for
example, so you can keyframe the attribute rather than control it with an
expression.
These actions disconnect an attribute from an expression:
Delete from the scene an object with an attribute that exists in the
expression.
Tip
The MEL choice command lets you control an attribute alternately with two
or more techniques in different frames. For example, you can keyframe an
attribute for frames 1-48, control it with an expression for frames 48-96, and
control it with a motion path for subsequent frames.
Example
Suppose your scene has two objects, Ball and Cone, and youve written this
expression:
Ball.translateX = Cone.translateX;
Ball.translateY = Cone.translateY;
Ball.translateZ = Cone.translateZ;
132
The .I[0], .I[1], and .I[2] characters indicate youve disconnected Cones
translate attributes from the expression. These symbols represent
placeholders for the former use of the attributes in the expression.
The .I means the placeholder represents an input to the expression. An input
to an expression is an attribute with a value the expression reads for
assignment to another attribute or variable. The number in brackets indicates
the order in the expression the attribute was read.
For example, .I[0] indicates the input is the first attribute read in the
expression, .I[1] indicates the input is the second attribute read, and .I[2]
indicates the input is the third attribute read.
Note that if you disconnect an attribute from an expression but the attribute
still exists in the scene, the attribute keeps its value from the last time the
expression executed and set its value.
Example
Suppose youve written these statements among others:
Ball.translateX = Cone.translateX;
Ball.translateY = Cone.translateY;
Ball.translateZ = Cone.translateZ;
133
Expressions
Note
If an expression assigns values to the attributes of only one object, deleting
the object deletes the expression also. If your expression assigns values to
attributes of several object attributes, deleting all those objects deletes the
expression.
To avoid deleting the expression in the preceding example, you would
need have some statement that sets an attribute of an object other than the
deleted Ball. For example, you might include this statement:
Cone.visibility = 1;
134
Example 1
Suppose you have these statements among others in an expression named
HorseController:
WhiteHorse.translateX = Car.translateX;
BlackHorse.translateX = Car.translateX;
BrownHorse.translateX = Car.translateX;
.I[0] is the symbolic placeholder for what was the Car.translateX attribute.
You can connect a different attribute to this placeholder to assign its contents
to the translateX attributes of WhiteHorse, BlackHorse, and BrownHorse.
Suppose you want to control these attributes with the translateX attribute of
an object named Cow. You can enter the following MEL command at the
Command Line:
connectAttr Cow.tx HorseController.input[0]
135
Expressions
WhiteHorse.translateX = .I[0];
BlackHorse.translateX = .I[0];
BrownHorse.translateX = .I[0];
Example 2
You can also reconnect an expressions output with the connectAttr
command. Suppose you have these statements among others in an
expression named HorseController:
WhiteHorse.translateX = Car.translateX;
BlackHorse.translateX = Car.translateX;
BrownHorse.translateX = Car.translateX;
Deleting the BrownHorse object and reloading the expression displays this:
WhiteHorse.translateX = Car.translateX;
BlackHorse.translateX = Car.translateX;
.O[2] = Car.translateX;
Renaming an object
If you rename an object whose attributes were used in an expression, the
Expression Editor continues to read or set the attributes. Maya doesnt
disconnect the attribute from the expression. The Expression Editor converts
to the new name of the object the next time you click the Reload button in
the Expression Editor.
136
Note
When you reload an expression, the Expression Editor converts any short
attribute names to their long attribute name equivalents. For example, if
you originally type the attribute name Ball.ty, reloading the expression
renames it as Ball.translateY.
Example
select -cl;
137
Expressions
When you execute a command from the Command Line, status information
appears in the Script Editor and the Command Lines response area. This
information is not displayed when a command executes in an expression.
Example
string $a[];
$a = ls -lights;
print($a);
The first statement defines an array named $a. The second statement
executes the MEL command within quotes, then assigns the commands
output to array $a. The third statement displays the contents of $a to the
Script Editor as follows:
ambientLightShape1
directionalLightShape1
Example
string $mycommand = "sphere";
eval($mycommand+" -r 5");
The first statement assigns the string sphere to the variable $mycommand.
The second statement appends -r 5 to sphere and executes the complete
command sphere -r 5. This creates a sphere with a radius of 5 grid units.
See eval on page 259 for more details.
138
Give the script the same filename as the procedure it contains, but with the
extension .mel.
For example, if your procedure name is randspot( ), name your script file
randspot.mel.
In an expression statement, use a statement that calls the procedure. You can
use the statement within left-hand single quote marks with an eval function,
or alone as in this example:
randspot();
Example
Suppose, in your Maya scripts directory, youve created a MEL script file
named randspot.mel with the following contents:
Expressions
When you rewind or play a frame in the animation, the expression executes.
The first expression statement executes the randspot procedure in the
randspot.mel script file. In the randspot procedure, the rand(2) part of the ifelse statement generates a random floating point value between 0 and 2,
then compares its value to 1. For details on the rand function, see rand on
page 243.
Using Maya: Hypergraph, Sets & Expressions
139
140
The | symbol between GroupA and Ball.tx indicates that the object to the left
of the symbol is the parent of the object to its right. Use no spaces before or
after the | symbol.
Important
Example
Ball.tx = $distance;
$distance = time;
Assume for this example youve set the starting frame of the animation to
frame 0.
The first statement sets Ball.tx to the variable $distance. The second
statement sets $distance to the value of time.
141
Expressions
Always examine the Script Editor for error messages after you edit an
expression and click the Create button. If you alter a previously successful
expression and a syntax error occurs, Maya executes the previous
successful expression when you play the animation. This might lead you to
believe your editing changes took effect.
After you play and rewind the expression, the first statement executes and
assigns the time to $distance. The next statement assigns Ball.tx the value of
$distance, which the first statement set to the value of time. Because
$distance is set to 0 as the first statement after rewinding, Ball returns to the
desired translateX position.
Increment operations
If you increment an attribute or variable during animation, you might be
confused by its behavior.
Example
Ball.ty = 0;
Ball.ty = Ball.ty + 1;
Balls translateY position stays at 1 unit along the Y-axis. Balls translateY
position doesnt increase by 1 each frame as the animation plays.
Example
Ball.ty = Ball.ty + 1;
142
This returns Ball to a Y position of 0 when you rewind to frame 1. When you
drag the current time indicator, though, Ball doesnt return to its Y position
of 0.
The if statement resets the value of translateY to 0 only when frame 1 plays.
Frame 1 is the default frame that plays when you rewind an animation. You
would need to use a different frame number in the if statement if youve set
your animation to start at a different frame.
The following topics describe the conversions that occur in such instances.
Understanding these details might help you troubleshoot unexpected
attribute and variable values.
Unless you have programming experience, dont intentionally convert data
types. You might be confused by unexpected attribute and variable values.
x +y +z
143
Expressions
Example
Ball.scaleY = <<1,2,0>>;
Maya assigns the floating point scaleY attribute the converted vector:
2
1 +2 +0 =
5 = 2.236
Example
Ball.scaleY = 1;
Example
int $pi = 3.14;
1 +2 +0 =
5 = 2.236 2
It deletes the decimal component .2360607. The $temp variable receives the
truncated value 2.
144
Example
vector $speed = 1.34;
float
vector
vector
145
Expressions
Example
Important
When Maya does arithmetic operations on literal constants and variables
without a declared data type, it guesses the data type based on the values
present.
In the statement Ball.scaleY = 1/3;, for example, Maya treats 1 and 3 as
integers because they have no decimal points. The expression divides
integer 1 by integer 3. The integer result is 0 with a remainder of 1. Maya
discards the remainder.
Because Ball.scaleY is a floating point attribute, Maya converts the integer 0
result to floating point 0 (which is the same value), then assigns it to
Ball.scaleY.
To get the intended result of 1/3, you must type Ball.scaleY = 1.0/3.0;
Maya treats 1.0 and 3.0 as floating point numbers because they have
decimal points. The number 1.0 divided by 3.0 results in 0.33333333333.
146
Particle Expressions
Particle expressions are more complex than other types of expressions. For
example, you can write an expression to control all particles in an object the
same way, or you can control each particle differently.
Execution of expressions differs for particles than for other types of objects.
To become proficient with particle expressions takes more study than for
other expressions, but the resulting effects are worth the effort. This chapter
guides you through the intricacies of working with particle expressions.
Claude Macri
147
Expressions
Particle Expressions
Understanding particle expressions
These buttons let you write two types of expressions: creation and runtime.
You can use both types for any attribute of a particle shape node.
Though the details of execution are subtle, a creation expression generally
executes when you rewind an animation or when a particle is emitted. A
runtime expression typically executes for each frame other than the rewind
frame or the frame in which a particle is emitted. By default, either type of
expression executes once for each particle in the object.
Creation and runtime expressions dont execute at the same time. The age of
each particle in the object determines whether a runtime expression or
creation expression executes. Execution details are in Understanding
creation expression execution on page 149 and Understanding runtime
expression execution on page 152.
The Default Object, Always Evaluate, and Convert Units options become
dim when you select a particle shape node, and you cant use them.
Default Object is dim because a particle shape nodes attributes can be
controlled by only one creation expression and one runtime expression. The
particle shape node is always the default object when its the selected object.
Always Evaluate is dim for particle shape node expressions because it has
no effect on particle shape node expressions. See How often an expression
executes in Chapter 7 for details on the checkbox.
148
Particle Expressions
Understanding creation expression execution
Convert Units is not selectable because you cant alter how Maya handles
unit conversions for particle shape node expressions. See Speeding
expression execution on page 127 for details on how Maya converts units
for other types of expressions.
Important
You cant write a different expression for each particle shape attribute as
you can for other types of objects. Because you can write only one creation
expression per particle shape, you dont need to select an attribute from the
Expression Editors Attributes list.
149
Expressions
You might also notice that all expressions in your scene are compiled and
executed each time you open the scene. This occurs for architectural reasons
and is unimportant to your work with expressions.
Particle Expressions
Writing creation expressions
Particles created with the Particle Tool have an age of 0 on and before the
Start Frame. With the default animation frame range and Start Frame,
rewinding an animation to frame 1 returns such particles to age 0.
If you set the Time Sliders start frame higher than the dynamics Start
Frame, be aware that rewinding the animation might cause the age of
particles to be greater than 0. If this occurs, the creation rule for the particles
wont execute.
Tip
You can set options in the Attribute Editor to display the age of an objects
particles in the workspace. Set the particle shapes Render Type to
Numeric, click Add Attributes For Current Render Type, and enter age in
the Attribute Name box. The age appears next to each particle.
You can also examine the age of an objects particles by entering
print(age+\n) in a particle expression. See print on page 261.
150
Particle Expressions
Writing creation expressions
A creation expression is also useful for initializing an attributes value for the
first frame before a runtime expression takes control of the attribute value in
subsequent frames. See Writing runtime expressions on page 153 for an
example of the interaction between a runtime and creation expression.
Example
Suppose youve used the Particle Tool to place a collection of particles in the
workspace. You then create the following creation expression to control their
velocity:
particleShape1.velocity = <<0,1,0>>;
Important
To use an expression to control particle attributes, make sure the selected
object in the Expression Editor is a particle shape node, not the transform
node of the particle object.
If a particle objects transform node is selected rather than the particle
shape node, move the mouse pointer to the workspace and press your
keyboards down arrow. This selects the particle shape node.
151
Expressions
All the particles move in a Y-axis direction at one grid unit per second as the
animation plays.
Particle Expressions
Understanding runtime expression execution
Important
There are no creation expressions for nodes other than particle shape
nodes. Such objects have only one type of expression. (Its similar to a
runtime expression.)
For a particle shape node, you can write only one runtime expression for
all its attributes. You dont need to select an attribute from the Attributes
list. You can create only one runtime expression per particle shape.
152
Particle Expressions
Writing runtime expressions
Example
Suppose youve created a grid of particles, then create this runtime
expression for its velocity attribute:
particleShape1.velocity = <<0,1,0>>;
The expression moves the grid of particles up at 1 grid unit per second as the
animation plays.
Expressions
153
Particle Expressions
Writing runtime expressions
Note
To make the illustrations of particles easier to see in this and other
chapters, we show them as small, shaded spheres rather than points.
Click the Current Render Type button next to Add Attributes For.
A Radius slider appears below the button.
With the default frame rate of 24 frames/second, the particles move 1/24 of
a grid unit each frame. With the default oversampling level of 1, the runtime
expression executes once per frame. Maya calculates the runtime expression
once for each particle of an object.
Because the expression sets the velocity to <<0,1,0>> each frame, the
expression executes redundantly. This expression would therefore be more
appropriate for a creation expression. However, either type of expression has
the same effect in this example.
Example
Suppose youve created a grid of particles, and your animations starting
frame number is 0. You create this runtime expression for its velocity
attribute:
particleShape1.velocity = <<0,time,0>>;
154
Particle Expressions
Writing runtime expressions
You need to use the statement in a runtime expression rather than a creation
expression, because youre increasing a value in the assignment each frame.
Using the statement in a creation expression would instead set the velocity
to a constant value <<0,0,0>>, because time equals 0 when the creation
expression executes for the particle grid.
Example
The previous examples gave all particles the same value for the velocity
attribute. You can instead give each particle a different value for an attribute.
Expressions
Suppose further you create this runtime expression for its acceleration
attribute:
particleShape1.acceleration = sphrand(2);
155
Particle Expressions
Writing runtime expressions
The expression executes once for each of the 121 particles each time the
runtime expression executes.
The sphrand(2) function provides a vector whose randomly selected
components reside within an imaginary sphere centered at the origin and
with a radius of 2. Each particle receives a different vector value. For details
on the sphrand function, see sphrand in Chapter 9.
Because each particle receives a different random vector for its acceleration
each frame, the particles accelerate individually in a constantly changing
direction and rate as the scene plays. This gives the acceleration abrupt
changes in direction.
Important
To give particles a constant acceleration, assign the acceleration attribute a
constant value in a runtime expression rather than in a creation expression.
Maya simulates the physics of acceleration. It initializes acceleration to
<<0,0,0>> before each frame, or if the oversample level is greater than 1,
before each timestep.
If the oversample level is 2, there are 2 timesteps per frame. If the
oversample level is 3, there are 3 timesteps per frame, and so on.
156
Particle Expressions
Writing runtime expressions
Example
Suppose youve set your animations starting frame to 0, and youve used
the Particle Tool to place a single particle at the origin:
When you play the animation, the runtime expression takes control of the
attribute. In the first frame that plays, the particle jumps to <<3, time, 0>>.
At the default frame rate of 24 frames/second, the position is <<3, 0.0417,
0>>, because the value of time is 0.0417.
Expressions
157
Particle Expressions
Writing runtime expressions
Each subsequent frame moves the particle upward at a rate set by the
incrementing value of time.
When you stop and rewind the animation, the particle moves back to the
origin, the particles original position when you created it with the Particle
Tool. When you created the particle, Maya stored its original position in an
internally maintained initial state attribute named position0. For details, see
Understanding initial state attributes on page 162.
Because the attribute has no creation expression controlling its value, Maya
sets the attribute to its initial state position0 value of <<0,0,0>>.
To prevent the particle from jumping back to the origin after rewinding, you
can write a creation expression thats the same as the runtime expression:
particleShape1.position = <<3,time,0>>;
158
Particle Expressions
Working with particle attributes
When you rewind the animation, Maya positions the object at the initial state
setting of its position attribute. This setting is <<3, 0.0417, 0>> because you
selected Set for Current while the position was equal to <<3, 0.0417, 0>>.
When you add a dynamic attribute to an object, the attribute names appear
in the Expression Editors Attributes list.
Note
See List of particle shape attributes on page 196 for attributes you can
use with particle objects.
159
Expressions
You also use expressions to control dynamic and custom attributes you add
to a particle shape node. See Attributes in Chapter 5 for details on the
differences between static, dynamic, and custom attributes. See Assigning
to a custom attribute on page 169 for details on working with custom
attributes.
Particle Expressions
Working with particle attributes
per particle
per object
A per particle attribute lets you set the value of the attribute individually for
each particle of the object. A per object attribute lets you set the attribute
value for all particles of the object collectively with a single value.
For example, a per particle opacityPP attribute lets you set a unique opacity
value for each particle of an object. With a per object opacity attribute, you
must give all particles of the object the same opacity.
A per particle attribute holds the attribute values for each particle in the
object. For example, though there is only one opacityPP attribute in a
particle object, the attribute holds the value for each particles opacity value.
The attribute holds the values in an array. In simple terms, an array is a list.
Though per particle attributes are best for creating complex effects, you cant
keyframe them. You can keyframe per object attributes.
You can add per particle or per object attributes for opacity, color, lifespan,
and other effects.
For a particle shape node attribute, you can tell whether its a per particle or
per object attribute by examining the Attribute Editors particle shape folder.
All per particle attributes appear in the Per Particle (Array) Attributes
section of the folder.
The per object attributes appear elsewhere in the folder. Most appear above
the Per Particle (Array) Attributes section, for example, in the Particle
Attributes and Render Attributes sections.
For many dynamically added attributes, you can also tell whether they are
per particle or per object by their names in the Expression Editor. If a name
ends with PP, its per particle. Otherwise, its usually per object.
Note that position, velocity, and acceleration are per particle attributes,
though their names dont end with PP.
160
Particle Expressions
Working with particle attributes
The most common way to create dynamic per object or per particle attributes
for a particle shape is by clicking one of the following buttons in the Add
Dynamic Attributes section of the Attribute Editor:
For example, if you click the Opacity button, a window appears and lets you
choose whether to add the opacity characteristic as a per object attribute or a
per particle attribute.
If you choose per particle, the Attributes list of the Expression Editor
displays a new attribute for the selected particle shape node: opacityPP. If
you choose per object, an opacity attribute is displayed instead.
For attributes other than lifespan, if you add both a per particle attribute and
a per object attribute for a characteristic, the per particle attribute takes
precedence. For instance, if you add opacity and opacityPP, the opacityPP
attribute controls the opacity of the particles of the specified object.
When you click Lifespan and add both a per particle and per object
attribute, Maya adds an additional attribute named useLifspanPP that lets
you choose whether lifespanPP or lifespan controls the characteristic.
If you click the Goal button in the Add Dynamic Attributes section of the
Attribute Editor, Maya adds a per object attribute and a per particle
attribute. The attributes are named goal and goalPP. Neither attribute has
precedence. Maya multiplies the value of the per object goal attribute by the
per particle goalPP attribute to create the final goal effect for each particle.
161
Expressions
Particle Expressions
Working with particle attributes
Important
You can use per particle attributes only in particle expressions. You can use
per object attributes in particle or nonparticle expressions.
If you use a runtime expression to read or write a per object attribute of a
particle object with many particles, you can speed up expression execution
by reading or writing the attribute in a nonparticle expression.
Nonparticle expressions execute only once per object. Particle expressions
execute once for each particle in the object. Because reading or writing a
per object attribute more than once per frame is redundant, you can save
processing time by working with them in nonparticle expressions.
162
Particle Expressions
Working with particle attributes
When you use the Add Attribute window to add a custom per particle
(array) attribute to a particle shape, you must choose whether you want to
add it with Add Initial State Attribute on or off. If you choose on, Maya
creates a corresponding initial state attribute for the added attribute.
If you choose off, Maya doesnt create a corresponding initial state attribute
for the added attribute. Without this corresponding attribute, you cant save
a particle objects current attribute values for initial state usage. You must
write a creation expression if you decide to initialize the custom attributes
value upon rewinding the animation.
Note
A per particle attribute is called an array attribute in the Add Attribute
window. The two terms have the same meaning. See Assigning to a
custom attribute on page 169 for details.
You can see whether a custom attribute was added with Add Initial State
Attribute on or off by using the MEL listAttributes command. (See the online
MEL documentation for details.)
When you add a custom attribute to a particle shape, do not end the name
with a 0 character. Youll subvert Mayas naming scheme for the initial state
attribute associated with an attribute.
For any attribute, if you dont initialize its value with a creation expression
or save its value for initial state usage, Maya gives the attribute a default
value at the animations first frame. It typically assigns the attribute the
value 0 or <<0,0,0>>, as appropriate for the data type. In other cases, for
instance, opacityPP and opacity, Maya assigns the attribute a default value
of 1.
If you know youre going to write a creation expression for a custom
attribute, you can set Add Initial State Attribute off when you add the
attribute. Otherwise, set Add Initial State Attribute on whenever you add a
custom attribute.
When a creation expression assigns a value to an attribute, the value
overrides the attributes initial state value for all particles whose age is 0.
163
Expressions
Particle Expressions
Working with particle attributes
The following steps show how to assign a different lifespanPP value for each
of the particles to make them disappear as the scene plays.
Select the particle shape node for Bubbles in the Outliner or Hypergraph.
In the Add Dynamic Attributes section of the Attribute Editor, click the
Lifespan button.
A window appears that prompts you to choose whether to add the attribute
per object or per particle.
Select Add Per Particle Attribute, then click the Add Attribute button.
This adds a lifespanPP attribute to the particle shape node for Bubbles. You
can set this attribute to give each particle a different value for how long it
lives.
164
Particle Expressions
Working with particle attributes
Because lifespanPP is a per particle attribute and the objects particle shape
node is selected in the Expression Editor, the expression does an execution
loop of both statements once for each particle in the object.
Because the expression is a creation expression, it executes after the
expression compiles. It also executes when you rewind the animation after
playing it.
For each of the particles, the first statement assigns the lifespanPP attribute a
random floating point number between 0 and 5. The rand function returns a
different random number each time it executes, so each particle has a
different lifespanPP value between 0 and 5. For details on the rand function,
see chapter 9, Functions.
The second statement displays Hello in the Script Editor, once for each
particle.
The creation expression gives each particle a random lifespanPP of less than
5 seconds. The particles disappear from the scene at random times between 0
and 5 seconds of scene play. (Maya gives particles created with the Particle
tool an age of 0 in the first frame of the animation.)
Expressions
When you rewind the animation, the particles reappear in the scene. Playing
the scene again makes them disappear at random times within 5 seconds.
165
Particle Expressions
Working with particle attributes
Its important that you use a creation expression for this effect. If you were
to use a runtime expression, the particles would disappear more quickly as
the animation plays, and Hello would appear 100 times each frame. The
reason for this is subtle:
In each frame, a runtime expression would assign a different random value
between 0 and 5 seconds to the lifespanPP of each particle. The expression
would likely assign one or more of the particles a lifespanPP near 0.
Meanwhile, the age of each particle increases from 0 at the first frame of
play.
Maya checks the age of each particle every frame. If the age is greater than
the lifespanPP value, Maya removes the particle.
Because the expression would reassign new random lifespanPP values to
each remaining particle in each frame, the new assignments would likely
give a few particles a lifespanPP thats less than their current age value.
Maya deletes such particles. This causes the objects particles to disappear
quickly from the scene.
166
Particle Expressions
Working with particle attributes
The following steps show how to give the particles a single lifespan. All
particles disappear at the same time when you play the scene.
In the Add Dynamic Attributes section of the Attribute Editor, click the
Lifespan button.
A window appears that prompts you to choose whether to add the attribute
per object or per particle.
Select Add Per Object Attribute, then click the Add Attribute button.
This adds the lifespan attribute to the particle shape node for Bubbles.
167
Expressions
Particle Expressions
Working with particle attributes
For each of the 100 particles, the first statement assigns the lifespan attribute
the value 1.33. The second statement displays Hello in the Script Editor once
for each particle.
6
168
Particle Expressions
Working with particle attributes
Select the objects particle shape node rather than its transform node.
Use the Hypergraph or Outliner to select the shape node.
Expressions
169
Particle Expressions
Working with particle attributes
4
Vector
Float
Integer
Boolean
Array
If you select Scalar, you can specify Minimum, Maximum, and Default
values for a Float or Integer attribute.
Minimum and Maximum set the lowest and highest values you can enter
for the attribute in the Attribute Editor or Channel Box. Default sets the
default value displayed for the attribute. Because youre going to control the
attributes value with an expression, you might want to skip entering values
for these options.
An expression isnt bound by the Minimum and Maximum values. The
attribute receives whatever value you assign it in the expression. The
expression can read the attributes Default value or any other value you give
it in the Attribute Editor or Channel Box.
When you select Scalar, you cant create a counterpart initial state attribute
by turning on Add Initial State Attribute.
If you select Array, you can also create a counterpart initial state attribute by
turning on Add Initial State Attribute. See Understanding initial state
attributes on page 162 for details.
You cant set Minimum, Maximum, or Default values for an Array
attribute.
170
Click Add if you want to add more attributes. Click OK to add the attribute
and close the Add Attribute window.
Particle Expressions
Working with particle attributes
The new attribute appears under the Dynamic Attributes section of the
Attribute Editor.
Example
Suppose youve created a 100-particle object named sunspot, and you add to
its particle shape node a vector per object attribute named glow. You assign
the glow attribute a vector value in a creation expression as follows:
sunspotShape1.glow = <<3,0,0>>;
print(sunspotShape1.glow + "\n");
Example
When you rewind the animation, the expression loops through 100
executions, once for each particle.
The first statement sets the $randomNumber variable to a random number
between 0 and 1. The next statement assigns a vector to the heat attribute of
a single particle. The left component of the vector assigned to heat is a
different random number each time the statement executes. The middle and
right components are always 0.
One particle might have the value <<0.57, 0, 0>>, another <<0.32, 0, 0>>,
another <<0.98, 0, 0>>, and so on.
The print statement displays the values in the Script Editor.
171
Expressions
Suppose you add a vector per particle attribute named heat to the 100particle sunspot shape node. You can give each particle a different value as
in this creation expression:
Particle Expressions
Working with particle attributes
Note
If you add a custom vector attribute to an object, Maya displays the
attribute in the Attribute Editor, but you cant enter its value there. You
must enter a value for it in an expression or with the Component Editor
available from the Attribute Editor.
Example
Suppose your scene contains an object named ThreePts made of three
particles and an object named TwoPts made of two particles.
The three particles in ThreePts are at these positions:
-5 0 0
-4 0 0
-3 0 0
172
Particle Expressions
Working with particle attributes
Suppose you write this runtime expression with TwoPtsShape2 selected in
the Object Selection list:
ThreePtsShape1.position = TwoPtsShape2.position;
print(ThreePtsShape1.position+"\n");
In the first frame of runtime expression execution, this assigns the position
attribute of TwoPts to the position attribute of ThreePts. In other words, the
expression repositions the three particles to the position of the two particles.
Because you selected TwoPtsShape1 in the Object Selection list, the
expression will execute once for each of its two particles.
When you play the scene, the runtime expression executes. The first particle
of ThreePts now is at the position of the first particle of TwoPts. The second
particle of ThreePts is at the position of the second particle of TwoPts. The
third particle of ThreePts doesnt change position. The expression executes
only twice each frame.
In summary, the particles in ThreePts are at these positions:
5 0 0
6 0 0
-3 0 0
Expressions
173
Particle Expressions
Working with particle attributes
Because TwoPts lacks a third particle, the third particle of ThreePts is
repositioned at the position of the first particle of TwoPts. You cant see this
in the workspace because the particles are in the exact same position.
The three particles in ThreePts are at these positions:
5 0 0
6 0 0
5 0 0
The five particles move to these positions as soon as the runtime expression
executes for the first time:
5
6
5
6
5
0
0
0
0
0
0
0
0
0
0
174
Particle Expressions
Working with particle attributes
For example, suppose you assign a particle objects position to a variable
named $oldposition in a creation expression:
vector $oldposition = particleShape1.position;
The runtime expression for the same particle shape node cant read the
contents of the $oldposition variable. To solve this problem, you can create
an attribute for the object, assign it a value in the creation expression, then
use the attribute value in a runtime expression.
For example, suppose you create an attribute named oldpos, and assign it
the following position in a creation expression:
particleShape1.oldpos = particleShape1.position;
Unless you have a solid grasp of physics, avoid setting a combination of the
position, velocity, and acceleration attributes.
To give a smooth, random motion to particles with a runtime expression, use
a random number function such as sphrand to assign random numbers to
the particle shapes acceleration attribute. A change in acceleration always
gives smooth motion no matter how abruptly its value changes.
To give a jittery random motion to particles with a runtime expression, use a
random number function such as sphrand to assign random numbers to the
particle shapes velocity or position attributes.
See Random number functions on page 239 for details on how to use
random number functions.
If an expression and a dynamic field control an objects position, velocity, or
acceleration, Maya calculates the expressions effect first, then adds the
fields effect.
175
Expressions
To create various types of particle motion, you can assign vector values to
the position, velocity, or acceleration attribute. See Writing runtime
expressions on page 153 for examples of working with these attributes.
Particle Expressions
Working with particle attributes
Example
Suppose a particle drops under the influence of a gravity field with default
gravity options. Gravity accelerates the particle at 9.8 units per second per
second down the Y-axis. In other words, the default acceleration of gravity is
<<0,-9.8,0>>.
Suppose further you write the following runtime expression for the particle:
velocity = velocity + <<1,0,0>>;
As each frame plays, Maya first calculates the particles velocity from the
expression statement. The velocity increases 1 unit per second in an X-axis
direction. Maya then adds the gravitational acceleration to the velocity.
Maya uses the combined result to compute the particles position.
Of course, you wont see this calculation process. The frame displays the
particle in the appropriate position after all computation.
Note that the expression adds the constant <<1,0,0>> to the particles
velocity each frame as the animation plays. This makes the particle move
with increasing velocity in an X direction as the time increases. An
increasing velocity is the same as acceleration.
The ball represents the particles position after
several frames. The white squares represent
the particles position as time increases.
Gravity alone
176
Particle Expressions
Working with particle attributes
The acceleration attribute works differently than the position or velocity
attributes in an important way. Maya initializes its value to <<0,0,0>> before
each frame. If the oversample level is greater than 1, this initialization occurs
before each timestep.
Example
Suppose you write the following runtime expression for a five-particle object
unaffected by gravity:
acceleration = acceleration + <<0,1,0>>;
acceleration = sphrand(3);
As each frame plays, Maya first calculates each particles acceleration from
the expression statement. Each particle receives the result of the sphrand(3)
function.
The sphrand(3) function provides a vector whose randomly selected
components reside within a spherical region centered at the origin with
radius 3. Each particle receives a different vector value.
Finally, Maya adds gravitys acceleration to the expression acceleration
resulting from sphrand(3). The frame displays each particle in the resulting
position.
Because of the random values resulting from the expression, each particle
has an acceleration that differs slightly from gravity in direction and
magnitude. Because the sphrand(3) function executes for each particle each
frame, the acceleration of each particle varies each frame.
177
Expressions
Particle Expressions
Working with particle attributes
Position at rewind
This example shows that you can take advantage of the additive effect of
fields and the acceleration attribute to create custom field effects.
Tip
You can turn off the effect of all fields on a particle shape node attribute by
setting its dynamicsWeight attribute to 0.
Example
Suppose youve used the Particle tool to create a randomly positioned
collection of particles named Bubbles. You can use a creation expression to
give the particles a constant color during animation play.
178
Particle Expressions
Working with particle attributes
Select the particle shape node for Bubbles in the Hypergraph or Outliner.
To write an expression to color particles, you must dynamically add the
attribute that lets you color them.
In the Add Dynamic Attributes section of the Attribute Editor, click the
Color button.
Select Add Per Particle Attribute, then click the Add Attribute button.
This adds an rgbPP attribute to the particle shape node for Bubbles. Because
youre adding this attribute as a per particle attribute, you can give each
particle a different color.
179
Expressions
A window appears that prompts you to choose whether to add the attribute
per object, per particle, or connected to a shader.
Particle Expressions
Working with particle attributes
When you click the Create button in the Expression Editor, Maya checks the
syntax of the expression. Assuming you made no typing errors, the
expression executes once for each of the 100 particles.
The expression colors all particles in the object red. The double angle
brackets << and >> enclose a vector that sets the red, green, and blue
components of the rgbPP attribute to 1, 0, and 0. In the RGB color scheme,
this gives the object a red color.
8
Tip
See the online version of this documentation for colored illustrations.
The following steps show how to give the particles a randomly changing
color as the animation plays.
180
Particle Expressions
Working with particle attributes
Because the creation expression executes when you rewind, the particles are
red.
5
You can slow the change of colors to create a flashing Christmas light effect.
The following steps make the particles change colors every second of
animation.
181
Expressions
If you rendered the animation and played it back at 24 frames per second,
you would have trouble seeing the color of a particle in any instant because
the color changes so quickly.
Particle Expressions
Working with particle attributes
This expression uses the modulus operator (%) to control when the rgbPP
attribute of the particles receives a random color. The modulus operator
returns the remainder after division. For example, 24 divided by 24 returns
0, but 25 divided by 24 returns 1. (Dividing 25 by 24 equals 1 with a
remainder of 1.)
If the value of frame divided by 24 is equal to any number with a remainder
of 0, the assignment to BubblesShape1.rgbPP occurs. In other words, the
assignment occurs when frame equals 24, 48, 72, and so on. At an animation
rate of 24 frames/second, the assignment happens once each second.
Important
Avoid using the modulus operator with floating point values. Because of
number rounding in floating point division, you wont likely get a return
value of exactly 0 with the modulus operator. Instead use an integer value
when possible.
2
1 second
2 seconds
3 seconds
Note that you can change the red rewind color to random colors by
changing the creation expression to this:
BubblesShape1.rgbPP = sphrand(1);
182
Particle Expressions
Working with particle attributes
Select the shape node of the emitted particles in the Expression Editor, then
write the expression to control the attribute.
Example
Suppose youve created an emitter and added a per particle lifespanPP
attribute to it. The following creation expression gives the emitted particles a
lifespan of 2 seconds:
particleShape1.lifespanPP = 2;
Important
Expressions
183
Particle Expressions
Working with particle attributes
Select the particle shape node of the particles in the Outliner or Hypergraph.
Write the runtime or creation expression using the value of any of these
attributes of the emitted particles shape node:
Long name
Short name
event
Description
Data Type
float array
eventCount
evc
integer
eventTest
evt
boolean
The eventCount and eventTest are static attributes. A particle shape node
has them as soon as you create the particle object. Though they dont appear
in the Expression Editor, you can use their values in an expression. You
must first create the event attribute as described previously.
184
Particle Expressions
Working with particle attributes
Example
Suppose youve created a five-particle object named Peas that falls with
gravity and collides with a plane.
You can make the particles turn red when the first particle hits the plane.
Select PeasShape1 in the Outliner or Hypergraph.
In the Particle Events window, click Create Event, then close the window.
This adds an event attribute to PeasShape1.
In the Add Dynamic Attributes section of the Attribute Editor, click Color.
The Particle Color window appears.
185
Expressions
Particle Expressions
Working with particle attributes
7
186
Particle Expressions
Working with particle attributes
Tip
See the online version of this documentation for colored illustrations.
Note that the value of the event attribute reflects the collision count in the
frame after each collision. For example, if a particle collides with the plane in
frame 10, event is updated in frame 11.
Expressions
When the other particles hit the plane for the first time, they also turn red
after they collide.
A particle stays red until it collides with the plane for the second time, when
event equals 2. After a second collision, the particle turns green.
187
Particle Expressions
Working with particle attributes
After a third collision, when event is equal to or greater than 3, a particle
turns blue. Each particle stays blue for all subsequent collisions as the
animation plays.
This statement executes for each particle in the object, so they all receive the
same white color when you rewind the scene.
188
Particle Expressions
Working with particle attributes
Note that Set for Current saves all attribute values, including position,
velocity, acceleration, and so on. In cases where you have several changing
attribute values during playback, Set for Current might save undesired
attribute values in addition to the desired ones. In such cases, use a creation
expression.
You can assign per particle attribute values to specific particles using the
particleId attribute.
Example
Suppose youve used the Particle tool to create a grid of eight particles
named ColorGrid. In the Attribute Editor, youve set the Render Type of the
particles to Spheres. Youve chosen ShadingSmooth Shade All to display
the particles with shading.
189
Expressions
Particle Expressions
Working with particle attributes
You can give the particles different colors based on their particleId.
In the Add Dynamic Attributes section of the Attribute Editor, click Color.
The Particle Color window appears.
In the Attribute Editor, choose Numeric from the Render Type menu.
The particleId of each particle is displayed instead of spheres:
190
Particle Expressions
Working with particle attributes
5
The creation expression executes whenever you rewind the animation. The
particles dont show the color assignments yet. The Numeric particle render
type ignores color assignments to rgbPP.
6
In the Attribute Editor, set Render Type of the particles to Spheres again.
The left, middle, and right columns of particles are red, white, and blue:
Expressions
The expressions first statement assigns a red color to all particles whose
particleId is less than or equal to 2. The value <<1,0,0>> is red in the RGB
color scheme.
The second statement assigns a white color to all particles whose particleId
is greater than 2 and less than 6. The value <<1,1,1>> is white in the RGB
color scheme.
The third statement assigns a blue color to all particles that dont meet the
conditions in the prior two statements. In other words, all particles whose
particleId is greater than or equal to 6 become blue. The value <<0,0,1>> is
blue in the RGB color scheme.
The following steps show another common way to control an attribute based
on the particleId attribute.
191
Particle Expressions
Working with particle attributes
To color half the particles red, and half the particles blue:
1
The first statement uses a modulus operator (%) to calculate the remainder
of dividing a particleId by 2. It then compares the remainder to 0. If the
remainder equals 0, the statement assigns the particle a red color. The value
<<1,0,0>> is red.
The second statement assigns a particle a blue color if the remainder of the
modulus operation doesnt equal 0. The value <<0,0,1>> is blue. For
example, dividing particleId 0 by 2 equals 0 with remainder 0. Because the
remainder is 0, the particle having particleId 0 receives a red color.
Dividing particleId 1 by 2 equals 0 with remainder 1. Because the remainder
is 1, the particle having particleId 1 receives a blue color.
Dividing particleId 2 by 2 equals 1 with remainder 0. With remainder 0, the
particle having particleId 1 receives a blue color. The expression executes for
each particle in the object.
The result is that even-numbered particleIds become red, odd numbered
particles become blue.
3
192
Particle Expressions
Assigning to vectors and vector arrays
The creation expression executes. The particles become red, white, and blue
as described for the previous expression.
4
Note to programmers
You cannot assign values to individual particles with the array index
notation commonly used in programming languages.
For example, suppose youve created an opacityPP attribute for an object
made of three particles. You cant assign values as in this example:
opacityPP[0] = 0.3;
opacityPP[1] = 0.5;
opacityPP[2] = 1;
Expressions
Previous topics in this chapter show general techniques for working with
vector array attributes. Vector array attributes are also called per particle
attributes. Subtle details of assigning to vector and vector array attributes
and variables follow.
Examples
vector $top_velocity = <<2,2,5>>;
This assigns the value of vector variable $top_velocity to the vector variable
$temp.
193
Particle Expressions
Assigning to vectors and vector arrays
Meaning
$variable.x
left component
$variable.y
middle component
$variable.z
right component
Examples
float $temp;
vector $myvector = <<1,2,3>>;
float $temp = $myvector.z;
An error occurs. A statement can read, but not directly assign, a component
of a vector variable.
194
Particle Expressions
Assigning to vectors and vector arrays
Example
Suppose you have 100-particle Cloud of randomly positioned particles.
CloudShape1.position = sphrand(1);
vector $pos = CloudShape1.position;
CloudShape1.rgbPP = <<0,$pos.y,0>>;
This colors the particles from black to green, depending on the position.
Increasingly green
195
Expressions
Particle Expressions
List of particle shape attributes
Example
particleShape1.rgbPP = <<1,0,CloudShape1.position.z>>;
Example
particleShape1.rgbPP.y = 1;
This also causes an error. You cant assign a value to a vector array attribute
component.
Attributes you can read but not write are marked with an asterisk (*).
Empty boxes in the Render Type column indicate the render type is
irrelevant to the attributes usage.
You can read and write per particle attributes only in particle expressions.
See Using Maya: Dynamics for more details on the attributes.
196
Particle Expressions
List of particle shape attributes
Description
Per
particle
Render Type
acceleration
(acc)
Sets acceleration.
yes
vector array
age*
(ag)
Contains number of
seconds each particle has
existed in scene.
yes
float array
attributeName
Numeric
string
betterIllumination
Cloud
boolean
colorAccum
MultiPoint
MultiStreak
Points
Streak
boolean
colorBlue
float
colorGreen
colorRed
Blobby Surface
Cloud
MultiPoint
MultiStreak
Points
Sphere
Sprite
Streak
conserve
(con)
Sets amount of
momentum conservation.
float
count*
(cnt)
Contains number of
particles in object.
integer
depthSort
(ds)
MultiPoint
MultiStreak
Points
Streak
Sprite
Data Type
Expressions
float
float
boolean
197
Particle Expressions
List of particle shape attributes
Description
dynamicsWeight
(dw)
event*
eventCount*
(evc)
integer
eventTest*
(evt)
boolean
goalPP
goalWeight
(gw)
incandescence
incandescencePP
inheritFactor
(inh)
float
isDynamic
(isd)
boolean
lifespan
float
198
Per
particle
Render Type
Data Type
float
yes
float array
yes
float array
float
yes
Cloud
vector
Cloud
vector array
Particle Expressions
List of particle shape attributes
Description
Per
particle
Render Type
Data Type
lifespanPP
yes
levelOfDetail
(lod)
lineWidth
mass
maxCount
(mxc)
multiCount
MultiPoint
Point
float
multiRadius
MultiPoint
MultiStreak
float
normalDir
MultiPoint
MultiStreak
Points
Streak
integer (1-3)
float array
float
MultiStreak
Streak
yes
float
float array
integer
Expressions
199
Particle Expressions
List of particle shape attributes
Description
opacity
Sets amount of
transparency.
opacityPP
Sets amount of
transparency.
particleId*
(id)
Contains id number of
each particle.
pointSize
position
(pos)
Sets position.
radius
Blobby Surface
Cloud
Sphere
float
radius0
Tube
float
radius1
Tube
float
radiusPP
Blobby Surface
Cloud
Sphere
float array
200
Per
particle
Render Type
Data Type
MultiPoint
MultiStreak
Points
Streak
Sphere
Blobby Surface
Cloud
Sprite
float
yes
MultiPoint
MultiStreak
Points
Streak
Sphere
Cloud
Sprite
float array
yes
Numeric
float array
MultiPoint,
Numeric
Points
float
yes
yes
vector array
Particle Expressions
List of particle shape attributes
Description
primaryVisibility
(rea)
Per
particle
Data Type
Cloud
Blobby Surface
Tube
boolean
visibleInReflections
(rrl)
Cloud
Blobby Surface
Tube
boolean
visibleInRefractions
(rrr)
Cloud
Blobby Surface
Tube
boolean
castsShadows
(rsh)
Cloud
Blobby Surface
Tube
boolean
rgbPP
Sets color.
MultiPoint
MultiStreak
Points
Sphere
Sprite
Streak
vector array
selectedOnly
Toggles display of id
numbers for selected
particles.
Numeric
boolean
spriteNum
Sprite
integer
spriteNumPP
Sprite
integer array
spriteScaleX
Sprite
float
spriteScaleXPP
Sprite
float array
spriteScaleY
Sprite
float
spriteScaleYPP
Sprite
float array
spriteTwist
Sprite
float
yes
yes
yes
yes
Expressions
Render Type
201
Particle Expressions
List of particle shape attributes
Description
Per
particle
Render Type
Data Type
spriteTwistPP
yes
Sprite
float array
surfaceShading
Cloud
float
tailFade
MultiStreak
Streak
float
tailSize
MultiStreak
Streak
Tube
float
threshold
Blobby Surface
Cloud
float
useLighting
MultiPoint
MultiStreak
Points
Sprite
Streak
boolean
velocity
(vel)
Sets velocity.
202
yes
vector array
Functions
In expressions, you can use built-in operations called functions to create
motion, particle positioning, and other effects. This chapter explains the
most commonly used functions and a few useful MEL commands.
A hermite function shaped
the lightnings soft body
geometry, dnoise animated
its turbulence, and sphrand
enhanced its randomness.
Expressions
Matt Baer
For easy reference, this chapter groups functions by their purpose. For
example, all math functions are grouped in the same section.
To find out about:
See page:
Understanding functions
205
Function syntax
206
Limit functions
abs
ceil
floor
clamp
min
max
sign
trunc
209
210
210
210
211
212
212
212
213
Using Maya: Hypergraph, Sets & Expressions
203
Functions
204
See page:
Exponential functions
exp
log
log10
pow
sqrt
214
214
214
214
215
215
Trigonometric functions
cos
cosd
sin
sind
tan
tand
acos
acosd
asin
asind
atan
atand
atan2
atan2d
hypot
216
216
218
219
224
224
225
225
226
226
226
227
227
227
228
228
Vector functions
angle
cross
dot
mag
rot
unit
229
230
230
231
231
232
233
Conversion functions
hsv_to_rgb
rgb_to_hsv
deg_to_rad
rad_to_deg
234
235
235
234
234
Functions
Understanding functions
See page:
Array functions
clear
size
sort
236
236
237
237
239
239
241
242
243
244
246
Curve functions
linstep
smoothstep
hermite
249
249
252
254
General commands
eval
print
system
259
259
261
263
264
Expressions
Understanding functions
A function generates a value where it occurs in an expression statement. It
takes action based on parameters called arguments that you enclose in
parentheses next to the function name.
Example
Suppose you have an object named Star whose translateX attribute is set
with this expression statement:
Star.translateX = rand(10);
In this statement, the rand function has the argument 10. With this
argument, the function generates a randomly selected floating point number
between 0 and 10 each time the statement executes. For example, translateX
Using Maya: Hypergraph, Sets & Expressions
205
Functions
Function syntax
might be assigned 6.5409 the first time the statement executes, 3.2974 the
second time, 8.7389 the third time, and so on. This causes Star to jump to
random points from 0 to 10 units away from the X-axis as the scene plays.
Though functions can be more or less complicated than this example, they
all have at least one argument and generate one value. Note that a function
is part of an expression statement. They dont stand alone in an expression.
Many functions do mathematical operations. For example, the sin function
generates the sine of a specified angle. Though we often provide explanatory
figures and details, we assume youre familiar with the mathematical
purpose of such functions. For details on the math behind such functions,
see a more elementary reference.
Note that the following functions are important to learn if you want to go
beyond the basics of expression writing:
sin or sind
linstep
smoothstep
hermite
noise
dnoise
rand
sphrand
Function syntax
To help you quickly reference different functions, this chapter includes a
syntax format statement for each function. The format follows:
datatype
function(datatype argument)
206
Functions
Function syntax
Note that for either datatype, you dont type a value. The datatype tells you
the type of data you must enter or the data type returned by the executed
function.
The data types are in small type size for easy identification in the syntax
definitions.
Example 1
int
abs(int number)
float
abs(float number)
The function name is abs, which returns the absolute value of the number of
your choice. The absolute value of a number is the number without its
positive or negative sign.
This example shows the abs function has three formats. Each version
requires an argument with a different data type and returns a value with a
different data type.
The first version indicates that you can type an integer argument, and the
function returns an integer result. For example, abs(-3) returns 3.
The third version indicates you can type a vector, and the function returns a
vector. For example abs(<<3, -6.3, -2>>) returns <<3, 6.3, 2>>.
Example 2
Many functions have only one format, for example, the deg_to_rad function:
float
207
Expressions
The second version indicates that you can type a floating point argument,
and the function returns a floating point result. For instance, abs(-7.54)
returns 7.54.
Functions
Function syntax
Data types
In many cases, entering a data type other than the type expected by a
function causes an error and prevents the expression from executing. For
example, if you enter a vector argument where a floating point number is
expected, an error occurs.
For a function argument that expects a floating point number, however, you
can instead type an integera number without a decimal point. Maya
converts an integer to a floating point number in arithmetic operations.
If an error occurs when you create an expression, check that youre using the
appropriate data types for all arguments.
Notes
In this book, examples of floating point return values show no more than
three digits to the right of the decimal point. If you display the contents of
an attribute or variable in the Script Editor, youll see as many as 10 digits
to the right of the decimal point.
For instance, an example might show a return value as 3.539 rather than
the precise value 3.538654390. The examples round up such numbers for
ease of reading.
Note also that converting radians to degrees and vice versa results in
rounding errors. For example, converting a radian value might result in
89.99999996 degrees rather than 90.0 degrees.
208
Functions
Limit functions
Examples
Ball.scaleY = abs(-1);
This statement assigns Ball.scaleY the value returned by the abs(-1) function.
If you use a function in an expression statement and do not assign the
returned value to an attribute, the statement has no effect.
abs(-1);
Returns 1, but doesnt assign it to an attribute. This has the same result as
the following meaningless statement:
1;
Limit functions
The limit functions are math functions that impose limits on numbers.
abs
int
Expressions
float
abs(float number)
vector
abs(vector number)
number is the number for which you want the absolute value.
Examples
abs(-1)
209
Functions
Limit functions
abs(<<-1,-2.43,555>>)
ceil
Returns a number rounded to the smallest integer value greater than or
equal to a floating point number.
float
ceil(float number)
Examples
ceil(2.344)
Returns 3.
ceil(3.0)
Returns 3.
ceil(Rock.scaleY)
floor
Returns a number rounded to the largest integer less than or equal to a
floating point number.
float
floor(float number)
Examples
floor(2.344)
Returns 2.
floor(3.0)
Returns 3.
210
Functions
Limit functions
floor(Head.height)
clamp
Returns a number within a range. You can use the clamp function to confine
an increasing, decreasing, or randomly changing number to a range of
values.
float
Examples
clamp(4,6,22)
clamp(4,6,2)
211
Expressions
Functions
Limit functions
min
Returns the lesser of two floating point numbers.
float
Examples
min(7.2,-3.2)
Returns -3.2.
Desk.height = -2;
Lamp.height = 9;
$Mylight = min(Desk.height,Lamp.height);
max
Returns the larger of two floating point numbers.
float
Examples
max(7.2,-3.2)
Returns 7.2.
Desk.height = -2;
Lamp.height = 9;
$Mylight = max(Desk.height,Lamp.height);
Sets $Mylight to 9.
sign
Returns one of three values representing the sign of a number. Returns -1 if
the number is negative, 1 if positive, 0 if 0.
float
212
Functions
Limit functions
Examples
sign(-9.63)
Returns -1.
sign(0)
Returns 0.
sign(10)
Returns 1.
sign(Ball.translateX)
trunc
Returns the whole number part of a floating point number.
float
trunc(float number)
Examples
trunc(2.344)
Expressions
Returns 2.
trunc(0.3)
Returns 0.
trunc(-2.82)
Returns -2.
trunc(time)
213
Functions
Exponential functions
Exponential functions
The following functions work with exponential values.
exp
Returns e raised to the power of a number, enumber. The predefined variable e
is the base of the natural logarithm, which is 2.718.
float
exp(float number)
Examples
exp(1)
log
Returns the natural logarithm of a number, logenumber. The natural
logarithm uses the constant e, which is 2.718.
float
log(float number)
number is the positive number for which you want the natural logarithm.
Examples
log(10)
Returns 2.303.
log(2.718282845904)
Returns 1.000.
log10
Returns the log base 10 of a number.
float
log10(float number)
number is the positive number for which you want the log base 10.
214
Functions
Exponential functions
Examples
log10(100)
Returns 2.
log10(10)
Returns 1.
pow
Returns a base number raised to an exponent.
float
base is the base number you want to raise to the exponent. A negative base
number with a decimal component causes an error message.
exponent is the exponent.
Examples
pow(2,3)
Returns 8.
pow(-2,3)
Expressions
Returns -8.
pow(2,-3)
Returns 0.125.
sqrt
Returns the square root of a positive number.
float
sqrt(float number)
number is the positive number of which you want the square root.
A negative number displays an error message.
Examples
sqrt(16)
Returns 4.
215
Functions
Trigonometric functions
sqrt($side)
Trigonometric functions
The following functions return trigonometric values. Each function has two
formats that let you choose the type of angular unit you work with: degrees
or radians. For example, the cos function expects an argument in radians,
while cosd expects an argument in degrees.
A radian equals 180 degrees divided by pi, or roughly 57.3 degrees. Note
that pi equals 3.1415927, which is also 180 degrees.
cos
Returns the cosine of an angle specified in radians.
float
cos(float number)
adjacent
B
cos = ------------------------------ = ---hypotenuse
C
Y
B
B
A
C
216
Functions
Trigonometric functions
The cosine ratio depends only on the size of the angle and not on the size of
the triangle. This constant ratio is called the cosine of the measure of the
angle.
The cosine ratio is a value between -1 and 1.
With a steadily increasing or decreasing argument, the cos function returns
steadily increasing or decreasing values between 1 and -1. This is useful for
creating rhythmic, oscillating changes in attribute values.
The cos function works like the sin function except its return values are 90
degrees, or pi/2, out of phase.
See page 219 for ideas on how to use the cyclical characteristics of the sin
and cos functions.
Example 1
cos(1)
Example 2
To animate the motion of Ball in a cosine wave pattern, use this expression:
Ball starts at the origin and moves in the X direction at a rate set by the
incrementing animation time. Its Y translation moves cyclically up and
down according to the return values of the cos function. The cos function
uses translateX, and therefore indirectly, time, as its argument.
As time increases from 0 to 6.283 seconds, the cos function returns values
that change in fine increments from 1 to -1 and back to 1. The value 6.283 is 2
times the value of pi.
As time increases beyond 6.283 seconds, the same cycle repeats for each span
of 6.283 seconds.
217
Expressions
Ball.translateX = time;
Ball.translateY = cos(Ball.translateX);
Functions
Trigonometric functions
Ball.translateY = cos(Ball.translateX);
time = 6.283
(2 * pi seconds)
time = 6.283
(2 * pi seconds)
The cosine curve is 1.571 (pi/2) seconds ahead of (or behind) the sine curve,
and vice versa.
cosd
Returns the cosine of an angle specified in degrees.
float
cosd(float number)
218
Functions
Trigonometric functions
Example
cosd(45)
sin
Returns the sine of an angle specified in radians.
float
sin(float number)
opposite
A
sin = ------------------------------ = ---hypotenuse
C
Y
C
A
A
C
If is from 0 to pi radians (0 to
180 degrees), sin is a value
between 0 and 1.
The sine ratio depends only on the size of the angle and not on the size of
the triangle. This constant ratio is called the sine of the measure of the angle.
The sine ratio is a value between -1 and 1.
With a steadily increasing or decreasing argument, the sin function returns
steadily increasing or decreasing values between -1 and 1. This is useful for
creating rhythmic, oscillating changes in attribute values.
Using Maya: Hypergraph, Sets & Expressions
219
Expressions
Functions
Trigonometric functions
For example, you can use the sin function to manipulate:
Example 1
float $pi = 3.1415927;
sin($pi/2)
Example 2
Ball.translateY = sin(Ball.translateX);
This statement sets Balls translateY attribute equal to the sine of its
translateX attribute. If you drag Ball along the X-axis, Balls translateY
position moves up and down in a cyclical pattern:
Example 3
To animate Ball to the path of the preceding example, use this expression:
Ball.translateX = time;
Ball.translateY = sin(Ball.translateX);
220
Functions
Trigonometric functions
Ball starts at the origin and moves in the X direction at a rate set by the
incrementing animation time. Its Y translation moves cyclically up and
down according to the return values of the sin function. The sin function
uses translateX, and therefore indirectly, time, as its argument.
As time increases from 0 to 6.283 seconds, the sin function returns values
that change in fine increments from 0 to 1 to -1 to 0. The value 6.283 is 2
times the value of pi. The resulting motion resembles a horizontal S-shape:
time = 6.283
(2 * pi seconds)
As time increases beyond 6.283 seconds, the same S-shaped cycle repeats for
each span of 6.283 seconds.
Amplitude
221
Expressions
Example 4
Functions
Trigonometric functions
You can decrease the amplitude of the sine wave by multiplying by a
number less than 1, for example, 0.5.
Example 5
This expression increases how often the sine wave completes a cycle:
Ball.translateX = time;
Ball.translateY = sin(Ball.translateX * 2);
Frequency
Example 6
This expression offsets the wave pattern higher up the Y-axis:
Ball.translateX = time;
Ball.translateY = sin(Ball.translateX) + 2;
By adding 2 to sin(Ball.translateX), the wave pattern starts further up the Yaxis. You can, of course, also subtract a number to offset the wave pattern
lower on the Y-axis.
222
Functions
Trigonometric functions
Offset of 2
Example 7
The following expression sets a frequency multiplier, amplitude, and offset
of a sine pattern in a single statement:
Ball.translateX = time;
Ball.translateY = (sin(Ball.translateX * 2) * 2) + 2;
Expressions
The following diagram shows which values set the frequency multiplier,
amplitude, and offset.
Frequency multiplier
Amplitude
Offset
Ball.translateY = (sin(Ball.translateX * 2) * 2) + 2;
A general equation showing the factors you can use to create a sine wave
pattern follows:
attribute = (sin(frequency * frequency multiplier) * amplitude) + offset;
223
Functions
Trigonometric functions
sind
Returns the sine of an angle specified in degrees.
float
sind(float number)
Example
sind(90)
tan
Returns the tangent of an angle specified in radians.
float
tan(float number)
opposite
A
tan = ----------------------- = --adjacent
B
Y
B
B
A
C
224
Functions
Trigonometric functions
The ratio depends only on the size of the angle and not on the size of the
triangle. This constant ratio is called the tangent of the measure of the angle.
Example
tan(1)
Returns 1.557.
tand
Returns the tangent of an angle specified in degrees.
float
tand(float number)
Example
tand(45)
Returns the radian value of the arc cosine of a number. The arc cosine is the
angle whose cosine is the specified number. The returned value is from 0 to
pi.
float
acos(float number)
Example
acos(1)
Returns 0.
acos(-0.5)
225
Expressions
acos
Functions
Trigonometric functions
acosd
Returns the degree value of the arc cosine of a number. The arc cosine is the
angle whose cosine is the specified number. The returned value is from 0 to
180.
float
acosd(float number)
Example
acosd(1)
Returns 0 degrees.
acosd(-0.5)
asin
Returns the radian value of the arc sine of a number. The arc sine is the angle
whose sine is the specified number. The returned value is from -pi/2 to pi/2.
float
asin(float number)
Example
asin(0.5)
asind
Returns the degree value of the arc sine of a number. The arc sine is the
angle whose sine is the specified number. The returned value is from -90 to
90.
float
asind(float number)
226
Functions
Trigonometric functions
Example
asind(0.5))
Returns 30 degrees.
atan
Returns the radian value of the arc tangent of a number. The arc tangent is
the angle whose tangent is the specified number. The returned value is from
-pi/2 to pi/2.
float
atan(float number)
Example
atan(1)
Returns 0.785.
atand
float
atand(float number)
Example
atand(1)
Returns 45 degrees.
atan2
Returns the radian value of the arc tangent of specified X and Y coordinates.
The arc tangent is the angle from the X-axis to a line passing through the
origin and a point with coordinates X,Y. The returned angle is in radians,
from -pi to pi, excluding -pi.
float
atan2(float Y, float X )
227
Expressions
Returns the degree value of the arc tangent of a number. The arc tangent is
the angle whose tangent is the specified number. The returned value is from
-90 to 90.
Functions
Trigonometric functions
Y is the Y coordinate of the point.
Example
atan2(1,1)
atan2d
Returns the degree value of the arc tangent of specified X and Y coordinates.
The arc tangent is the angle from the X-axis to a line passing through the
origin and a point with coordinates X,Y. The returned angle is in degrees,
from -180 to 180, excluding -180.
float
atan2d(float Y, float X )
Example
atan2d(1,1)
Returns 45 degrees.
hypot
Returns the magnitude of two-dimensional vector from the origin to a point
with coordinates X, Y.
Y
hypot
(X,Y)
X
228
Functions
Vector functions
As shown in the preceding figure, the hypot function returns the radius of a
circle whose center is at one end of a right triangles hypotenuse and
perimeter is at the other end of the hypotenuse.
The following equation gives the magnitude of the vector:
2
x +y
float
hypot(float x, float y)
Example
hypot(3,4)
Returns 5.
Vector functions
Expressions
angle
Returns the radian angle between two vectors.
Vector1
Angle
Vector2
float
229
Functions
Vector functions
vector2 is the other vector.
The returned angle is the shortest angle between the two vectors. The
measurement is always less than 180 degrees.
Example
angle(<<2,-1,1>>,<<1,1,2>>)
cross
Returns the cross product of two vectors.
For two vectors, the cross product returns the vector thats normal to the
plane defined by the two vectors.
Vector1
Vector2
Cross product
vector
If the cross product is 0, the two vectors are parallel or colinear. If one or
both vectors are <<0,0,0>>, the cross product returns <<0,0,0>>.
vector1 is one of the vectors.
vector2 is the other vector.
Example
cross(<<1,2,-2>>,<<3,0,1>>)
230
Functions
Vector functions
dot
Returns the floating point dot product of two vectors. The dot product takes
two vectors as arguments and returns a scalar value.
float
Example
dot(<<1,2,-2>>,<<3,0,1>>)
mag
Returns the magnitude of a vector. This is the length of the vector.
Y-axis
Expressions
<<X, Y, Z>>
Y
X-axis
Z-axis
Magnitude
float
mag(vector vector)
231
Functions
Vector functions
The mag function converts a vector into a floating point number using the
following formula.
2
x +y +z
Example
mag(<<7,8,9>>)
Returns 13.928.
2
7 + 8 + 9 = 13.928
rot
Returns a vector that represents the position of a point after its rotated a
specified number of radians about a specified axis. Rotation is counterclockwise as viewed downward from the axis end position.
Position of point
before rotation
Angle
Position of point
after rotation
Axis
vector
232
Functions
Vector functions
Example 1
rot(<<3,3,0>>,<<1,0,0>>,0.5)
Example 2
particleShape1.position = rot(position,<<0,1,0>>,0.1);
Expressions
unit
Returns the unit vector corresponding to a vector.
The unit vector has the same direction as the specified vector, but with a
magnitude of 1.
vector
Example
unit(<<1,1,1>>)
233
Functions
Conversion functions
Y
<<1, 1, 1>>
<<0.577, 0.577, 0.577>>
X
Z
Unit vector (magnitude = 1)
Conversion functions
The following functions convert color scheme values or angle
measurements.
deg_to_rad
Returns the radian equivalent of a degree value. One radian equals roughly
57.29578 degrees.
float
Example
deg_to_rad(90)
rad_to_deg
Returns the degree equivalent of a radian value. One radian equals roughly
57.29578 degrees.
float
rad_to_deg(float radians)
234
Functions
Conversion functions
Examples
rad_to_deg(1)
Returns 57.296.
float $pi = 3.1415927;
rad_to_deg($pi)
Returns 180.
hsv_to_rgb
Converts an HSV vector to an RGB vector.
vector
hsv_to_rgb(vector hsv)
Example
hsv_to_rgb(<<1,0.5,0.6>>)
Tip
rgb_to_hsv
Converts an RGB vector to an HSV vector.
235
Expressions
To see the relationship between HSV and RGB color components, enter the
MEL command colorEditor at the Command Line. This displays the Color
Chooser window.
Functions
Array functions
vector
rgb_to_hsv(vector rgb)
Example
rgb_to_hsv(<<0.6,0.6, 0.6>>)
Array functions
The following functions work with integer, floating point, and vector arrays.
If you need more information, see a reference book on the C programming
language.
clear
Empties the arrays contents, freeing all memory reserved for the array.
After you clear an array, its size is 0. When you no longer need to use an
array, use the clear function to free memory.
int
clear(array array)
Example
int $myInts[] = {1,2,3,4,5,6};
print("size of $myInts is: "+size($myInts)+"\n");
clear($myInts);
print("size of $myInts is: "+size($myInts)+"\n");
236
Functions
Array functions
size
Returns the number of elements in an array or the number of characters in a
string.
int
size(array array)
int
size(string string)
Example 1
string $s = "Hello";
$stringlen = size($s);
Example 2
int $myInts[] = {1,2,3,4,5,6};
$numInts = size($myInts);
Example 1
int $myInts[] = {3,6,1,4,2,5};
int $afterSorting[] = sort($myInts);
print("After sorting, the array contains:\n");
for ($i = 0; $i < 6; $i = $i + 1)
{
print($afterSorting[$i]+"\n");
}
237
Expressions
sort
Functions
Array functions
The sort function sorts the elements of $myInts in ascending order. The
following appears in the Script Editor:
After sorting, the array contains:
1
2
3
4
5
6
Example 2
string $myName[] = {"Peewee","Michael","Kennedy"};
string $afterSorting[] = sort($myName);
print("After sorting, the array contains:\n");
for ($i = 0; $i < 3; $i = $i + 1)
{
print($afterSorting[$i]+"\n");
}
The sort function sorts the elements of $myName in alphabetical order. The
following appears in the Script Editor:
After sorting, the array contains:
Kennedy
Michael
Peewee
238
Functions
Random number functions
gauss
Returns a random floating point number or vector. The number returned
falls within a Gaussian (bell curve) distribution with mean value 0.
float
gauss(float stdDev)
vector
vector
gauss(vector stdDevVector)
stdDev specifies the value at which one standard deviation occurs along the
distribution. This gives a one-dimensional Gaussian distribution.
XstdDev and YstdDev specify the values for one standard deviation. This
gives a two-dimensional Gaussian distribution in the XY plane. The right
component of the vector returned is 0.
stdDevVector specifies the vector component values for one standard
deviation. This gives a three-dimensional distribution.
Example
gauss(5)
239
Expressions
To control the random values returned by this function, see seed on page
246.
Functions
Random number functions
If you were to execute gauss(5) repeatedly and chart the values returned,
they would occur roughly with this frequency:
Mean
One standard deviation
Number of
occurrences
-5
Value returned
If you were to execute gauss(2) repeatedly, return values would occur with
this frequency:
Mean
One standard deviation
Number of
occurrences
-2
Value returned
240
Functions
Random number functions
noise
Returns a random number from -1 to 1 according to a Perlin noise field
generator.
float
noise(float number)
float
float
noise(vector vector)
noise(time)
1
Return
value 0
-1
noise(time) as animation plays
241
Expressions
Example 1
Functions
Random number functions
Example 2
noise(frame)
1
Return
value 0
-1
noise(frame) as animation plays
The value returned by noise(frame) and noise(time) is the same when frame
contains the same number as time. For example, when frame equals 10,
noise(frame) returns the same value that noise(time) returns when time is 10.
dnoise
Returns a vector with each component containing a random number from -1
to 1. It works like the noise function except it expects and returns a vector
argument. The returned vector represents the gradient of the noise field in
three dimensions.
vector
dnoise(vector argument)
Example
dnoise(<<10,20,-30>>)
242
Functions
Random number functions
rand
Returns a random floating point number or vector within a range of your
choice.
float
rand(float maxnumber)
float
vector
rand(vector maxvector)
vector
maxnumber specifies the maximum number returned (in the first syntax
format listed above). The minimum number returned is 0. In other words,
the returned value will be a random number between 0 and maxnumber.
minnumber and maxnumber specify the minimum and maximum numbers
returned.
maxvector specifies the maximum value for each component of the vector
returned. The minimum value is 0. Each component returned is a different
random number.
minvector and maxvector specify the minimum and maximum value for each
component of the vector returned.
Example 1
rand(5)
Example 2
rand(-1,1)
243
Expressions
To control the random values returned by this function, see seed on page
246.
Functions
Random number functions
If you were to execute rand(-1,1) repeatedly as an animation plays, its return
values might occur as in this figure:
1
Return
value 0
-1
rand(1,-1) as animation plays
Example 3
rand(<<1,1,1>>)
Example 4
rand(<<1,1,1>>,<<100,200,300>>)
Returns a random vector in which the left component is between 1 and 100,
the middle component is between 1 and 200, and the right component is
between 1 and 300. An example is <<81.234, 49.095, 166.048>>.
sphrand
Returns a random vector value that exists within a spherical or ellipsoidal
region of your choice. An ellipsoid is a sphere scaled along its X-, Y- or Zaxes.
vector
sphrand(float radius)
vector
sphrand(vector vector)
244
Functions
Random number functions
Example 1
sphrand(1)
radius
Example 2
sphrand(<<2,1,1>>)
Radius in Z
1
Radius in X
Outer bound of
returned value
Radius in Y
245
Expressions
Functions
Random number functions
1
Select the particle shape node of the particle object in the Expression Editor.
Turn on Creation.
Maya executes the expression once for each particle. It gives each particle a
different random position around the origin within the ellipsoid specified by
<<2,1,1>>.
seed
Sets a seed value the gauss, rand, and sphrand functions use to generate
random numbers. If you assign a value to the seed then execute the gauss,
rand, or sphrand function repeatedly, an identical sequence of random
numbers is generated. For clarification, see the example below and
Reproducing randomness on page 123.
int
seed(int number)
Example
Suppose you create a NURBS sphere named Ball then enter this expression:
Ball.translateX = rand(5);
246
Functions
Random number functions
When you rewind the animation, Balls translateX attribute receives a
random value between 0 and 5, for example, 1.392. When you play the
animation, the translateX attribute receives a different random value
between 0 and 5 each frame.
When you rewind the animation again, the translateX attribute receives a
value thats different from the value it received the first time you rewound,
for example, 3.223.
When you play the animation again, the translateX attribute receives a value
each frame thats different from the values it received the first time you
played the animation. In short, every time the rand(5) executes, it gives a
different random value.
Suppose you change the expression to this:
if (frame == 1)
seed(1);
Ball.translateX = rand(5);
Rewinding the scene to frame 1 executes the seed(1) function. It then assigns
translateX a random value between 0 and 5, for example, 4.501.
When you play the animation, the rand(5) function executes each frame and
returns a different value. Example returned values follow:
Value
4.501
3.863
3.202
3.735
2.726
0.101
Expressions
Frame
Each time you rewind and play the animation, translateX receives the same
sequence of random values.
For different seed values, the sequence of numbers returned will differ. You
cant predict the values in the number sequence based on the value of the
seed.
247
Functions
Random number functions
Suppose you change the expression to this:
if (frame == 1)
seed(500);
Ball.translateX = rand(5);
The rand(5) function returns these values as you rewind and play the
animation:
Frame
Value
4.725
2.628
0.189
0.004
4.834
0.775
By changing the seed functions value, you change the sequence of random
numbers generated.
A common mistake while using the seed function follows:
seed(1);
Ball.translateX = rand(5);
When you rewind the animation, Balls translateX attribute receives the
value 4.501. When you play the animation, the translateX attribute receives
4.501 each time the expression executes.
Because you assign a value (1) to the seed before each execution of rand(5),
you initialize the random number sequence. The rand(5) function therefore
returns the first value of the number sequence each time it executes.
Important
When you set a seed value in an expression or MEL script, the seed value
affects the rand, sphrand, and gauss functions in other expressions and
MEL scripts. Such functions are affected by this seed value in all scenes
you open subsequently in the current work session.
248
Functions
Curve functions
Curve functions
The step functions let you make smooth, incrementing transitions between
values.
linstep
Returns a value from 0 to 1 that represents a parameters proportional
distance between a minimum and maximum value. This function lets you
increase an attribute such as opacity from 0 to 1 linearly over a time range.
float
Example
Suppose youve used the Particle Tool to create a collection of particles
named Cloud:
Expressions
Suppose further youve added a dyamic per object opacity attribute to Cloud
(see Working with particle attributes in Chapter 8). You then write this
runtime expression for Clouds particle shape node:
CloudShape1.opacity = linstep(0,5,age);
249
Functions
Curve functions
This expression increases the per object opacity attribute of CloudShape1 in
equal steps from 0 to 1 for the first 5 seconds of the objects existence.
Because you created the object with the Particle Tool, the particles existence
begins in the first frame of the animation.
All particles in the object fade in from transparent to opaque for the first 5
seconds of animation.
At the first frame that plays, the age of the particles is 0, so the linstep
function returns 0 for the opacity. An opacity of 0 is transparent.
In each subsequent frame, the linstep function returns a proportionally
larger opacity value. When the age of the object reaches 5, the linstep
function returns 1 for the opacity. An opacity of 1 is 100% opaque.
When the age exceeds 5, the linstep function returns 1. The opacity stays
100% opaque. Here are some values returned for the objects opacity:
250
Age
Opacity
0.0417
0.0083
0.0833
0.0166
0.125
0.025
0.1667
0.0333
0.2083
0.0417
2.5
0.5
1.0
0.2
3.75
0.75
5.041
5.083
10
Functions
Curve functions
As the table shows, the opacity increases in linear increments for the first 5
seconds of the objects age. At the midpoint of the specified 0 to 5 second age
range, the opacity is 0.5. At 3/4 of the way between 0 and 5 seconds, the
opacity is 0.75. At 5 seconds of the objects age, opacity is 1. After 5 seconds,
the opacity stays at 1.
1
opacity
5
age (in seconds)
This increases the opacity attribute linearly from 0 to 1 as the objects age
increases from 5 to 10 seconds.
Expressions
opacity
5
age (in seconds)
10
This decreases the opacity attribute linearly from 1 to 0 for the first 5 seconds
of the objects age. Subtracting linstep(0,5,age) from 1 causes the opacity to
fade out rather than fade in.
251
Functions
Curve functions
opacity
5
age (in seconds)
smoothstep
Returns a value from 0 to 1 that represents a parameters proportional
distance between a minimum and maximum value. The smoothstep function
lets you increase an attribute such as opacity from 0 to 1 gradually, but
nonlinearly, over a time range.
The smoothstep function works like the linstep function, except it increases
values more quickly near the middle values between the minimum and
maximum value. The function uses hermite interpolation between minimum
and maximum values.
float
252
Functions
Curve functions
The following figure compares values returned by smoothstep and linstep
over time:
parameter
smoothstep
start
linstep
end
Example
Suppose youve used the Particle Tool to create a collection of particles
named Cloud:
Expressions
Suppose also youve added a dynamic per object opacity attribute to Cloud
(see Working with particle attributes in Chapter 8). You then write this
runtime expression for Clouds particle shape node:
CloudShape1.opacity = smoothstep(0,5,age);
253
Functions
Curve functions
This increases the opacity attribute of CloudShape1 in steps from 0 to 1 for
the first 5 seconds of the objects age. This makes the object fade in from
transparent to opaque. The fade in and fade out of the opacity occurs more
quickly around 2.5, the midpoint between 0 and 5.
1
opacity
5
age (in seconds)
hermite
Returns values along a hermite curve. You can use the hermite function, for
instance, to move a particle objects position smoothly along a curve. As the
examples in the following pages show, you can create various curve shapes
by altering the arguments to the hermite function.
vector
float
hermite(vector start, vector end, vector tan1, vector tan2, float parameter)
hermite(float start, float end, float tan1, float tan2, float parameter)
254
Functions
Curve functions
Example 1
Suppose you create an object named dust made of one particle at the origin.
To guide its motion along a short upward-bound curve for the first four
seconds of animation, you can write the following runtime expression:
dust.position = hermite(<<0,0,0>>,<<2,2,0>>,
<<3,0,0>>, <<0,3,0>>, linstep(0,4,time));
When you play the animation, the particle moves from the start point
<0,0,0> along a curve to the end point <2,2,0>. The tangent vector <3,0,0>
sets the curves direction and shape as it leaves the start point. The tangent
vector <0,3,0> sets the curves direction and shape as it approaches the end
point.
From zero to four seconds of animation play, the particle moves along the
curve as defined by the linstep function. (See page 249 for details on linstep.)
The function arguments and resulting path of the object follow:
Y
tan2 = <<0,3,0>>
Expressions
end = <<2,2,0>>
Objects path
start = <<0,0,0>>
tan1 = <<3,0,0>>
Example 2
Suppose you change the third argument of the previous example expression
to <<6,0,0>>:
dust.position = hermite(<<0,0,0>>,<<2,2,0>>,
<<6,0,0>>, <<0,3,0>>, linstep(0,4,time));
255
Functions
Curve functions
The slope of the path curve steepens because of the longer tan1 vector:
Y
tan2 = <<0,3,0>>
end = <<2,2,0>>
Objects path
X
start = <<0,0,0>>
tan1 = <<6,0,0>>
Example 3
The following expression moves dust in an S pattern:
dust.position = hermite(<<0,0,0>>,<<2,0,0>>,
<<0,3,0>>, <<0,3,0>>, linstep(0,4,time));
Y
tan1 = <<0,3,0>>
tan2 = <<0,3,0>>
X
start = <<0,0,0>>
end = <<2,0,0>>
The tan1 vector <<0,3,0>> sets the direction of the curve from the start point
to a positive Y direction. The tan2 vector <<0,3,0>> sets the direction of the
curve to a positive Y direction as it approaches the end point.
Values between the start and end point curves are interpolated to form an S
pattern.
256
Functions
Curve functions
Example 4
Suppose you change the fourth argument of the previous example
expression to <<0,-3,0>>:
dust.position = hermite(<<0,0,0>>,<<2,0,0>>,
<<0,3,0>>, <<0,-3,0>>, linstep(0,4,time));
tan1 = <<0,3,0>>
X
start = <<0,0,0>>
end = <<2,0,0>>
Expressions
tan2 = <<0,-3,0>>
The tan1 vector <<0,3,0>> sets the direction of the curve from the start point
to a positive Y direction. The tan2 vector <<0,-3,0>> sets the direction of the
curve to a negative Y direction as it approaches the end point.
Example 5
Suppose you change the third argument of the preceding example to
<<0,10,0>>:
dust.position = hermite(<<0,0,0>>,<<2,0,0>>,
<<0,10,0>>, <<0,-3,0>>, linstep(0,4,time));
257
Functions
Curve functions
Y
tan1 = <<0,10,0>>
X
start = <<0,0,0>>
end = <<2,0,0>>
tan2 = <<0,-3,0>>
Because of the longer tan1 vector, the slope of the path curve steepens as it
rises from the start point. Because the tan2 vector has a smaller Y magnitude
than the Y magnitude of the tan1 vector, the slope of the path curve is flatter
as it approaches the end point. The curves rise in the Y direction is greater
than the previous example because the magnitude of tan1s Y component is
larger (10 instead of 3).
258
Functions
General commands
General commands
The following functions do various actions in Maya.
eval
Executes a MEL command.
string
eval(string command)
Example 1
eval("select -cl")
Executes the command select -cl, which deselects all objects in the scene.
Though the return value is not used in this example, it contains the
command output.
Example 2
The first statement assigns the command string select -cl to the string variable
$cmd. The second statement executes the contents of $cmd, which is the
command select -cl.
Example 3
string $mycommand = "sphere";
eval($mycommand+"-r 5");
The first statement assigns the string sphere to the variable $mycommand.
The second statement appends -r 5 to the string sphere and executes the
complete command sphere -r 5. This creates a sphere with a radius of 5 grid
units.
259
Expressions
Functions
General commands
Example 4
string $a[];
$a = eval("ls -lights");
print($a);
The first statement defines an array of strings named $a. The second
statement executes the MEL command ls -lights, then assigns the commands
output to array $a. The third statement displays the contents of $a to the
Script Editor as follows:
ambientLightShape1
directionalLightShape1
Note that each line of command output appears on a new line. Each
command output line is an array element. Maya formats array output with
each array element on a new line.
Example 5
Suppose youve created a MEL script file named bunk.mel in your Maya
scripts directory and it contains this procedure:
global proc string bunk()
{
string $fog;
if (rand(2) < 1)
$fog = "particle";
else
$fog = "sphere";
return $fog;
}
260
Functions
General commands
The procedure finishes executing and passes the value of $fog back to the
calling procedure, bunk() in the expression. This assigns the command string
to the variable $name.
The eval function executes the command string stored in the $name. For
example, the statement might execute particle, which creates a particle at the
origin of the workspace.
The fourth statement displays the contents of $name, for example, particle.
The expression executes each frame and creates a new particle or sphere.
print
Displays text in the Script Editor. You can use this function to display the
contents of attributes and variables. This is helpful for debugging an
expression.
print(string text)
print(vector number)
print(float number)
print(int number)
print(array number)
You can format displayed text with standard C language escape characters.
For example, you can create a new line with \n or a tab character with
\t in the argument.
261
Expressions
Functions
General commands
If you assign a string to a variable thats not a string data type, the following
text appears if you display the variable:
Variable data type
String assignment
Data displayed
float
"3.14"
3.14
int
"3.14"
vector
"3.14"
3.14 0 0
float
"pi is 3.14"
0, error message
As shown in the last row of the table, if a variable is assigned a string that
starts with a nonnumerical character, Maya converts the string to 0.
262
Functions
General commands
Examples
print(time);
print("\n");
The first statement displays the value of time. The second statement displays
a new-line character after the value of time, so the time appears on a
separate line in the Script Editor.
float $f = 3.14159;
print($f);
Expressions
The print function causes an error message because you cannot use the +
operator with a string array.
system
Passes a UNIX command to the shell where you launched Maya.
int
Example
string $cmdout;
$cmdout = system("date");
print($cmdout+"\n");
263
Functions
Other functions and commands
Executes the UNIX date command, which outputs your workstations date
and time to the $cmdout variable. The final statement displays the date in
the Script Editor.
Math
Curve
String
File
alias
acosh
besselj0
gmatch
fopen
catch
asinh
besselj1
match
fclose
chdir
atanh
besseljn
size
fflush
env
constrainValue
besselyn
strcmp
popen
error
erf
substitute
pclose
exists
erfc
substring
fprint
getenv
expm1
tokenize
frewind
getpid
fmod
tolower
feof
gmatch
gamma
toupper
fgetline
putenv
log1p
pwd
fwrite
source
fread
trace
filetest
warning
whatIs
264
fgetword
Index
Symbols
abbreviating attribute
names 112, 116
abs function 209
absolute value 209
acceleration 197
acceleration attribute
assigning constant value
to 156
assigning with runtime
expression 155
changing value randomly 156
fields effect on 175
initialization to zero 177
working with 175
acos function 225, 226
Add Attribute window 50, 120,
169
Add Dynamic Attributes 49, 161
Add Initial State Attribute
checkbox 163, 170
adding custom attributes 119,
169
age 197
age of particles
at rewind 150
how to examine 150
runtime expression execution
and 152
when created with Particle
tool 168
alias UNIX command
avoiding use with text
editor 109
Always Evaluate 130
Always Evaluate checkbox 118
amplitude of sin function 221
angle function 229
angular units
conversion of 128
degrees 29, 127
radians 29, 127
arc cosine 225, 226
arc sine 226
arc tangent 227, 228
arguments in functions 205
arithmetic operators 63
array (per particle) attributes 163
assigning to array of different
length 172
array functions 236
array indexes
invalid assigment to 193
Array option for per particle
attributes 170
arrays 93
clearing contents of 236
display format 262
element assignment 95
example initialization and
usage 93
exceeding memory capacity
of 93
expansion of 93
invalid assignment to
indexes 193
obtaining size of 237
sorting 237
asin function 226
assigning
to attributes 55
to int or float variables 60
to specific particles 189
to vector attributes 56
to vector components 193,
194
to vector variables 61
vector to three scalar
attributes 56
assignment operator 47
265
Index
! 87
- 63
-- 92
!= 65, 66
$ 59, 73
% 63, 182
%= 92
&& 67
* 63
*= 92
+ 63
++ 92
+= 92
/ 63
// 75
/= 92
< 65
<< >> 53, 73, 180, 193
<= 65
-= 92
= 47, 55
== 65, 66, 74
> 65
>= 65
?: 86
\n 261
{ } 39, 70, 72, 73
| 140
|| 67
Index
266
attributes
abbreviating names 112, 116
assigning conditionally 32
assigning to 55
assigning to multiple 13, 23
assigning to multiple
objects 13, 28
connecting to symbolic
placeholders 135
custom 50
data types 51
deleting from
expressions 131
disconnecting from
expressions 132
displayed in Attributes list 18
displaying contents of 123
displaying disconnected 132
dynamic 49
eliminating expression control
of 122
full name 51
initial state 158, 162
linking 11, 15, 26
long names 114
name syntax 47
not selecting for particle shape
node 112
particle shape node 159
per object 12, 160
per particle 12, 160
reading in expressions 133
removing from
expressions 131
seeing abbreviations of 113,
115
static 49
unexpected values 141
Attributes list 103
B
base number raised to
exponent 215
bell curve function 239
betterIllumination 197
blank lines in expressions 74
Booleans 52
handling as floating point 65
symbolic constants 95
braces 72
in statements 39, 40
matching pairs of 73
brackets
double angle 53, 73, 180, 193
break instruction 79
C
C language
escape characters 261
syntax in expressions 75
case sensitivity in variable
names 59
castsShadows 201
ceil function 210
centimeters 127
Channel Box
displaying attribute values
in 30
choice command 132
circular motion of NURBS
sphere 119
clamp function 211
clear function 236
clearing
an expression 106
array contents 236
Index
conversion
of angular units only 128
of data types 143, 144
of user selected units 127
conversion functions 234
converting
degrees to radians 129
measurement units 128
statements to comments 131
copying text in expressions 105
cos function 216
comparison with sin
function 218
cosd function 218
cosine 216, 217, 218
cosine wave pattern
animating a ball 217
count 197
Create button 22
Create Event 184
creating new expressions 111
creation expressions 148
assigning to rgbPP 179
dynamics start frame 149
example assignment to
lifespan 165, 167
example assignment to
lifespanPP 164
execution for emitted
particles 149
how often execution
occurs 148
using values in runtime
expressions 174
when to use 150
cross function 230
cross product of two vectors 230
curve functions 249
custom attributes 50
adding to an object 119
adding to particle shape
node 169
assigning to 169
examples of assignment 171
when to use 118
custom variables 59
declaring 59
using globally 61
cyclical pattern with sin
function 220
D
data types
attribute 53
Boolean 52
conversion during
assignment 143, 144
conversion of displayed
strings 262
conversion with arithmetic
operators 145
data entry limitations 54
float array 52
floating point 52
functions 208
integers 52
matrix 55
vector array 52
debugging expressions with print
function 261
decimal deletion in data type
conversion 144
decimal precision in display 261
declaring variables 59
default object
in Expression Editor 104
making an object the 115
defining variables 26
deg_to_rad function 234
267
Index
collision
example of controlling color
resulting from 185
working with particles 183
color
Christmas light effect with
particles 181
giving object constant
color 179
giving particles randomly
changing color 180
understanding RGB and
HSV 235
working with 178
colorAccum 197
colorBlue 197
colorEditor 235
colorGreen 197
colorRed 197
comments
converting statements to 131
in expressions 75
compiling an expression 19, 62,
118
conditional assignment to
attributes 32
conditional statements 69
else-if 71
if 34, 69
if-else 70
confining numerical range 211
connectAttr command 135
connecting an attribute 135
Connection Editor 132, 135
conserve 197
constants 62
Boolean 95
continue instruction 80
controlling flow in statements 77
Index
degrees 29
converting to radians 129,
234
deleting
attribute names 131
expressions 112, 134
text from expressions 105
depthSort 197
discarded remainders in data type
conversions 146
disconnectAttr command 132
disconnecting an attribute 132
displaying
attribute contents 123
disconnected attributes 132
text 261
variable contents 123
dnoise function 242
do loop 78
dollar sign ($) in variable
names 59, 73
dot function 231
dot product 231
dot product operator 64
double angle brackets 53, 73,
180, 193
dynamic attributes 49
adding to object 49, 50, 161
dynamic per object attribute
example assignment to
lifespan 167
dynamic per particle attribute
example assignment to
lifespanPP 164
dynamics
changing start frame 149
how often Maya
evaluates 149, 152
Dynamics Controller 149, 152
dynamicsWeight 198
dynamicsWeight attribute 178
268
E
e raised to power 214
Edit button 22
editing expressions
in text field 99, 105
else keyword 38
else-if statements 71
emitted particles
age of 149
assigning lifespanPP for 183
creation expression execution
and 149
working with 183
English common names for
attributes 114
equal to (==) operator 36
errors
common expression 95
comparing floats with the ==
operator 89
from wrong data types in
functions 208
in flow control statements 88
logic 95
message format of 95
syntax 36, 73, 95
where they appear 96
eval function 259
event 198
event attribute 184
when collision count
increases 187
eventCount 198
eventCount attribute 184
eventTest 198
eventTest attribute 184
examining two or more
expressions 106
executing
MEL commands in
expressions 137
MEL commands with eval
function 259
MEL procedures in
expressions 139
nonparticle expressions 118
UNIX commands in
expressions 263
execution
slow expression 127
exp function 214
exponential functions 214
Expression Editor
starting 13
Index
F
fading opacity 249, 253
fields
influence on expression 175
turning off effect in an
expression 178
filtering attributes
by connected attribute 104
from Expression Editor 104
filtering expressions 99
finding expressions
by connected attribute 101
by expression name 100
by item type 102
by selected object 101
float 52, 57
float arrays data type 52
floating point 52
floor function 210
flow control errors 88
flow control statements 77
for loop 79
for-in loop 81
forward slashes (//) for
comments 75
frame 0
reason for using in
examples 43
frame playback rate 16, 58
frame variable 57
frequency multiplier of sin
function 222
G
gauss function 239
Gaussian distribution 239
General button 49
general commands 259
global procedures
declaring 139
global variables 61
declaring 62
initializing 62
goal attribute 161
Goal button 161
goalPP 198
goalPP attribute 161
Index
expressions
advantage of separate 31
advantage of single 31
comments in 75
common errors 95
comparison with MEL
scripts 46
compiling 19
copying text 105
creating 13
creating new 111
creation 148
default object 104
deleting 112, 131
deleting text in 105
displaying connected
attributes only 104
editing in text field 99
editing with text editor 106
elements of 46, 47
eliminating control of
attributes 122
erasing 106
examining two or more 106
execution for nonparticle
shapes 118
fields influence on 175
filtering 99
finding 100, 101, 102
for particles 147
input to 133, 135
keywords 76
names for particle shape
node 100
naming conventions 18
output from 134, 136
programming features 75
redundant execution 130,
154
reloading 106
required elements of 48
runtime 148
runtime execution 152
saving to file 107
269
Index
goalWeight 198
gravity field
accelerations effect on 177
H
half-circle
creating motion with hermite
function 257
hermite function 254
HSV conversion to RGB 235
hsv_to_rgb function 235
hypot function 229
I
if statements 32, 34, 69
if-else abbreviation 86
if-else statements 38, 39, 70
incandescence 198
incandescencePP 198
increment operations and
unexpected values 142
inheritFactor 198
initial state attributes 158, 162,
163
creation expression
execution 150
naming convention 163
saving values for 158
input to expressions 135
integers 52, 57
handling as floating point 65
internal conversion of units 127
isDynamic 198
K
keyframes
eliminating expression to
use 122
keywords in expressions 76
L
levelOfDetail 199
lifespan 198
lifespan attribute 161
example assignment in
creation expression 167
Lifespan button 161
lifespanPP 199
lifespanPP attribute 161, 164
assigning for emitted
particles 183
limit functions 209
lineWidth 199
linking attributes 11, 15, 26
linstep function 249
comparison with
smoothstep 253
listAttributes MEL command 163
log base 10 214
log function 214
logic errors 95
logical operators 67
&& 67
|| 67
long attribute names 114
looping errors 88
J
joining text in strings 262
270
M
mag function 231
magnitude of a vector 67, 231
mass 199
matrix data type 55
max function 212
maxCount 199
measurement units 127
MEL commands 45, 46
executing with eval
function 259
using alone in
statements 137
using with eval function 138
using within single
quotes 138
MEL procedures
using in expressions 138
MEL scripts 46
millimeters 128
min function 212
mixed data types
using with arithmetic
operators 145
modulus operator (%) 63, 182,
192
risk of using with floats 182
motion
creating jittery 175
creating smooth, random 175
multiCount 199
multiRadius 199
N
natural logarithm 214
new line characters in print
statement 261
Index
O
object names
omitting in expressions 115
path of 140
Objects list 103
offset with sin function 222
omitting object names in
expressions 115
online function
documentation 264
opacity 200
opacity attribute 161
fading over time 249, 253
Opacity button 161
opacityPP 200
opacityPP attribute 161
operators
arithmetic 48, 63
assigning values to 36
dot product 64
equal to 36, 65
greater than 65
greater than or equal to 65
less than 35, 65
less than or equal to 65
logical 48, 67
not equal to 65
precedence 68
relational 48, 65
shortcut assignment 91
shortcut increment and
decrement 92
order of statements 37
output from expression 134, 136
oversample level 152, 156
P
parentheses
matching pairs of 73
use in conditionals 68, 73
particle array attributes
assigning to different
lengths 172
particle attributes
list of 196
Particle Collision Events 184
particleId 200
particleId attribute 189
271
Index
particles
age of 150
assigning to specific 189
attribute data types 52
expressions for 147
moving position with hermite
function 254
selecting shape node 148
shape node attributes 159
transform node attributes 159
using sphrand to create
ellipsoid of 245
working with collisions 183
path names of objects 140
per object attributes 12, 160
keyframing 160
naming conventions 160
scalar option 170
per particle attributes 12, 53, 160
Array option 170
assigning to individual
particles 189
how to distinguish 160
naming conventions 160
Perlin noise field 241
playback rate 58
pointSize 200
position 200
position attribute
assigning with creation
expression 158
assigning with runtime
expression 157
fields effect on 175
working with 175
pow function 215
precedence of operators 68
precision of float display 261
predefined variables 57
frame 57
time 57
primaryVisibility 201
Index
R
radians 29, 127
angle between two
vectors 229
converting to degrees 234
radius 200
radius0 200
radius1 200
radiusPP 200
rand function 140, 243
rand functions 123
random lifespan of particles 165
random number functions 123,
239
random numbers
making return values
consistent 124
redundant expressions 130
relational operators 65
reloading expressions 106
removing an attribute 131
renaming an object 136
render type
numeric 190
rewinding
effect on creation
expressions 149
unexpected values 141
RGB conversion to HSV 235
rgb_to_hsv function 235
rgbPP 201
rgbPP attribute
example use of 179
rotate function 232
272
rotating
object around its axis 28
points position 232
rounding errors
from converting radians to
degrees 208
rounding numbers 210
rules of syntax 73
runtime expressions 148, 153
assigning rgbPP in 181
how often execution
occurs 148, 152
S
saving an expression 107
saving attribute values for initial
state 158, 188
Scalar option for per object
attributes 170
scale
multiplying by percentage 41
slowing increase of 21, 26
Script Editor
error display 96
scripting with MEL 45
scripts directory 139
seed function 246
making consistent random
values 125
selectedOnly 201
Selection list 103, 104
semicolon terminator 18, 48, 73
Set for All Dynamic 162
Set For Current 150
Set for Current 158, 162, 188
shaded spheres
how rendered in
examples 154
Index
U
unexpected values
after incrementing 142
after rewinding 141
in mixed data type
division 146
of attributes 141, 143
V
variables 56
as expression element 48
assigning to vector 61
data type of 57
declaring 59
defining 26
displaying contents 123
predefined 57
unexpected values 143
vector functions 229
vectors 57
assigning to component of
array attribute 194
assigning to variable 193
component operator 194
data type 52
definition 52
dot product 231
format in print function
output 262
formula for magnitude 67,
231
magnitude of 2D 228
random vectors with
sphrand 244
velocity 202
273
Index
text editor
changing operation
settings 110
quitting 107
selecting 107
selecting default startup 110
using on expression 106
using unlisted 109
valid options 109
threshold 202
time
changing 152
default use of seconds 33
definition 57
dividing by 27
multiplying by 27
negative value of 59
predefined variable 19
relationship to frame 59
value at different frames 19
Time Slider
setting start and end range 16
timesteps 156
transform nodes
not used for particle
expressions 151
trigonometric functions 216
trunc function 213
truncating
insignificant numbers 213,
261
tutorials
for expressions 15
Index
velocity attribute
assigning with creation
expression 150
assigning with runtime
expression 153, 154
fields effect on 175
working with 175
vi text editor 107
vim text editor 107
visibleInReflections 201
visibleInRefractions 201
W
while loop 77
white space in expressions 74
WINEDITOR setting 109, 110
X
xemacs text editor 107
274