@map-gesture-controls/core 0.1.3 → 0.1.5

package/README.md

@@ -0,0 +1,89 @@
+# @map-gesture-controls/core
+
+[![npm version](https://img.shields.io/npm/v/@map-gesture-controls/core?style=flat-square)](https://www.npmjs.com/package/@map-gesture-controls/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/@map-gesture-controls/core?style=flat-square&label=minzipped)](https://bundlephobia.com/package/@map-gesture-controls/core)
+[![TypeScript](https://img.shields.io/badge/TypeScript-typed-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+
+**Turn any web map into a hands-free experience.** This is the map-agnostic gesture detection engine behind [map-gesture-controls](https://github.com/sanderdesnaijer/map-gesture-controls). It uses [MediaPipe](https://developers.google.com/mediapipe) hand-tracking WASM to detect hand gestures from a webcam feed, classify them in real time, and expose a clean event-driven API. All processing runs locally in the browser. No video data ever leaves the device.
+
+> Building with OpenLayers? Use [`@map-gesture-controls/ol`](https://www.npmjs.com/package/@map-gesture-controls/ol) instead. It wraps this package and adds map integration out of the box.
+
+## What it does
+
+- Detects hands and classifies gestures at 30+ fps using MediaPipe Hand Landmarker
+- Recognizes **fist** (pan), **open palm** (zoom), and **idle** states
+- Manages gesture transitions with dwell timers and grace periods to avoid flickering
+- Provides a configurable webcam overlay with corner/full/hidden display modes
+- Ships fully typed TypeScript declarations
+
+## Install
+
+```bash
+npm install @map-gesture-controls/core
+```
+
+## Quick start
+
+```ts
+import { GestureController } from '@map-gesture-controls/core';
+import '@map-gesture-controls/core/style.css';
+
+const controller = new GestureController({
+  onGestureFrame(frame) {
+    // frame.hands contains detected hands with landmarks and gesture type
+    console.log(frame);
+  },
+});
+
+// Must be called from a user interaction (button click) for webcam permission
+await controller.start();
+```
+
+## Exports
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `GestureController` | Class | Opens the webcam, runs MediaPipe detection, and emits gesture frames |
+| `GestureStateMachine` | Class | Manages gesture state transitions with dwell and grace timers |
+| `WebcamOverlay` | Class | Renders a configurable camera preview overlay |
+| `classifyGesture` | Function | Classifies a set of hand landmarks into `fist`, `openPalm`, or `none` |
+| `getHandSize` | Function | Computes the bounding size of a hand from its landmarks |
+| `getTwoHandDistance` | Function | Measures the distance between two detected hands |
+| `DEFAULT_WEBCAM_CONFIG` | Constant | Default webcam overlay settings |
+| `DEFAULT_TUNING_CONFIG` | Constant | Default tuning parameters |
+
+Full TypeScript types are exported for `GestureMode`, `GestureFrame`, `DetectedHand`, `WebcamConfig`, `TuningConfig`, and more.
+
+## Gesture recognition
+
+| Gesture | Detection rule | Use case |
+| --- | --- | --- |
+| **Fist** | One hand, 3+ fingers curled | Pan / drag |
+| **Open palm** | Two hands, all fingers extended and spread | Zoom in/out |
+| **Idle** | Anything else | No action |
+
+Gestures are confirmed after a configurable dwell period (default 80 ms) and held through a grace period (default 150 ms) to prevent flickering when tracking briefly drops.
+
+## Use cases
+
+- **Kiosk and exhibit displays** where touch screens get dirty or break down
+- **Accessibility** for users who cannot use a mouse or touchscreen
+- **Touchless interfaces** in medical, industrial, or public environments
+- **Custom map integrations** beyond OpenLayers (build your own adapter using this core engine)
+
+## Browser support
+
+Requires **WebGL**, **`getUserMedia`** (webcam), and **WASM** support. Works in Chrome 111+, Edge 111+, Firefox 115+, and Safari 17+.
+
+## Documentation
+
+Full docs, live demos, and configuration reference at **[sanderdesnaijer.github.io/map-gesture-controls](https://sanderdesnaijer.github.io/map-gesture-controls/)**
+
+## Privacy
+
+MediaPipe WASM and the hand landmarker model are loaded from public CDNs. No video frames are sent to any server. All gesture processing happens locally in the browser.
+
+## License
+
+MIT

package/dist/GestureStateMachine.d.ts

@@ -5,7 +5,7 @@ export interface StateMachineOutput {
     zoomDelta: number | null;
 }
 /**
- * GestureStateMachine — 3-state FSM
+ * GestureStateMachine: 3-state FSM
  *
  * Priority rules (evaluated every frame):
  *   both hands visible AND both open palm → desired = 'zooming'

package/dist/GestureStateMachine.js

@@ -65,7 +65,7 @@ class EMAScalar {
     }
 }
 /**
- * GestureStateMachine — 3-state FSM
+ * GestureStateMachine: 3-state FSM
  *
  * Priority rules (evaluated every frame):
  *   both hands visible AND both open palm → desired = 'zooming'

package/dist/GestureStateMachine.test.js

@@ -7,7 +7,7 @@ const FAST_TUNING = {
     releaseGraceMs: 0, // grace=0: idle on the SECOND frame after release
     panDeadzonePx: 0,
     zoomDeadzoneRatio: 0,
-    smoothingAlpha: 1, // no smoothing — raw values pass through
+    smoothingAlpha: 1, // no smoothing, raw values pass through
     minDetectionConfidence: 0.65,
     minTrackingConfidence: 0.65,
     minPresenceConfidence: 0.60,
@@ -97,9 +97,9 @@ describe('GestureStateMachine', () => {
         fsm.update(makeFrame(0, makeHand('fist', lm1), null));
         // Frame 2: transition fires → panning, but buildOutput returns from idle branch (panDelta=null)
         fsm.update(makeFrame(0, makeHand('fist', lm1), null));
-        // Frame 3: first real panning frame — sets prevPanPos = wristPos1, no delta yet
+        // Frame 3: first real panning frame, sets prevPanPos = wristPos1, no delta yet
         fsm.update(makeFrame(1, makeHand('fist', lm1), null));
-        // Frame 4: second panning frame — emits delta
+        // Frame 4: second panning frame, emits delta
         const out = fsm.update(makeFrame(2, makeHand('fist', lm2), null));
         expect(out.mode).toBe('panning');
         expect(out.panDelta).not.toBeNull();
@@ -122,7 +122,7 @@ describe('GestureStateMachine', () => {
         // Frame 1+2: dwell + transition (zooming entered on frame 2, but output comes from idle branch)
         fsm.update(makeFrame(0, makeHand('openPalm', lmL1), makeHand('openPalm', lmR1)));
         fsm.update(makeFrame(0, makeHand('openPalm', lmL1), makeHand('openPalm', lmR1)));
-        // Frame 3: first real zooming frame — sets prevZoomDist, no delta yet
+        // Frame 3: first real zooming frame, sets prevZoomDist, no delta yet
         fsm.update(makeFrame(1, makeHand('openPalm', lmL1), makeHand('openPalm', lmR1)));
         // Frame 4: wider spread → positive delta
         const out = fsm.update(makeFrame(2, makeHand('openPalm', lmL2), makeHand('openPalm', lmR2)));

package/dist/gestureClassifier.d.ts

@@ -1,13 +1,13 @@
 import type { HandLandmark, GestureType } from './types.js';
 /**
  * Returns the apparent 2D size of the hand: wrist-to-middle-MCP distance
- * in normalised screen space (0–1). Used as a depth proxy — hand grows
- * larger as it moves toward the camera.
+ * in normalised screen space (0-1). Used as a depth proxy (hand grows
+ * larger as it moves toward the camera).
  */
 export declare function getHandSize(landmarks: HandLandmark[]): number;
 /**
  * Returns the Euclidean distance between the index fingertips of two hands
- * in normalised screen space (0–1). Used as the two-hand zoom metric —
+ * in normalised screen space (0-1). Used as the two-hand zoom metric:
  * hands moving apart = positive delta = zoom in.
  */
 export declare function getTwoHandDistance(landmarksA: HandLandmark[], landmarksB: HandLandmark[]): number;

package/dist/gestureClassifier.js

@@ -11,7 +11,7 @@ function dist(a, b) {
  * Returns true if all four fingers (index–pinky) are extended AND spread apart.
  *
  * "Extended": tip is farther from the wrist than its MCP joint (allows slightly
- * bent fingers — the 0.9 factor gives ~10% slack).
+ * bent fingers; the 0.9 factor gives ~10% slack).
  *
  * "Spread": the minimum distance between any two adjacent fingertips (index–middle,
  * middle–ring, ring–pinky) must be at least spreadThreshold × handSize. Using the
@@ -31,7 +31,7 @@ function areAllFingersExtended(landmarks) {
     }
     // Spread check: minimum pairwise distance between adjacent fingertips vs hand size.
     // Using the minimum (not mean) catches duck/pinch shapes where adjacent fingertips
-    // touch — the mean can stay high because the outer pair (index↔pinky) is still far
+    // touch: the mean can stay high because the outer pair (index↔pinky) is still far
     // apart, but the minimum collapses to near zero when any two tips cluster together.
     // A natural open hand has even adjacent tips ~20–35% of handSize apart.
     // A duck has adjacent tips at ~2–8% of handSize. Threshold of 0.18 separates them.
@@ -67,8 +67,8 @@ function areAllFingersCurled(landmarks) {
 }
 /**
  * Returns the apparent 2D size of the hand: wrist-to-middle-MCP distance
- * in normalised screen space (0–1). Used as a depth proxy — hand grows
- * larger as it moves toward the camera.
+ * in normalised screen space (0-1). Used as a depth proxy (hand grows
+ * larger as it moves toward the camera).
  */
 export function getHandSize(landmarks) {
     const wrist = landmarks[LANDMARKS.WRIST];
@@ -79,7 +79,7 @@ export function getHandSize(landmarks) {
 }
 /**
  * Returns the Euclidean distance between the index fingertips of two hands
- * in normalised screen space (0–1). Used as the two-hand zoom metric —
+ * in normalised screen space (0-1). Used as the two-hand zoom metric:
  * hands moving apart = positive delta = zoom in.
  */
 export function getTwoHandDistance(landmarksA, landmarksB) {

package/dist/gestureClassifier.test.js

@@ -31,7 +31,7 @@ function makeOpenPalmLandmarks() {
     lm[LANDMARKS.MIDDLE_MCP] = { x: 0.4, y: 0.5, z: 0 };
     lm[LANDMARKS.RING_MCP] = { x: 0.5, y: 0.5, z: 0 };
     lm[LANDMARKS.PINKY_MCP] = { x: 0.6, y: 0.5, z: 0 };
-    // Fingertips — extended (farther from wrist than MCPs) and spread
+    // Fingertips: extended (farther from wrist than MCPs) and spread
     lm[LANDMARKS.INDEX_TIP] = { x: 0.2, y: 0.1, z: 0 };
     lm[LANDMARKS.MIDDLE_TIP] = { x: 0.35, y: 0.1, z: 0 };
     lm[LANDMARKS.RING_TIP] = { x: 0.5, y: 0.1, z: 0 };
@@ -42,7 +42,7 @@ function makeOpenPalmLandmarks() {
  * Build a fist hand.
  *
  * Strategy: wrist at (0.5, 0.8), MCP joints at (0.5, 0.5),
- * fingertips curled back to (0.5, 0.7) — closer to wrist than MCPs.
+ * fingertips curled back to (0.5, 0.7), closer to wrist than MCPs.
  *
  * dist(tip, wrist) ≈ 0.1 < dist(mcp, wrist) * 1.1 ≈ 0.33  ✓
  */
@@ -72,7 +72,7 @@ describe('classifyGesture', () => {
         expect(classifyGesture(makeFistLandmarks())).toBe('fist');
     });
     it('returns "none" for an ambiguous / neutral hand', () => {
-        // All landmarks at the same point — fingers neither extended nor curled
+        // All landmarks at the same point, fingers neither extended nor curled
         expect(classifyGesture(makeLandmarks())).toBe('none');
     });
     it('prefers "fist" over "openPalm" when both criteria match', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@map-gesture-controls/core",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Map-agnostic hand gesture detection and state machine (MediaPipe)",
   "type": "module",
   "main": "dist/index.js",
@@ -30,8 +30,29 @@
   "keywords": [
     "mediapipe",
     "hand-gestures",
-    "gesture-detection"
+    "gesture-detection",
+    "gesture-recognition",
+    "hand-tracking",
+    "webcam",
+    "touchless",
+    "hands-free",
+    "accessibility",
+    "computer-vision",
+    "wasm",
+    "kiosk",
+    "map",
+    "interaction"
   ],
+  "homepage": "https://sanderdesnaijer.github.io/map-gesture-controls/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sanderdesnaijer/map-gesture-controls.git",
+    "directory": "packages/map-gesture-core"
+  },
+  "bugs": {
+    "url": "https://github.com/sanderdesnaijer/map-gesture-controls/issues"
+  },
+  "author": "Sander de Snaijer",
   "overrides": {
     "esbuild": "^0.25.0"
   },