$1 Unistroke Recognizer

A modern, strongly-typed, and modular TypeScript implementation of the famous $1 Unistroke Recognizer algorithm.

This library allows you to easily recognize drawn shapes and gestures (such as circles, rectangles, arrows, etc.) based on 2D coordinates. It is extremely lightweight, requires no machine learning models, and works perfectly in the browser.

Installation

Install the package using your preferred package manager:

# npm
npm install @smartupcorp/onedollar-unistroke-recognizer

# yarn
yarn add @smartupcorp/onedollar-unistroke-recognizer

# pnpm
pnpm add @smartupcorp/onedollar-unistroke-recognizer

Quick Start

1. Recognizing Default Gestures

By default, the recognizer can load 16 standard gestures (triangle, x, rectangle, circle, check, caret, zig-zag, arrow, left/right square brackets, v, delete, left/right curly braces, star, pigtail).

import {
  Point,
  DollarRecognizer,
  DEFAULT_GESTURES,
} from "@smartupcorp/onedollar-unistroke-recognizer";

// Initialize with all default gestures
const recognizer = new DollarRecognizer(DEFAULT_GESTURES);

// Assume `userPoints` is an array of Point objects captured from pointer events
const userPoints = [new Point(10, 10), new Point(12, 15) /* ... */];

// Recognize the gesture (second argument is `useProtractor` for faster/accurate matching)
// Returns a sorted array of Result objects (highest score first)
const results = recognizer.recognize(userPoints, true);

if (results.length > 0) {
  const bestMatch = results[0];
  console.log(
    `Recognized as: ${bestMatch.name} (Score: ${Math.round(bestMatch.score * 100)}%)`,
  );

  // You can also check the second-best match
  if (results[1]) {
    console.log(`Second guess: ${results[1].name}`);
  }
}

2. Loading Specific Gestures Only (Recommended)

If your application only needs to recognize a specific shape (e.g., only a "circle"), you can pass it directly to the constructor. This prevents false positives from other shapes and improves performance.

import { Point, DollarRecognizer, CIRCLE_GESTURE } from '@smartupcorp/onedollar-unistroke-recognizer';

// Initialize with ONLY the circle gesture
const recognizer = new DollarRecognizer([CIRCLE_GESTURE]);

const results = recognizer.recognize(userPoints, true);

// Check if the best match meets your score threshold (e.g., 80%)
if (results.length > 0 && results[0].name === "circle" && results[0].score >= 0.8) {
    console.log("A circle was drawn!");
} else {
    console.log("Not a circle.");
}

3. Adding Custom Gestures

You can dynamically teach the recognizer new gestures created by users.

// Clear existing gestures and start fresh
const recognizer = new DollarRecognizer([]);

// Add a custom gesture (requires an array of Points representing the new shape)
recognizer.addGesture("my-custom-shape", userDrawnPoints);

License

This project is licensed under the New BSD License - see the LICENSE file for details.

Acknowledgements

The core algorithm is a TypeScript port of the $1 Unistroke Recognizer originally developed by:

• Jacob O. Wobbrock, Ph.D. (University of Washington)
• Andrew D. Wilson, Ph.D. (Microsoft Research)
• Yang Li, Ph.D. (University of Washington)

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.

The Protractor enhancement was separately published by Yang Li: Li, Y. (2010). Protractor: A fast and accurate gesture recognizer. Proceedings of the ACM Conference on Human Factors in Computing Systems (CHI '10). Atlanta, Georgia (April 10-15, 2010). New York: ACM Press, pp. 2169-2172.

Original C#/JavaScript code is distributed under the New BSD License.