KeyframeTrack

A KeyframeTrack is a timed sequence of keyframes, which are composed of lists of times and related values, and which are used to animate a specific property of an object.

For an overview of the different elements of the Verge3D animation system see the "Animation System" article in the "Next Steps" section of the manual.

In contrast to the animation hierarchy of the JSON model format a KeyframeTrack doesn't store its single keyframes as objects in a "keys" array (holding the times and the values for each frame together in one place).

Instead of this there are always two arrays in a KeyframeTrack: the times array stores the time values for all keyframes of this track in sequential order, and the values array contains the corresponding changing values of the animated property.

A single value, belonging to a certain point of time, can not only be a simple number, but (for example) a vector (if a position is animated) or a quaternion (if a rotation is animated). For this reason the values array (which is a flat array, too) might be three or four times as long as the times array.

Corresponding to the different possible types of animated values there are several subclasses of KeyframeTrack, inheriting the most properties and methods:

Some examples of how to manually create AnimationClips with different sorts of KeyframeTracks can be found in the https://www.soft8soft.com/verge3d/examples/js/AnimationClipCreator.js file.

Since explicit values are only specified for the discrete points of time stored in the times array, all values in between have to be interpolated.

The track's name is important for the connection of this track with 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. See Animation Constants for possible values. Default is InterpolateLinear.

Properties

.name : String

The track's name can refer to morph targets or bones or possibly other values within an animated object. See PropertyBinding.parseTrackName for the forms of strings that can be parsed for property binding:

The name can specify the node either using its name or its uuid (although it needs to be in the subtree of the scene graph node passed into the mixer). Or, if the track name starts with a dot, the track applies to the root node that was passed into the mixer.

Usually after the node a property will be specified directly. But you can also specify a subproperty, such as .rotation[x], if you just want to drive the X component of the rotation via a float track.

You can also specify bones or multimaterials by using an object name, for example: .bones[R_hand].scale; the red channel of the diffuse color of the fourth material in a materials array - as a further example - can be accessed with .materials[3].diffuse[r].

PropertyBinding will also resolve morph target names, for example: .morphTargetInfluences[run].

Note: The track's name does not necessarily have to be unique. Multiple tracks can drive the same property. The result should be based on a weighted blend between the multiple tracks according to the weights of their respective 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.

.TimeBufferType : 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

.createInterpolant () : null

Creates a LinearInterpolant, CubicInterpolant or DiscreteInterpolant, depending on the value of the interpolation parameter passed in the constructor.

.getInterpolation () : null

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

Creates a new DiscreteInterpolant from the times and values. A Float32Array can be passed which will receive the results. Otherwise a new array with the appropriate size will be created automatically.

.InterpolantFactoryMethodLinear (result) : null

Creates a new LinearInterpolant from the times and values. A Float32Array can be passed which will receive the results. Otherwise a new array with the appropriate size will be created automatically.

.InterpolantFactoryMethodSmooth (result) : null

Create a new CubicInterpolant from the times and values. A Float32Array can be passed which will receive the results. Otherwise a new array with the appropriate size will be created automatically.

.optimize () : this

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

.scale () : this

Scales all keyframe times by a factor.

Note: This is useful, for example, for conversions to a certain rate of frames per seconds (as it is done internally by animationClip.CreateFromMorphTargetSequence).

.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.

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

Static Methods

.parse (json : JSON) : KeyframeTrack

Parses a JSON object and returns a new keyframe track of the correct type.

.toJSON (track : KeyframeTrack) : JSON

Converts the track to JSON.

Source

For more info on how to obtain the source code of this module see this page.