$Q Super-Quick Recognizer

A modern, strongly-typed, and modular TypeScript implementation of the $Q Super-Quick Recognizer.

This library is a high-performance, multi-stroke gesture recognizer. Unlike the original $1 recognizer, $Q supports gestures made of multiple lines (like "X", "T", or Kanji) and uses a Lookup Table (LUT) for ultra-fast recognition.

Installation

Install the package using your preferred package manager:

# npm
npm install @smartupcorp/qdollar-super-quick-recognizer

# yarn
yarn add @smartupcorp/qdollar-super-quick-recognizer

# pnpm
pnpm add @smartupcorp/qdollar-super-quick-recognizer

Quick Start

1. Recognizing Default Gestures

The recognizer comes with 16 standard multi-stroke gestures (T, N, D, P, X, H, I, exclamation, star, etc.).

import {
  Point,
  QDollarRecognizer,
  DEFAULT_GESTURES,
} from "@smartupcorp/qdollar-super-quick-recognizer";

// Initialize with default multi-stroke gestures
const recognizer = new QDollarRecognizer(DEFAULT_GESTURES);

// Points include an ID to identify which stroke they belong to
const userPoints = [
  new Point(30, 146, 1), new Point(106, 222, 1), // Stroke 1
  new Point(30, 225, 2), new Point(106, 146, 2)  // Stroke 2
];

// Returns a sorted array of Result objects (highest score first)
const results = recognizer.recognize(userPoints);

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

2. Adding Custom Multi-stroke Gestures

const recognizer = new QDollarRecognizer([]);

// Define a custom 2-stroke gesture
const myShape = [
  new Point(10, 10, 1), new Point(100, 10, 1), // Line 1
  new Point(50, 10, 2), new Point(50, 100, 2)  // Line 2
];

recognizer.addGesture("my-custom-shape", myShape);

API Reference

QDollarRecognizer

recognize(points: Point[]): Result[]

Calculates the similarity between the input points and loaded templates. Returns a list of results sorted by score (descending).

addGesture(name: string, points: Point[]): number

Adds a new template to the recognizer.

deleteUserGestures(): number

Resets the templates to the initial set passed during construction.

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 $Q Super-Quick Recognizer originally developed by:

• Radu-Daniel Vatavu, Ph.D. (University Stefan cel Mare of Suceava)
• Lisa Anthony, Ph.D. (University of Florida)
• Jacob O. Wobbrock, Ph.D. (University of Washington)

Vatavu, R.-D., Anthony, L. and Wobbrock, J.O. (2018). $Q: A Super-Quick, Articulation-Invariant $1-Family Recognizer. Proceedings of the ACM Conference on Human Factors in Computing Systems (CHI '18). Montreal, Quebec (April 21-26, 2018). New York: ACM Press, paper no. 531.

Original JavaScript code is distributed under the New BSD License.