keyframes
Keyframe utils for a generic timeline. Imagine the low-level structure of After Effect's keyframes for a single control. The control (such as image position, color, etc) might use a 2-component vector (x, y), a color, or some other tweenable value.
When a keyframe is added, the list is sorted to ensure the time stamps go from low to high.
var keyframes = keyframeskeyframeskeyframes //get the interpolated value at the given time stampvar eased = keyframesvalue timeStamp //get the closest keyframe within given (time) radiusvar closest = keyframes //get the keyframe that matches the given time stampvar match = keyframes //the underlying arrayconsole
This does not make any assumptions about the unit of time. The value
for a keyframe is generally a number or array of numbers, but you could also use a custom interpolation
function (see below) if you want to support color strings or some other data type.
Usage
var keys = require('keyframes')([frames][, sorted])
Creates a new set of keyframes, optionally with some frames to use as default. The frames will then be sorted in order of their time stamp.
It's assumed the list of keyframes is unsorted; but if it already has been, you can pass false
for sorted
and it won't perform another sort.
keys.nearest(timeStamp[, radius])
Gets the nearest keyframe to the specified time stamp. If radius
is not specified, this will return the closest keyframe. If radius
is a number, this only returns the closest result within that distance; otherwise returns null.
If radius is zero, this function behaves the same as keys.get()
.
If it can't find any keyframes, null is returned.
keys.nearestIndex(timeStamp[, radius])
Like nearest()
, but returns an index to the frames
array instead of a keyframe object.
keys.get(timeStamp)
keys.getIndex(timeStamp)
Convenience methods to get the keyframe or index exactly at the given time stamp. Same as keys.nearest(timeStamp, 0)
and keys.nearestIndex(timeStamp, 0)
.
keys.value(timeStamp[, interpolator][, out])
Determines the value at the given time stamp, based on keyframe interpolation.
If the time stamp falls on a keyframe, the value of that keyframe will be returned. If the time stamp falls between two keyframes, we use linear interpolation between the two. The result is clamped to the first and last keyframes; so if your first keyframe is at 2.5
and you're querying the value at 0.0
, the returned value will be of the keyframe at 2.5
.
Here, out
will get passed to the interpolator function. The default interpolator function is lerp-array – this allows you to re-use arrays instead of creating new ones per frame.
You can also pass your own interpolator
function for custom features and easings. This will get called with (startFrame, endFrame, t, out)
, which you can operate to return a value. This may be useful if your values are, for example, color strings and need a custom easing.
Example:
var expoOut = var lerpArray = var keys = time: 0 value: 0 0 time: 1 value: 10 5 // get interpolated value at time stamp 0.5 var result = timelinevalue05//=> [ 5, 2.5 ] // get the value with custom interpolationvar result2 = timelinevalue05 { t = // remap time return }
keys.next(timeStamp)
keys.previous(timeStamp)
This is useful for jumping left and right in a timeline editor. From the given time stamp, it will return the next keyframe to the left or right. If none exist (i.e. we are at the bounds already) then null will be returned.
keys.add(frame)
Adds a "keyframe" object (which has time
and value
properties). When a new frame is added, the list is re-sorted. For bulk adds, you may want to access the frames
object directly.
keys.splice(index, howmany, item1, ..., itemX)
Similar to Array.splice
, this allows you to remove or insert keyframes within the array. If new keyframes have been inserted, the list will be re-sorted.
keys.sort()
To be called when you manually change the underlying frames
structure (i.e. after a bulk add).
keys.clear()
Clears the list of keyframes.
keys.frames
The underlying array that holds keyframes.
keys.count
A getter for keys.frames.length
.
keys.interpolation(time)
This is a more advanced method that returns the start and end indices and interpolation factor for a time stamp. The return value is an array with the following format:
startFrameIndex endFrameIndex interpolationFactor
If we are sitting on a keyframe, then start and end indices will be equal. If we have no keyframes, both indices will be -1.
The returned array is re-used to reduce GC load. You should not store reference to it since it will change with subsequent calls.
This is useful for tools that wish to separate the easing function (i.e. remap the value of t using eases) from a user-defined interpolator (i.e. interpolating objects with {x, y}
properties).
License
MIT, see LICENSE.md for details.