As we discussed in the last section, an animation in Johnny-Five is created and then you enqueue segments that run first-in, first-out. We're going to go from the inside out in our exploration of creating an animation: first, we'll learn about writing keyframes, then segments, and finally we'll explore the Animation object.
Writing keyframes are at the core of the Animation API—the power of this API is its ability to tween between our keyframes. Each keyframe is an object, and you'll pass your keyframes into your segment via an array. Remember: you'll want to write a keyframe for each of your cue points.
As each keyframe is an object, we have access to a few properties that we can establish for each one:
There are several easing functions available via Johnny-Five's use of the ease-component module; a very popular one is inOutCirc, which causes the frames to move slowly at first, quickly increasing in the middle, and slowing down again towards the end. See the Johnny-Five and ease-component docs for more examples of easing functions.
You can also define keyframes without using objects; if you pass your keyframes as an array of integer values, each integer value will be interpreted as a step value. Consider the following array:
keyFrames: [0, 90, -45, 90, -90]
This will (assuming a 0 start point) move the servo to 0, 90, 45, 135, and 45 degrees for each cue point.
You can also use non-integer values in shorthand syntax to mean specialized values:
So, in closing, you can use either a keyframe object, a number, null, or false to represent a keyframe in a segment definition. Now that we've explored the attributes available on a keyframe object, let's write some keyframes to match certain situations.
Let's explore some examples of keyframes:
Example 1: Write a set of keyframes that starts a servo at the last position it was at, moves to it by 90 degrees with an inOutCirc easing, then moves it by 45 degrees back with no easing:
- The first keyframe can be handled using the
nullvalue:var myFrames = [null];
- The second requires a keyframe object because we want to establish an
easingfunction:var myFrames = [null, { degrees: 90, easing: 'inOutCirc' }]; - The last could be done with a keyframe object:
var myFrames = [null, { degrees: 90, easing: 'inOutCirc' }, { step: -45 }];
However, we can also use shorthand—remember that passing a number as a keyframe will lead to using that number as a step value:
var myFrames = [null, {degrees: 90, easing: 'inOutCirc' }, -45];Among the preceding alternatives, which one you use is entirely up to your own preference.
Example 2: Write a set of keyframes that starts the servo at 0, moves to 90, spends two cue points moving to 180, and then moves to 135:
- The first and second keyframes can be set via a keyframe object, as follows:
var myFrames = [{degrees: 0}, {degrees: 90}]; - Otherwise for the second keyframe, we can use a shorthand, as shown here:
var myFrames = [{degrees: 0}, 90];
As we know that the first keyframe will set the servo to 0, we can use step instead of degrees. For the next step, we want the servo to take two cue points to move to 180. We could calculate how to do this with standard keyframes, or we could use a shorthand null to tell the segment to skip that cue point and tween between 90 and 180 over two cue points:
var myFrames = [{degrees: 0}, 90, null, {degrees: 180}]Now that you've learned how to write keyframe arrays and objects, let's take a look at writing the rest of our Animation object.
We know that segments consist of an array of keyframes, an array of cue points, a duration, and some options. Let's take a look at the options available to us in each segment, and then build some segments to get us ready for our next project.
The segment options and their properties are as follows:
More often than not, you'll be animating more than one servo at a time. How do you handle keyframes for more than one servo? By passing an array of arrays; each array represents the keyframes for a servo in the target servo array. For instance, the following segment contains the keyframes for two servos in an array:
var myMultiServoSegment = {
duration: 2000,
cuePoints: [0, .5, 1],
keyFrames: [
[{degrees: 135}, -45, -45]
[{degrees: 45], 45, 45]
]
}Let's walk through a couple of examples of writing segments.
Example 1: Write a sweeping segment that goes from 0 to 180 and back. Give it the inOutCirc easing and make it loop. The duration should be 5 seconds, with as few keyframes as possible.
Now, we could write our keyframes to go from 0 to 180 and back, or we could use the metronomic option to help us out. Using the metronomic function also means that we only need two keyframes and cue points—0 and 1! We'll also need the easing option and the loop option. Here's the result of this example:
var sweepingSegment = {
duration: 5000,
metronomic: true,
loop: true,
easing: 'inOutCirc',
cuePoints: [0, 1],
keyFrames: [{degrees: 0}, {degrees: 180}]
}
Example 2: Write a segment that runs once. This segment contains instructions for two servos. Servo one starts at whatever position the servo is already at, then adds 45 degrees over 1 second, then removes 30 degrees over 2 seconds, and finally adds 15 degrees over 1 second. The second servo simply moves from 20 degrees to 120 degrees over the duration, with full tweening and the inOutCirc easing. The duration of the segment should be 4 seconds.
We're using relative positions here, so it looks like the keyframes shorthand will come in handy. We have to set unequal cue points at: 0/4, 1/4, 3/4, and 4/4, that is at .25, .75, and 1. Remember— in a keyframe shorthand, null at the beginning means use the current position of the servo, and null in the middle means skip the cue point and recalculate tweening!
Keeping all of this in mind, we get the following:
var mySegment = {
duration: 4000,
cuePoints: [0, .25, .75, 1] ,
keyFrames: [
[null, 45, -30, 15],
[{degrees: 20}, null, null, {degrees: 120}]
]
}This is the true power of the Animation API—we can describe complex movements in objects that mathematically work out.
Now that we know how to write keyframes and segments, let's take a look at writing Animation objects and running segments using them.
The analogy that I like to use for the Animation object is to think of it like an MP3 player. You load tracks into it, and you can press play, pause, or stop. You queue segments into an animation in any order, and you can play, pause, or stop the animation at any time.
Let's take a quick look at the constructor: it only takes one parameter, which is the target. As we mentioned earlier, the target is the servo or an array of servos being animated. So, let's take a look at a sample program that constructs a servo array and constructs an Animation object:
var five = require('johnny-five')
var board = new five.Board()
board.on('ready', function(){
var servos = new five.Servos([3, 5, 6])
var animation = new five.Animation(servos)
})Once we've constructed the Animation object, the next important function is .enqueue(). You pass a segment to this function to add it to the animation queue. Animations are run first-in, first-out, so our code becomes this:
var five = require('johnny-five')
var board = new five.Board()
board.on('ready', function(){
var servos = new five.Servos([3, 5, 6])
var animation = new five.Animation(servos)
var mySegment = {
easing: 'inOutCirc',
duration: 3000,
cuePoints: [0, .25, .75, 1]
keyframes: [{degrees: 45}, 45, 45, -45]
}
animation.enqueue(mySegment)
})That's the whole kit and caboodle; animations are set to run as soon as a segment is enqued! Let's take an in-depth look at the functions available to the Animation object:
Now that we know how animations work in general, let's build our own project with our three servos. Let's animate!
You should still have your servo array from the last project. Let's animate it! We'll use the REPL to modify our animation segment in real time and play with some of the true power of the Animation API.
Let's start with the code that initializes our board, sets up our servo array, creates an animation and a segment, and inserts them into the REPL. Place the following into animation-project.js:
var five = require('johnny-five')
var board = new five.Board()
board.on('ready', function(){
var servos = new five.Servos([3, 5, 6])
var animation = new five.Animation(servos)
var mySegment = {
easing: 'inOutCirc',
duration: 3000,
cuePoints: [0, .25, .75, 1],
keyFrames: [
[{degrees: 45}, 45, 45, -45],
[{degrees: 30}, 30, 30, 30],
[{degrees: 20}, 40, 40, 40]
]
}
this.repl.inject({
animation,
mySegment
})
animation.enqueue(mySegment)
})Go ahead and run this with the following:
node animation-project.js
Your servos should spring to life and should start running the segment (we queued it on the last line!). Once it's done running, let's see it again on a loop. In the REPL, type the following:
>mySegment.loop = true >animation.enqueue(mySegment)
The segment should start running on a loop. Want to see it slower? Let's change the speed using the Animation object's speed() function:
>animation.speed(.5)
This should slow it down to half speed. Let's go ahead and stop the animation, clearing the queue:
>animation.stop()
Let's see what happens when we make our segment metronomic using an easing function, and then run it:
>mySegment.easing = 'inOutCirc' >mySegment.metronomic = true >animation.enqueue(mySegment)
The segment now loops forward and reverses and looks more fluid!
This is cool, but what if we want animations to run one after the other? We could use a series of durations and timers, or we could tap into Johnny-Five's event system, which extends through the Animation API. Next we'll explore how to tap into these events to create timed animations.