/gest.js

gest.js is a webcam based gesture recognition library that helps developers make webpages more immersive

Primary LanguageJavaScriptMIT LicenseMIT

#What is gest.js? Check out this presentation from MelbJS

This is a short presentation I gave at MelbJS that summarises gest.js: http://hadimichael.github.io/gestjs-presentation/

#gest.js IN THE WILD

Are you using gest.js? Please get in touch @hadi_michael

#EXAMPLES

A simple gest.js demo that displays the gesture direction on screen: https://hadi.io/gest.js/demos/simple/index.html

Using gest.js to control Nathan Searles' SlidesJS: https://hadi.io/gest.js/demos/slidesjs/index.html

#USAGE

##Include the library (gest.js) You will need to include the 'gest.js' library using something like:

<script type="text/javascript" src="gest.min.js"></script>

##Start gesture detection You can start gest.js by calling: gest.start();

##Listen for recognised gestures

Method 1 (recommended)

Use the .options.subscribeWithCallback(...) function to listen for gestures:

gest.options.subscribeWithCallback(function(gesture) {
	//handle gesture .direction .up .down .left .right .error
});

This method is recommended because it will automatically handle cross-browser event handling.

Method 2

You can register an event listener on the document for gest using:

document.addEventListener('gest', function(gesture) {
	//handle gesture .direction .up .down .left .right .error
}, false);

##How to handle recognised gestures On every event, you will be passed a gesture object that contains:

  • .direction the recognised gesture in words as a string
  • .up boolean, true if the recognised gesture is up
  • .down boolean, true if the recognised gesture is down
  • .left boolean, true if the recognised gesture is left
  • .right boolean, true if the recognised gesture is right
  • .error an error object with...
    • .code a code as an int
    • .message and a message as a string

##Stop gesture detection You can stop gest.js at any time by calling: gest.stop();

##Using Options

###Sensitivity (80 by default) You can specify the degree of colour change that should be used to determine whether or not a pixel has changed. The specified value should range from 0-100, with 100 implying that the slightest change should be enough. You can specify sensitivity using: gest.options.sensitivity(85);

###Skin Filtering (off by default) To improve recognition in bright lighting conditions, you can enable HSV skin filtering using: gest.options.skinFilter(true);

###Debugging (off by default) In order to view the video stream and enable console.log(…) messages, you will need to toggle debugging using: gest.options.debug(true);

#WHAT'S CHANGED

##v0.5.0 (latest)

  • Firefox support (woohoo!)
  • Error handling, all the way back to the stone-age (IE7)
  • Better event handling
  • Ability for the developer to define sensitivity
  • A new .options.subscribeWithCallback(...) function
  • On screen messages is now DEPRECATED. I decided that this is something that the front-end developer should build - it shouldn't be part of the library. If you really want it back, check demo/simple.
  • Locking is now DEPRECATED. It wasn't an elegant enough solution. It might come back in future releases...

#TODO

  • bespoke.js plugin (this is pretty much done, I just need to package it up)
  • Fine tune skin filtering values
  • Include a ready flag... might do this, not sure yet.
  • Bring back the ready message: "The force is strong with you, go forth and gesture."

#Acknowledgements gest.js is an extension of work started by William Wu https://github.com/willy-vvu.

#LICENSE (MIT)

Copyright (c) 2013, Hadi Michael (http://hadi.io)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.