/onedollar-unistroke-coffee

Implementation of the $1 Unistroke Recognizer, a two-dimensional template based gesture recognition, in CoffeeScript.

Primary LanguageCoffeeScriptMIT LicenseMIT

OneDollar.js

Build Status npm package GitHub license

Implementation of the $1 Unistroke Recognizer, a two-dimensional template based gesture recognition, in CoffeeScript.

Table of Contents

About

The $1 Gesture Recognizer is a research project by Wobbrock, Wilson and Li of the University of Washington and Microsoft Research. It describes a simple algorithm for accurate and fast recognition of drawn gestures.

Gestures can be recognised at any position, scale, and under any rotation. The system requires little training, achieving a 97% recognition rate with only one template for each gesture.

Wobbrock, J.O., Wilson, A.D. and Li, Y. (2007). Gestures without libraries, toolkits or training: A $1 recognizer for user interface prototypes. Proceedings of the ACM Symposium on User Interface Software and Technology (UIST '07). Newport, Rhode Island (October 7-10, 2007). New York: ACM Press, pp. 159-168.

Usage

Vanilla JS

var one = new OneDollar();

one.add('circle', [[50,60], [70,80], /* ... */ [90,10], [20,30]]);
one.add('triangle', [[10,20], [30,40], /* ... */ [50,60], [70,80]]);

one.on('circle triangle', function(result){
  console.log('do this');
});

// OR:
// one.on('*', function(result){
//   console.log('do that');
// });

// OR:
// one.on(function(result){
//   console.log('do that');
// });

one.check([[50,60], [70,80], /* ... */ [90,10], [20,30]]);

// OR:
// one.start(1, [50,60]);
// one.update(1, [70,80]);
// /* ... */
// one.update(1, [90,10]);
// one.end(1, [20,30]);

// OR:
// one.start([50,60]);
// one.update([70,80]);
// /* ... */
// one.update([90,10]);
// one.end([20,30]);

jQuery

$('#js-sketch').onedollar({
//  options: {
//    'score': 80,
//    'parts': 64,
//    'step': 2,
//    'angle': 45,
//    'size': 250
//  },
  templates: {
    'circle': [[50,60], [70,80], /* ... */ [90,10], [20,30]],
    'triangle': [[10,20], [30,40], /* ... */ [50,60], [70,80]]
  },
  on: [
    ['circle triangle', function(results) {
      console.log(results);
    }]
  ]
});

Download

Variant File Size Gzipped
onedollar.js 10.4 kB 2.62 kB
onedollar.min.js 3.89 kB 1.63 kB
jquery.onedollar.js 2.84 kB 884 B
jquery.onedollar.min.js 1.18 kB 588 B

Note: For older versions have a look at the releases.

Installation

Option 1: Download the files manually or clone the repository.

Option 2: The library is available through Bower:

bower install --save onedollar

Option 3: The library is available through NPM:

npm install --save onedollar.js

API

Method Arguments Return Description
add name : String, path : Array this : OneDollar Add a new template
one.add('circle', [[50,60], /* ... */ [20,30]]);
remove name : String this : OneDollar Remove added template
one.remove('circle');`
on name(s) : String, callback : Function this : OneDollar Bind callbacks
one.on('circle', function(results) { /* ... */ });
off name : String this : OneDollar Unbind callback
one.off('circle');
check path : Array results : Object Check the path
var results = one.check([[50,60], /* ... */ [20,30]]);
start [index : Integer], point : Array[2] this : OneDollar Start a new candidate
one.start([50,60]); one.start(1, [50,60]);
update [index : Integer], point : Array[2] this : OneDollar Update a started candidate
one.update([50,60]); one.update(1, [50,60]);
end [index : Integer], point : Array[2] results : Object End a started candidate
var results = one.end([50,60]); var results = one.end(1, [50,60]);

Example:

var one = new OneDollar();
one.add('circle', [[50,60], [70,80], /* ... */ [90,10], [20,30]]);
// ...

Options

Note: All options are optional. For further details read the official paper.

Name Type Default Description Required
options.score Number (0-100) 80 The similarity threshold to apply the callback(s) No
options.parts Number 64 The number of resampling points No
options.step Number 2 The degree of one single rotation step No
options.angle Number 45 The last degree of rotation No
options.size Number 250 The width and height of the scaling bounding box No

Example:

var options = {
  'score': 80,
  'parts': 64,
  'step': 2,
  'angle': 45,
  'size': 250
};
var one = new OneDollar(options);

Results

Note: Each check and end method will return a result set.

Name Type Description
results.recognized Boolean Is a template recognized?
results.score Number The score value of the best matched template
results.name String The name of the best matched template
results.path Object ↓
results.path.start Array[2] The start point of the candidate
results.path.end Array[2] The end point of the candidate
results.path.centroid Array[2] The centroid of the candidate
results.ranking Array A sorted ranking of matched templates

Example:

var results = one.check([[50,60], [70,80], /* ... */ [90,10], [20,30]]);
console.log(results);
// {
//   recognized: true,
//   score: 84.27,
//   name: "circle",
//   path: {
//   	start: Array[2],
//   	end: Array[2],
//   	centroid: Array[2]
//   },
//   ranking: Array
// }

Examples

Questions?

Don't be shy and feel free to contact me via mail or Twitter.

License

The library is Open Source Software released under the license. It's developed by Darius Morawiec.