@map-gesture-controls/core 0.1.8 → 0.2.0

package/README.md

@@ -16,7 +16,7 @@
 ## What it does
 
 - Detects hands and classifies gestures at 30+ fps using MediaPipe Hand Landmarker
-- Recognizes **fist** (left = pan, right = zoom, both = rotate) and **idle** states
+- Recognizes **fist** and **pinch** as interchangeable triggers (left = pan, right = zoom, both = rotate)
 - 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
@@ -59,7 +59,8 @@ controller.start();
 | `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` or `none` |
+| `classifyGesture` | Function | Stateless classifier: returns `fist`, `pinch`, `openPalm`, or `none` for a set of landmarks |
+| `createHandClassifier` | Function | Returns a stateful per-hand classifier with pinch hysteresis (use this instead of `classifyGesture` in custom pipelines) |
 | `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 |
@@ -69,13 +70,21 @@ Full TypeScript types are exported for `GestureMode`, `GestureFrame`, `DetectedH
 
 ## Gesture recognition
 
-| Gesture | Detection rule | Use case |
+Both **fist** and **pinch** trigger the same map actions, users can use whichever is more comfortable.
+
+| Gesture | Detection rule | Map action |
 | --- | --- | --- |
 | **Left fist** | Left hand, 3+ fingers curled | Pan / drag |
-| **Right fist** | Right hand, 3+ fingers curled | Zoom in/out (vertical movement) |
-| **Both fists** | Both hands, 3+ fingers curled each | Rotate map |
+| **Left pinch** | Left hand, thumb and index tip within 25% of hand size (exits at 35%) | Pan / drag |
+| **Right fist** | Right hand, 3+ fingers curled | Zoom (move up = in, down = out) |
+| **Right pinch** | Right hand, thumb and index tip within 25% of hand size (exits at 35%) | Zoom (move up = in, down = out) |
+| **Both hands active** | Both hands fist or pinch (mixed is fine) | Rotate map |
 | **Idle** | Anything else | No action |
 
+> **Reset (OpenLayers only):** `@map-gesture-controls/ol` adds a reset gesture on top of the above. Bring both hands together in a prayer/namaste pose (wrists close, neither hand making a fist or pinch) and hold for 1 second. A progress bar fills in the webcam overlay; when it completes, pan, zoom, and rotation all snap back to their initial values.
+
+Pinch detection uses hysteresis: the gesture is entered at 25% of hand size and held until fingers open beyond 35%. This prevents flickering when fingers hover near the threshold during a held pinch.
+
 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

package/dist/GestureController.d.ts

@@ -15,6 +15,8 @@ export declare class GestureController {
     private onFrame;
     private tuning;
     private lastVideoTime;
+    private leftClassifier;
+    private rightClassifier;
     constructor(tuning: TuningConfig, onFrame: FrameCallback);
     /**
      * Initialise MediaPipe and request webcam access.

package/dist/GestureController.js

@@ -1,5 +1,5 @@
 import { FilesetResolver } from '@mediapipe/tasks-vision';
-import { classifyGesture } from './gestureClassifier.js';
+import { createHandClassifier } from './gestureClassifier.js';
 import { MEDIAPIPE_WASM_URL } from './constants.js';
 /**
  * GestureController
@@ -57,6 +57,19 @@ export class GestureController {
             writable: true,
             value: -1
         });
+        // One stateful classifier per hand label; persists pinch hysteresis across frames.
+        Object.defineProperty(this, "leftClassifier", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: createHandClassifier()
+        });
+        Object.defineProperty(this, "rightClassifier", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: createHandClassifier()
+        });
         this.tuning = tuning;
         this.onFrame = onFrame;
     }
@@ -146,7 +159,8 @@ export class GestureController {
             const rawLabel = handednessArr?.[0]?.categoryName;
             const label = rawLabel === 'Left' ? 'Left' : 'Right';
             const score = handednessArr?.[0]?.score ?? 0;
-            const gesture = classifyGesture(landmarks);
+            const classify = label === 'Left' ? this.leftClassifier : this.rightClassifier;
+            const gesture = classify(landmarks);
             return { handedness: label, score, landmarks, gesture };
         });
         const leftHand = hands.find((h) => h.handedness === 'Left') ?? null;

package/dist/GestureStateMachine.d.ts

@@ -33,6 +33,9 @@ export declare class GestureStateMachine {
     private prevZoomDist;
     private rotateSmoother;
     private prevRotateAngle;
+    private leftActiveFrames;
+    private rightActiveFrames;
+    private static readonly ESCALATION_FRAMES;
     constructor(tuning: TuningConfig);
     getMode(): GestureMode;
     update(frame: GestureFrame): StateMachineOutput;

package/dist/GestureStateMachine.js

@@ -142,6 +142,22 @@ export class GestureStateMachine {
             writable: true,
             value: null
         });
+        // Tracks how many consecutive frames each hand has been active.
+        // Used to require the secondary hand to be stable before escalating
+        // the mode (e.g. pan → rotate), preventing a single noisy frame from
+        // interrupting an ongoing single-hand gesture.
+        Object.defineProperty(this, "leftActiveFrames", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        Object.defineProperty(this, "rightActiveFrames", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
         this.panSmoother = new EMAPoint(tuning.smoothingAlpha);
         this.zoomSmoother = new EMAScalar(tuning.smoothingAlpha);
         this.rotateSmoother = new EMAScalar(tuning.smoothingAlpha);
@@ -154,17 +170,35 @@ export class GestureStateMachine {
         const { actionDwellMs, releaseGraceMs } = this.tuning;
         const { leftHand, rightHand } = frame;
         // ── Determine desired mode for this frame ─────────────────────────────────
-        const rightFist = rightHand !== null && rightHand.gesture === 'fist';
-        const leftFist = leftHand !== null && leftHand.gesture === 'fist';
-        const bothFists = rightFist && leftFist;
-        // Both fists → rotate; right only → zoom; left only → pan
-        const desired = bothFists
+        // Both fist and pinch trigger the same modes, users can choose either.
+        const isActive = (hand) => hand !== null && (hand.gesture === 'fist' || hand.gesture === 'pinch');
+        const rightActive = isActive(rightHand);
+        const leftActive = isActive(leftHand);
+        // Track consecutive active frames per hand. Used to guard against a single
+        // noisy frame from the secondary hand escalating (or interrupting) an
+        // ongoing single-hand gesture. Counts reset to 0 the moment a hand drops.
+        this.leftActiveFrames = leftActive ? this.leftActiveFrames + 1 : 0;
+        this.rightActiveFrames = rightActive ? this.rightActiveFrames + 1 : 0;
+        // Escalation to 'rotating' requires both hands to have been active for at
+        // least ESCALATION_FRAMES consecutive frames. This prevents one brief noisy
+        // frame on the secondary hand from interrupting an ongoing pan or zoom.
+        const bothStable = this.leftActiveFrames >= GestureStateMachine.ESCALATION_FRAMES &&
+            this.rightActiveFrames >= GestureStateMachine.ESCALATION_FRAMES;
+        // Both stable → rotate; right only → zoom; left only → pan.
+        // When both hands are active but not yet stable, we preserve the current
+        // single-hand mode (panning/zooming) so the secondary hand must be held
+        // for ESCALATION_FRAMES before rotating kicks in. This prevents a single
+        // noisy frame from the secondary hand from interrupting an ongoing gesture.
+        const bothActiveButUnstable = leftActive && rightActive && !bothStable;
+        const desired = bothStable
             ? 'rotating'
-            : rightFist
-                ? 'zooming'
-                : leftFist
-                    ? 'panning'
-                    : 'idle';
+            : bothActiveButUnstable && (this.mode === 'panning' || this.mode === 'zooming')
+                ? this.mode // hold current mode until secondary hand is confirmed stable
+                : rightActive
+                    ? 'zooming'
+                    : leftActive
+                        ? 'panning'
+                        : 'idle';
         // ── idle ──────────────────────────────────────────────────────────────────
         if (this.mode === 'idle') {
             if (desired !== 'idle') {
@@ -182,6 +216,11 @@ export class GestureStateMachine {
         }
         // ── panning ───────────────────────────────────────────────────────────────
         if (this.mode === 'panning') {
+            // Escalate to rotating once the right hand becomes stably active too.
+            if (bothStable) {
+                this.transitionTo('rotating');
+                return this.buildOutput(null, null, null);
+            }
             if (desired !== 'panning') {
                 if (this.releaseTimer === null) {
                     this.releaseTimer = now;
@@ -192,7 +231,7 @@ export class GestureStateMachine {
                 return this.buildOutput(null, null, null);
             }
             this.releaseTimer = null;
-            const fistHand = leftHand?.gesture === 'fist' ? leftHand : null;
+            const fistHand = isActive(leftHand) ? leftHand : null;
             if (!fistHand) {
                 this.transitionTo('idle');
                 return this.buildOutput(null, null, null);
@@ -213,6 +252,11 @@ export class GestureStateMachine {
         }
         // ── zooming ───────────────────────────────────────────────────────────────
         if (this.mode === 'zooming') {
+            // Escalate to rotating once the left hand becomes stably active too.
+            if (bothStable) {
+                this.transitionTo('rotating');
+                return this.buildOutput(null, null, null);
+            }
             if (desired !== 'zooming') {
                 if (this.releaseTimer === null) {
                     this.releaseTimer = now;
@@ -283,6 +327,13 @@ export class GestureStateMachine {
         this.mode = next;
         this.releaseTimer = null;
         this.actionDwell = null;
+        // Reset both counters so escalation requires a fresh stable run in the new mode.
+        // Exception: keep the dominant hand's counter when entering a single-hand mode so
+        // it does not need to re-accumulate from zero if the hand was already stable.
+        if (next !== 'panning' && next !== 'rotating')
+            this.leftActiveFrames = 0;
+        if (next !== 'zooming' && next !== 'rotating')
+            this.rightActiveFrames = 0;
         if (next !== 'panning') {
             this.panSmoother.reset();
             this.prevPanPos = null;
@@ -303,3 +354,9 @@ export class GestureStateMachine {
         this.transitionTo('idle');
     }
 }
+Object.defineProperty(GestureStateMachine, "ESCALATION_FRAMES", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 3
+});

package/dist/WebcamOverlay.d.ts

@@ -14,15 +14,19 @@ export declare class WebcamOverlay {
     private canvas;
     private ctx;
     private badge;
+    private resetBar;
+    private resetFill;
     private config;
+    private lastMode;
     constructor(config: WebcamConfig);
     /** Attach video element produced by GestureController */
     attachVideo(video: HTMLVideoElement): void;
     /** Mount the overlay into the given parent (usually document.body or map container) */
     mount(parent: HTMLElement): void;
     unmount(): void;
-    /** Called each frame with the latest gesture frame and mode. */
-    render(frame: GestureFrame | null, mode: GestureMode): void;
+    /** Called each frame with the latest gesture frame, mode, and optional reset progress (0 to 1). */
+    render(frame: GestureFrame | null, mode: GestureMode, resetProgress?: number): void;
+    private updateResetBar;
     private drawSkeleton;
     private updateBadge;
     private applyContainerStyles;

package/dist/WebcamOverlay.js

@@ -51,12 +51,30 @@ export class WebcamOverlay {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "resetBar", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "resetFill", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "config", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "lastMode", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         this.config = config;
         this.container = document.createElement('div');
         this.container.className = 'ol-gesture-overlay';
@@ -67,8 +85,16 @@ export class WebcamOverlay {
         this.badge = document.createElement('div');
         this.badge.className = 'ol-gesture-badge ol-gesture-badge--idle';
         this.badge.textContent = 'Idle';
+        this.resetBar = document.createElement('div');
+        this.resetBar.className = 'ol-gesture-reset';
+        this.resetBar.innerHTML =
+            '<span class="ol-gesture-reset-label">Reset</span>' +
+                '<div class="ol-gesture-reset-track"><div class="ol-gesture-reset-fill"></div></div>';
+        this.resetBar.style.opacity = '0';
+        this.resetFill = this.resetBar.querySelector('.ol-gesture-reset-fill');
         this.container.appendChild(this.canvas);
         this.container.appendChild(this.badge);
+        this.container.appendChild(this.resetBar);
         const ctx = this.canvas.getContext('2d');
         if (!ctx)
             throw new Error('Cannot get 2D canvas context');
@@ -88,13 +114,16 @@ export class WebcamOverlay {
     unmount() {
         this.container.parentElement?.removeChild(this.container);
     }
-    /** Called each frame with the latest gesture frame and mode. */
-    render(frame, mode) {
+    /** Called each frame with the latest gesture frame, mode, and optional reset progress (0 to 1). */
+    render(frame, mode, resetProgress = 0) {
         this.updateBadge(mode);
+        this.updateResetBar(resetProgress);
         const w = this.config.width;
         const h = this.config.height;
-        this.canvas.width = w;
-        this.canvas.height = h;
+        if (this.canvas.width !== w || this.canvas.height !== h) {
+            this.canvas.width = w;
+            this.canvas.height = h;
+        }
         this.ctx.clearRect(0, 0, w, h);
         if (frame === null)
             return;
@@ -102,6 +131,10 @@ export class WebcamOverlay {
             this.drawSkeleton(hand.landmarks, mode, hand.gesture === 'fist');
         }
     }
+    updateResetBar(resetProgress) {
+        this.resetFill.style.width = `${resetProgress * 100}%`;
+        this.resetBar.style.opacity = resetProgress > 0 ? '1' : '0';
+    }
     drawSkeleton(landmarks, mode, isActionHand) {
         const { ctx } = this;
         const w = this.config.width;
@@ -141,6 +174,9 @@ export class WebcamOverlay {
         }
     }
     updateBadge(mode) {
+        if (mode === this.lastMode)
+            return;
+        this.lastMode = mode;
         const labels = {
             idle: 'Idle',
             panning: 'Pan',

package/dist/constants.d.ts

@@ -13,6 +13,8 @@ export declare const LANDMARKS: {
     readonly PINKY_TIP: 20;
     readonly PINKY_MCP: 17;
 };
+export declare const PINCH_THRESHOLD = 0.25;
+export declare const PINCH_RELEASE_THRESHOLD = 0.35;
 export declare const FINGERTIP_INDICES: readonly [8, 12, 16, 20];
 export declare const FINGER_BASE_INDICES: readonly [5, 9, 13, 17];
 export declare const COLORS: {

package/dist/constants.js

@@ -29,6 +29,12 @@ export const LANDMARKS = {
     PINKY_TIP: 20,
     PINKY_MCP: 17,
 };
+// Pinch detection thresholds as a fraction of hand size.
+// Hysteresis: enter pinch at PINCH_THRESHOLD, exit (release) at PINCH_RELEASE_THRESHOLD.
+// The wider release threshold prevents the classifier from flickering between
+// 'pinch' and 'none' when the fingers hover at the edge of the enter threshold.
+export const PINCH_THRESHOLD = 0.25;
+export const PINCH_RELEASE_THRESHOLD = 0.35;
 // Fingertip indices for open-palm detection
 export const FINGERTIP_INDICES = [
     LANDMARKS.INDEX_TIP,

package/dist/gestureClassifier.d.ts

@@ -14,9 +14,24 @@ export declare function getTwoHandDistance(landmarksA: HandLandmark[], landmarks
 /**
  * Classify the gesture for a single hand from its landmarks.
  *
- * Priority: fist > openPalm > none
+ * Priority: fist > pinch > openPalm > none
  *
- * Fist: most fingers curled
- * Open palm: all fingers extended
+ * Fist:      most fingers curled
+ * Pinch:     thumb tip and index tip close together
+ * Open palm: all fingers extended and spread
+ *
+ * NOTE: This stateless version has no pinch hysteresis. Use `createHandClassifier`
+ * for a stateful per-hand classifier that prevents pinch flickering.
  */
 export declare function classifyGesture(landmarks: HandLandmark[]): GestureType;
+/**
+ * Returns a stateful classify function for a single hand.
+ *
+ * Pinch uses hysteresis: the hand enters 'pinch' when tips are within
+ * PINCH_THRESHOLD of hand size, and stays in 'pinch' until tips separate
+ * beyond PINCH_RELEASE_THRESHOLD. This prevents rapid toggling when fingers
+ * hover at the entry threshold during a held pinch gesture.
+ *
+ * Use one instance per hand (left / right) and reset between hand sessions.
+ */
+export declare function createHandClassifier(): (landmarks: HandLandmark[]) => GestureType;

package/dist/gestureClassifier.js

@@ -1,4 +1,4 @@
-import { LANDMARKS, FINGERTIP_INDICES, FINGER_BASE_INDICES } from './constants.js';
+import { LANDMARKS, FINGERTIP_INDICES, FINGER_BASE_INDICES, PINCH_THRESHOLD, PINCH_RELEASE_THRESHOLD } from './constants.js';
 /**
  * Euclidean distance between two landmarks (ignoring Z).
  */
@@ -89,13 +89,42 @@ export function getTwoHandDistance(landmarksA, landmarksB) {
         return 0;
     return dist(tipA, tipB);
 }
+/**
+ * Stateless pinch check used only as the entry condition.
+ * Returns true when thumb tip and index tip are within PINCH_THRESHOLD of hand size.
+ */
+function isPinchEnter(landmarks) {
+    const handSize = getHandSize(landmarks);
+    if (handSize === 0)
+        return false;
+    const thumbTip = landmarks[LANDMARKS.THUMB_TIP];
+    const indexTip = landmarks[LANDMARKS.INDEX_TIP];
+    return dist(thumbTip, indexTip) < handSize * PINCH_THRESHOLD;
+}
+/**
+ * Returns true when thumb tip and index tip are still within PINCH_RELEASE_THRESHOLD.
+ * Used as the exit condition to implement hysteresis: once pinching, we stay in
+ * 'pinch' until the fingers open wider than the release threshold.
+ */
+function isPinchHeld(landmarks) {
+    const handSize = getHandSize(landmarks);
+    if (handSize === 0)
+        return false;
+    const thumbTip = landmarks[LANDMARKS.THUMB_TIP];
+    const indexTip = landmarks[LANDMARKS.INDEX_TIP];
+    return dist(thumbTip, indexTip) < handSize * PINCH_RELEASE_THRESHOLD;
+}
 /**
  * Classify the gesture for a single hand from its landmarks.
  *
- * Priority: fist > openPalm > none
+ * Priority: fist > pinch > openPalm > none
+ *
+ * Fist:      most fingers curled
+ * Pinch:     thumb tip and index tip close together
+ * Open palm: all fingers extended and spread
  *
- * Fist: most fingers curled
- * Open palm: all fingers extended
+ * NOTE: This stateless version has no pinch hysteresis. Use `createHandClassifier`
+ * for a stateful per-hand classifier that prevents pinch flickering.
  */
 export function classifyGesture(landmarks) {
     if (landmarks.length < 21)
@@ -103,8 +132,48 @@ export function classifyGesture(landmarks) {
     if (areAllFingersCurled(landmarks)) {
         return 'fist';
     }
+    if (isPinchEnter(landmarks)) {
+        return 'pinch';
+    }
     if (areAllFingersExtended(landmarks)) {
         return 'openPalm';
     }
     return 'none';
 }
+/**
+ * Returns a stateful classify function for a single hand.
+ *
+ * Pinch uses hysteresis: the hand enters 'pinch' when tips are within
+ * PINCH_THRESHOLD of hand size, and stays in 'pinch' until tips separate
+ * beyond PINCH_RELEASE_THRESHOLD. This prevents rapid toggling when fingers
+ * hover at the entry threshold during a held pinch gesture.
+ *
+ * Use one instance per hand (left / right) and reset between hand sessions.
+ */
+export function createHandClassifier() {
+    let pinching = false;
+    return function classify(landmarks) {
+        if (landmarks.length < 21) {
+            pinching = false;
+            return 'none';
+        }
+        if (areAllFingersCurled(landmarks)) {
+            pinching = false;
+            return 'fist';
+        }
+        // Hysteresis: enter pinch on PINCH_THRESHOLD, exit on PINCH_RELEASE_THRESHOLD.
+        if (pinching) {
+            pinching = isPinchHeld(landmarks);
+        }
+        else {
+            pinching = isPinchEnter(landmarks);
+        }
+        if (pinching) {
+            return 'pinch';
+        }
+        if (areAllFingersExtended(landmarks)) {
+            return 'openPalm';
+        }
+        return 'none';
+    };
+}

package/dist/index.d.ts

@@ -2,6 +2,6 @@ export { GestureController } from './GestureController.js';
 export { GestureStateMachine } from './GestureStateMachine.js';
 export type { StateMachineOutput } from './GestureStateMachine.js';
 export { WebcamOverlay } from './WebcamOverlay.js';
-export { classifyGesture, getHandSize, getTwoHandDistance } from './gestureClassifier.js';
+export { classifyGesture, createHandClassifier, getHandSize, getTwoHandDistance } from './gestureClassifier.js';
 export type { GestureMode, GestureType, HandednessLabel, GestureFrame, DetectedHand, WebcamConfig, TuningConfig, SmoothedPoint, Point2D, HandLandmark, } from './types.js';
 export { DEFAULT_WEBCAM_CONFIG, DEFAULT_TUNING_CONFIG, LANDMARKS, COLORS, } from './constants.js';