CONTENTS

Introduction

When to Use Expressions

What Is an Expression?

Adding Expressions

The Pick Whip

Vectors and Dimensions

Ranges of Values

Interpolation Methods

Objects

Global Objects

The Default Object

Methods and Attributes

Vector Math

an example

OTHER MATERIAL

Geometry

Tables

Project Index

HOME

Vectors, Arrays, Dimensions & Indexing

You’ll notice that sometimes the whip creates expressions that seem to repeat themselves. For instance, if you drag the whip from position to rotation, you’ll get:

This happens because position uses two values–x and y coordinates–while rotation returns only one. Rather than cause an error, the whip simply applies the rotation values twice, once each for the x and y position values.

A package of two or more values is called a vector or an array. Many of After Effects’ parameters are vectors, including position, anchor point, and scale.

A single value is usually just called a number, though you could be fancy and call it a scalar.

Vector vs Array

What's the difference between a vector and an array? You may notice that the AE documentation seems to use the terms interchangeably. Simply put, a vector is an array of numbers.

An array is just a set of individual bits of data. Arrays can contain pretty much anything you'd like. You could create an array of objects, an array of words, or an array that held a mix:

I'm not sure what you'd do with an array like ralph, but it's certainly a legal array. I think you're most likely to encounter arrays of numbers (aka vectors) in After Effects, because other types of arrays simply are less useful.

So, in these pages, I'll use the word 'array' when I'm talking about the general concept or operations applicable to any kind of array. I'll use 'vector' when talking specifically about arrays of numbers.

Indexing

If you have an array, you can extract just one of its values by following the array name with a number in brackets indicating which of the values you want, e.g.

This process is called indexing. Note that when indexing into an array, you start counting at zero. That is, the first value in an array is selected by ‘[0]’, the second is selected by ‘[1]’, and so on.

The example above will return the first value in the position vector — the x-coordinate — while ‘Position[1]’ would return the second value (the y-coordinate).

This can be confusing, because everything else in After Effects starts counting at 1. It’s important to remember that indexing into arrays always starts counting at zero.

Creating Arrays

You can pack several values into an array simply by listing them in brackets, separated by commas:

would create a new variable named my_vector, and put in it the three values 10, 20, and 30.

would return 20, the second value in ‘my_vector’ (remember that indexing into arrays starts counting at zero).

Dimensions

The number of values in an array is called its dimension. For instance, ‘my_vector’ as listed above has a dimension of 3. Position has a dimension of 2 (or 3, for 3D layers). Properties which take scalar values, such as rotation and opacity, have a dimension of 1. (A number or scalar really is a 1-dimensional vector.)

Note that multi-dimensional attributes such as position, and variables you’ve defined to contain arrays, don’t need to have their names written in brackets–After Effects already knows they are arrays. You only need to do use brackets when putting together the array's contents – the array name doesn’t need to be bracketed.

Modifying One Component of an Array

Note that you actually could write the position attribute as:

This pulls out the first and second values from position, and then packs them into an array. The result is almost identical to just writing ‘position’. The advantage is that you could use constructions like this to modify just one component of an array, leaving the others unchanged. For instance:

would return an array whose first value was the anchor point’s current x-value, and whose second value was zero. If applied to the anchor point parameter, this would leave the anchor point’s horizontal position as it was, but move it vertically to the top of the layer (y=0).

Be careful when using constructions like this, however, because you may need to rewrite them if you make your layer 3D, to account for the additional z-axis value in parameters such as position and anchor_point.

For instance, if you used the anchor_point example above with a 3D layer, After Effects would simply fill in 'zero' for the missing third dimension. This is better than generating an error, but still may not be what you'd really want, because it would ignore any changes to the anchor point's z position.

As another example, suppose you used the following expression to copy one layer's position to another layer, with a 100 pixel offset along the y-axis:

If you then made the layers 3D, and moved the 'leader' along its z-axis, you'd find that the 'follower' (the layer with the expression) wouldn't really follow. It would ignore any changes to the z-axis, because your hand-rolled vector only contained the first two dimensions.

Why Are Arrays Important?

Why are we making such a big deal about arrays? Because your expressions must supply results of the proper dimension. You cannot, for instance, supply only one value for position:

This doesn’t make any sense, as there is no ‘position 6’. You need (at least) two values for position:

(Remember, by the way, that you would never actually write "position=", because the assignment is assumed by the fact that the expression is applied to the position parameter.)

If your results have the wrong dimension, After Effects will generate an error and disable the expression. In my experience, this is among the most common errors when writing expressions.

To avoid this problem, you should always start out by looking up the dimension expected by your parameter, either in the After Effects documentation or in the tables I’ve put together here. This is the dimension your expression will need to produce.

Similarly, whenever you reference another parameter in your expression, look up its dimension in these tables or the documentation. You’ll need to adjust the values coming from these parameters to match your needed output dimension. If you have two dimensions coming in, and can output only one, you'll need to somehow reconcile the dimension mismatch (e.g. by ignoring one component of your incoming data).

The following table lists the dimensions for many of After Effects’ most common parameters, as well as the range of values they typically accept.

Remember that the pick whip will automatically correct dimension mismatches, by indexing into vectors or by repeating scalars, as necessary.