page 1 2 3 4

The Language of Expressions

Basic Arrays

Arrays are a mathematical concept for storing related data in an orderly fashion. After Effects makes extensive use of JavaScript's implementation of arrays. I wish I didn't have to drag you through this but unfortunately if you want to get anywhere with expressions you're going to have to understand the concept of arrays. However, we'll keep it as simple as possible. The simplist arrays are one-dimensional and you can visualize them as simply a list of data. The next level of complexity is the two-dimensional array, which you can visualize as a grid of data with rows and columns (like a spreadsheet). Arrays can actually have any number of dimensions but it gets hard to visualize them after three dimensions (which would be like a cube of data or a stack of grids). Fortunately, most of the arrays that you will need to deal with in After Effects are one-dimensional.

Getting at the Data

In JavaScript, you get at data in an array by using an "index". Indexing starts at zero, so for a one-dimensional array, an index is simply an integer between 0 and the number of elements in the array minus one. For example, if you had an array that consisted of the numbers 10,11,12 and 13 (four elements total), valid indexes for this array would be 0 through 3. An index of zero would return the result 10 and an index of 3 would return the result 13. An index outside this range would generate an error and After Effects will scold you harshly if you try it. Data in multi-dimensional arrays is accessed with multi-dimensional indexes, but you won't run into that situation very often.

Array Syntax

When you retrieve data from an array in JavaScript you enclose the index in brackets. So the x component of a layer's Position property would be accessed with "position[0]" and the y component would be accessed with "position[1]". It's important to remember that in After Effects an x component is always represented by index 0, the y component is represented by index 1 and (for 3D layers) the z component is represented by index 2. Just to make it more confusing, brackets have another purpose in JavaScript related to arrays. You can use brackets to actually define an array. For example, let's say you wanted to define an array named "myArray" that you want to contain the values 5, 6, 7, and 8. You could do it with a statement like this:


myArray = [5,6,7,8];

So here we're using brackets to define the contents of the array "myArray". We would also use brackets to access the individual elements of the array. For example, myArray[0] would be 5, myArray[1] would be 6, and so on. This dual purposing of the brackets can be a little confusing, but a helpful way to remember this is that when you see brackets not appended to anything (as in "myArray = [5,6,7,8];) they are being used to define an array and the numbers between the brackets are the actual elements of the array. When the brackets are appended to an object or property (as in myArray[0]) they are being used to retrieve a particular element of the array and the number between the brackets is the index.

Let's look a simple example that demonstrates both uses. Let's say you wanted to write an expression that added 10 to a layer's x Position and 25 to the layer's y Position. You could write an expression like this:


newX = position[0] + 10;
newY = position[1] + 25;
[newX,newY]

Let's go through it line by line. In the first line, the index 0 is used to retrieve the x component of the Position property, 10 is added to it, and the result is stored in a variable named "newX". In the second line, the index 1 is used to retrieve the y component of the Position property, 25 is added to it, and the result is stored in a variable named "newY". In the final line, a new two-element array is defined that consists of the elements newX and newY and that array is plugged into the value of the Position property.

Important Point

The above example brings up a very important issue (unrelated to arrays) that we might as well mention here. We've been looking at an expression for a layer's Position property which references the Position property itself. When an expression for a property references that same property, the value it retrieves is the value that would exist if the expression didn't exist. In other words, what we would get in our example would be the initial Position modified by the effect of any Position keyframes, but the value won't include any effects of the expression itself. This trips up a lot of novices that think they should be able to write an expression for Opacity like this:


opacity = opacity + 1;

and have the Opacity increment by 1 at each frame. It doesn't work that way.

Expressions have no memory. Expressions have no way of knowing what they did in the past. (Well, that's not completely true - an expression can "re-create" the past but it's not trivial and can be a render hog). They have no way of storing any information that they can retrieve at future frames. One more time: If your Position expression refers to "position", you get the value that would exist if there were no Position expression.

However, (just to add to the confusion) if you refer to the Position property from within an expression for any other property that expression will have access to the result of the Position expression. Let me say it one more way - the past, present, or future result of an expression is available externally to any other expression but not internally within itself.

Another related point that I need to stress is that an expression has one and only one way to communicate with other expressions. That way is through the value of the parameter that the expression is applied to. In other words, there are no global variables in expressions in After Effects.

We'll look at these issues again later when we look at ways to get around these "limitations".

Array Math

Now we're going to take a quick look at basic array math. Most of the array math that you will need to use in your expressions is pretty simple. First let's look at a simple expression for Position that adds two arrays.


a = [100,150];
b = [200,250];
a + b

The result of this is (as you might have guessed) [300,400]. That is, the two arrays ("a" and "b") have been added together, component by component, with the first element of "a" being added to the first element of "b", and so on. So the result of this operation is that the new Position calculated by the expression is x = 300, y = 400. Just to exercise our newfound knowledge of arrays, and to demonstrate what's going on internally, let's write the last line another way.


a = [100,150];
b = [200,250];
[a[0] + b[0],a[1] + b[1]]

This looks a lot more complicated but it accomplishes the same thing. Here we have manually added the individual components together separately and then built a two-element array for the result. With the first method, we let After Effects do the adding and array building. That's the way you'll want to do it if you can, but there are plenty of situations where you will need to construct the resulting array yourself.

After Effects is pretty forgiving if you try to add two arrays of different lengths. The result will be an array the size of the larger of the two. For example, [1,2,3] + [4,5] will give you [5,7,3]. After Effects has kindly filled in the third element of our [4,5] array with a zero before the addition.

Array subtraction works in a similar way. Can you guess the result of this expression?


a = [500,400];
b = [200,300];
a - b

If you guessed [300,100], you're right. It's getting easier, right? Well, just to confuse you, multiplication and division don't work the same way. After Effects doesn't know how to multiply two arrays together, but it does know how to multiply an array by a number (or "scalar", as we'll call it when we get into vectors). The result is not too surprising. Here's an example:


a = [100,150];
a*10

The result of this would be the array [1000,1500]. After Effects has multiplied each element of the array by 10. Similarly, the result of this division expression:


a = [100,150];
a/10

would be [10,15].

Note that the order of the operands is important for division. After Effects is smart enough to figure out that 10*[100,100] is the same as [100,100]*10, but if you try 10/[100,100] you'll get an error because After Effects doesn't know how to divide a number by an array.

Flashback

If you're unlucky enough not to have upgraded since AE 5.0, you have to do array math in a much more clumsy way. In AE 5.0 you have to use special "vector" operators (we'll talk more about vectors later). For example, a simple expression like this:


a = [100,150];
b = [200,250];
a + b*5

would have to be written like this in AE 5.0:


a = [100,150];
b = [200,250];
sum(a,(mul(b,5))

It gets pretty ugly in a hurry. This old syntax will work in later versions of AE, but would you want to do it that way if you didn't have to? I didn't think so.