Managing Keyframes

The main idea of MAXScript’s access to controllers is to manage keyframes. You can adjust keys, change their values, move them in time, and add and delete them.

To access keys, simply use the .keys property, calling it in object.parameter.keys or object.parameter.controller.keys. These return an array of keys. Like any array, you can access its elements using [index], and you can know how many keys exist using .count. Let’s look at a small example to see how it works:

 obj = sphere()
 animate on (
 at time 40 obj.radius = 50
 at time 60 obj.radius = 25
 )
 k1 = obj.radius.keys[1]

There are two new commands here. ANIMATE ON affects actions the same as if the Animate button was turned on. In addition, AT TIME changes the selected values at the specified time.

This code also assigns the first key to the variable k1. You can now adjust several parameters in this key using this variable. First, you can adjust any key value with the .value property. To change it to 30, in our example, you’d type k1.value = 30. To move this key to frame 10, use the .time property as in k1.time = 10.

	TIP Select the object in the viewport and observe the Track Bar. All changes made to the keyframes and to the animation will appear instantaneously.

Some controllers allow many more options for a key. Bezier controllers allow us to adjust the tangent type of a key and change it to linear, smooth, etc. This is done using .intangenttype and .outtangenttype. You can specify the following tangent types: #smooth, #linear, #slow, #fast, #step, and #custom.

Using Functions to Manipulate Keys

Several functions can be used to manipulate keys. These functions add, remove, select, and move them. You can create keys with ADDNEWKEY <controller> <time>. This command adds a new key to the specified time, with the value found at that time. Using the previous example, you can add a keyframe at frame 30 using addnewkey obj.radius.controller 30.

Notice that this addition changes the number of keys, which means the index of the keys will also change. obj.radius.keys[2] is now the keyframe you just created at frame 30, instead of the key at 40. In addition, its value is automatically assigned by the animation curve, but you can change it at any time using the tools you have already learned.

To select keys, you can use two commands: SELECTKEY and SELECTKEYS. Both commands are additive. SELECTKEY selects a single key and adds it to the previous selection. SELECTKEYS selects keys in a given interval (and adds them to any already selected). In the previous example, selectkeys obj.radius.controller 0 30 will add all keys from frame 0 to 30 (inclusive) to the selection. Selectkey obj.radius .controller 3 will select the third key, adding this key to the previous selection.

If you want to deselect keys, the process is the same as selecting but the equivalent commands are DESELECTKEY and DESELECTKEYS.

To delete keys, you can use two commands: DELETEKEY and DELETEKEYS. The first deletes a specified key, and doesn’t work for multiple keys, which means you need to do it one key at a time. Let’s delete the key at frame 40, which is key #3, using deletekey obj.radius.controller 3. DELETEKEYS works on a selection of keys (deletekeys #selection) or on all keys (deletekeys #all).

To move keys, use MOVEKEYS. If #selection is specified, it moves the selected keys. If not, it moves all keys. Let’s move the key in frame 60 to frame 80 in the previous example:

 deselectkeys obj.radius.controller 0 60
 selectkey obj.radius.controller 3
 movekeys obj.radius.controller 20 #selection

This MOVEKEYS will move the selected keys 20 frames ahead. If you want to move a key back in time, just use a negative number.

Controller Operations

Some of the most important controller features in MAXScript are the time features. They allow us to access the Edit Time options in Track View.

Many time operations can be performed through MAXScript. Some controllers will not support these features, so you need to check to make sure the controller can be accessed by using SUPPORTSTIMEOPERATIONS. If it returns true, you’ll be able to edit the keyframe timing.

You can scale the time in a specified interval of a controller. This works similarly to the Scale Time option in Track View. To do so, you need to use the SCALETIME command. It requires a time interval and a scale float. Let’s look at a simple example of this:

 s = sphere()
 select s
 animate on
 (
 at time 0 s.scale = [1,1,1]
 at time 20 s.scale = [1,1,2]
 at time 50 s.scale = [2,2,1]
 )
 supportstimeoperations s.scale.controller
 scaletime s.scale.controller 0 1s20f 1.5

Notice the keyframes were scaled and moved from 20 to 30 and from 50 to 75.

Another important time operation is REVERSETIME. It allows us to reverse the time, thus making it easier to render an animation backwards. Let’s reverse the time in our previous example:

 reversetime s.scale.controller 0 75 #incleft #incright

This will reverse the animation in the given interval—including the keyframes at the beginning (#incleft) and end (#incright) of the interval.

© 2000, Frol (selection, edition, publication)