February 22, 2011

Windows Phone Shake Gestures Library

Yochay Kiriaty

There are more than a few very successful mobile applications that use the accelerometer as the main user input. Most commonly used in driving or flying simulation games, the accelerometer in mobile devices is a very powerful tool. But there are other applications/games that use the accelerometer. You can imagine applications like magic 8 ball, where you need to shake the phone to get the perfect answer to a very hard question, implementation of a casino-like slot machine, where you need shake the phone to start rolling the dice, or many other similar implementations. The UX aspect is clear, simply shake or move your phone to trigger some functionality.

Windows Phone has very good support for accelerometer, and the API is relatively easy to use. With that said, while the plain vanilla API for using the raw input from the Windows Phone accelerometer is a good way to start, if you want to drive some logic and gestures, like recognizing a shake gesture, you have to work that in yourself.

Well, lucky you; you came across this blog, which means you’ll read about the Windows Phone Shake Gesture Library that uses the accelerometer to detect a “shake gesture” in 3D space (in three different axes – X, Y, and Z).

For now let’s assume a shake gesture is a “continuous motion in 3D space across one (or more) axes that changes its direction several times.” Imagine that you are shaking your phone vertically (Y-axis)—you move the phone up and down several time in one continues gesture. Therefore, when trying to detect a gesture we look for the following:

That the motion is continuous in time; that is, the swings are continuous without major “still” periods during which the phone isn’t shaken
That the swings (moving the phone up and down) are meaningful; that is, powerful enough to register as a shake
That there are several changes in direction during that time; that is, the phone is moving up and down… the same applies if you shake the phone left and right, or back and forth

For example, take a look at the following figure (a visualization of captured accelerometer data).The green line (representing the Z-axis in this case), represents a continuous shake gesture that has clear changes in direction – with 4 different peaks (two positive peaks greater than 1, and two negative peaks smaller than -1). The ShakeGestureLibrary recognizes this as a valid shake gesture and raises the proper events.

You might want to note, that the ShakeGestureLibrary works in real time. You will see the shake event as soon as the library recognizes it. The algorithms we use are simple and don’t require a lot of CPU and memory, therefore the event occurs in real-time.

The rest of this post includes a short explanation on how to use the library. If you are interested in the shake library implementation, you are more than welcome to read all about it at the Windows Phone Shake Gesture Library Recipe page on AppHub, where you can download the library, sample application, and documentation.

Using the Shake Library in Your Application

Once you download the library, you’ll see the ShakeGestures.dll. Then follow these five steps and you are all set:

1. Add reference to shake gestures library: ShakeGestures.dll.

2. Add a using statement to file header: using ShakeGestures;

3. Register to the ShakeGesture event:

// register shake event

ShakeGesturesHelper.Instance.ShakeGesture += new

    EventHandler<ShakeGestureEventArgs>(Instance_ShakeGesture);

// optional, set parameters

ShakeGesturesHelper.Instance.MinimumRequiredMovesForShake = 4;

4. implement the ShakeGesture event handler from step 3:

private void Instance_ShakeGesture(object sender, ShakeGestureEventArgs e)

    _lastUpdateTime.Dispatcher.BeginInvoke(

        () =>

            _lastUpdateTime.Text = DateTime.Now.ToString();

            CurrentShakeType = e.ShakeType;

});

The ShakeGestureEventArgs holds a ShakeType property that identifies the direction of the shake gesture.

5. Finally, activate the shake gesture helper, which binds to the phone’s accelerometer and starts listening to incoming sensor input events.

// start shake detection
ShakeGesturesHelper.Instance.Active = true;

Note: You can continue working directly with the phone’s sensor. The ShakeGesturesHelper class doesn’t block any sensor events—it just listens to them.

Note: The ShakeGesture event arrives on a thread different from the UI thread, so if you want to update the UI from this event you should dispatch your code to run on the UI thread. This can be done by using the method myControl.Dispatcher.BeginInvoke(), where myControl is the control you want to update.

A Few Important Configuration Parameters

During the coding and testing of the library, we found that shake is very individualized. It depends on the nature of the application and the actual shake gesture made by the phone’s user. Therefore, we give you plenty of different properties to tweak and tune for your own purposes. These parameters control various aspects of the gesture detection algorithm. By changing these parameters, you can change your application’s sensitivity to the “force” of shakes and to their duration.

The recipe includes full documentation of all the library parameters; here are just few examples:

ShakeMagnitudeWithoutGravitationThreshold – Any vector with a magnitude (force) bigger than this value is considered a valid shake vector

MinimumShakeVectorsNeededForShake – Determines the number of shake vectors needed in order to recognize a “shake segment”

Note: We don’t use a system timer to measure time. Instead, we depend on the fact that the Windows Phone sensor generates about 50 events per second, so the time between each event is around 20 msec. Therefore, five events total roughly 100 msec. You’ll see in the code that we measure event intervals and not real world clock time.

MinimumRequiredMovesForShake – Determines the number of changes required in a shake segment direction to get a shake signal. You can think of this parameter as how many peaks (positive and negative) you need in order to raise a shake gesture.