ThreeJS Keyframe Track

A KeyframeTrack is a timed series of keyframes that are made up of lists of times and related values and are used to animate an object's unique property.

The "Animation System" page in the "Next Steps" part of the handbook provides an overview of the various elements of the three.js animation system.

Unlike the JSON model format's animation hierarchy, a KeyframeTrack does not save its single keyframes as objects in a "keys" array (holding the times and the values for each frame together in one place).

Instead, a KeyframeTrack always has two arrays: the times array maintains the time values for all keyframes in this track in sequential order, and the values array includes the animated property's corresponding changing values.

A single value associated with a certain point in time can be anything from a basic number to a vector (if a location is animated) or a quaternion (if a rotation is animated). As a result, the values array (which is also a flat array) could be three or four times the size of the times array.

There are multiple subclasses of KeyframeTrack that correspond to the various sorts of animated values and inherit the most attributes and methods:

• BooleanKeyframeTrack
• ColorKeyframeTrack
• NumberKeyframeTrack
• QuaternionKeyframeTrack
• StringKeyframeTrack
• VectorKeyframeTrack

The AnimationClipCreator file contains some examples of how to manually build AnimationClips with various types of KeyframeTracks.

All values in between must be interpolated because explicit values are only stated for the discrete points of time stored in the times array.

The name of the track is significant because it connects this track to a specific property of the animated node (done by PropertyBinding).

Constructor

KeyframeTrack( name : String, times : Array, values : Array, interpolation : Constant )

name - the identifier for the KeyframeTrack.

times - an array of keyframe times, converted internally to a Float32Array.

values - an array with the values related to the times array, converted internally to a Float32Array.

interpolation - the type of interpolation to use.

Properties

.name : String

The name of the track could refer to morph targets, bones, or other data within an animated object. See PropertyBinding for further information. For the types of strings that can be parsed for property binding, see parseTrackName:

The name can either give the node's name or its uuid (although it needs to be in the subtree of the scene graph node passed into the mixer). Alternatively, if the track name begins with a dot, the track applies to the mixer's root node.

A property is usually supplied straight after the node. If you only wish to drive the X component of the rotation via a float track, you can specify a subproperty, such as.rotation[x].

You can also use an object name to describe bones or multimaterials, such as.bones[R hand]. scale; for another example,.materials[3].diffuse[r] can be used to access the red channel of the diffuse colour of the fourth material in a materials array.

.morphTargetInfluences[run] is an example of a morph target name that PropertyBinding will resolve.

It's worth noting that the track's name doesn't have to be unique. The same property can be driven by multiple tracks. The end result should be a weighted blend of the different tracks based on the weights of their individual actions.

.times : Float32Array

A Float32Array, converted from the times array which is passed in the constructor.

.values : Float32Array

A Float32Array, converted from the values array which is passed in the constructor.

.DefaultInterpolation : Constant

The default interpolation type: InterpolateLinear.

.Time BufferType : Constant

Float32Array, the type of the buffer internally used for the times.

.ValueBufferType : Constant

Float32Array, the type of the buffer internally used for the values.

Methods

.clone () : KeyframeTrack

Returns a copy of this track.

.createInterpolant () : Interpolant

Depending on the value of the interpolation argument supplied in the function Object() { [native code] }, creates a LinearInterpolant, CubicInterpolant, or DiscreteInterpolant.

.getInterpolation () : Interpolant

Returns the interpolation type.

.getValueSize () : Number

Returns the size of each value (that is the length of the values array divided by the length of the times array).

.InterpolantFactoryMethodDiscrete ( result ) : DiscreteInterpolant

From the times and values, a new DiscreteInterpolant is created. The results can be passed in the form of a Float32Array. Otherwise, a new array of the proper size will be automatically constructed.

.InterpolantFactoryMethodLinear ( result ) : LinearInterpolant

From the times and values, a new LinearInterpolant is created. The results can be passed in the form of a Float32Array. Otherwise, a new array of the proper size will be automatically constructed.

.InterpolantFactoryMethodSmooth ( result ) : CubicInterpolant

From the times and values, create a new CubicInterpolant. The results can be passed in the form of a Float32Array. Otherwise, a new array of the proper size will be automatically constructed.

.optimize () : this

Removes equivalent sequential keys, which are common in morph target sequences.

.scale () : this

Scales all keyframe times by a factor.

.setInterpolation ( interpolationType : Constant ) : this

Sets the interpolation type. See Animation Constants for choices.

.shift ( timeOffsetInSeconds : Number ) : this

Moves all keyframes either forward or backward in time.

.trim ( startTimeInSeconds : Number, endTimeInSeconds : Number ) : this

Removes keyframes before startTime and after endTime, without changing any values within the range [startTime, endTime].

.validate () : Boolean

Performs minimal validation on the tracks. Returns true if valid.

If a track is empty, the value size is invalid, an item in the times or values array is not a valid integer, or the items in the times array are out of order, this method logs errors to the console.

Static Methods

.toJSON ( track : KeyframeTrack ) : JSON

Converts the track to JSON.