@map-gesture-controls/core 0.1.7 → 0.1.9

package/dist/GestureStateMachine.test.js

@@ -28,6 +28,7 @@ function makeFrame(timestamp, leftHand, rightHand) {
 }
 /**
  * Drive the FSM into 'panning' with dwell=0 (requires two identical frames).
+ * Pan = left fist only.
  */
 function enterPanning(fsm, hand = makeHand('fist')) {
     fsm.update(makeFrame(0, hand, null)); // starts dwell timer
@@ -35,8 +36,27 @@ function enterPanning(fsm, hand = makeHand('fist')) {
 }
 /**
  * Drive the FSM into 'zooming' with dwell=0 (requires two identical frames).
+ * Zoom = right fist only.
  */
-function enterZooming(fsm, left = makeHand('openPalm'), right = makeHand('openPalm')) {
+function enterZooming(fsm, right = makeHand('fist')) {
+    fsm.update(makeFrame(0, null, right));
+    fsm.update(makeFrame(0, null, right));
+}
+/**
+ * Drive the FSM into 'rotating' with dwell=0.
+ * Requires ESCALATION_FRAMES (3) consecutive both-active frames, then one
+ * more for the dwell to fire (dwell=0 means it fires on the frame that meets
+ * the threshold, so 3 stable frames + 1 dwell frame = 4 total).
+ * Rotate = both fists.
+ */
+function enterRotating(fsm, left = makeHand('fist'), right = makeHand('fist')) {
+    // Frame 1: both active, dwell timer starts (idle branch, no transition yet).
+    // Frame 2: dwell fires → transitionTo('zooming'), resets leftActiveFrames to 0.
+    // Frames 3-5: leftActiveFrames counts 1 → 2 → 3 (= ESCALATION_FRAMES).
+    // Frame 5: bothStable=true → zooming branch escalates to rotating.
+    fsm.update(makeFrame(0, left, right));
+    fsm.update(makeFrame(0, left, right));
+    fsm.update(makeFrame(0, left, right));
     fsm.update(makeFrame(0, left, right));
     fsm.update(makeFrame(0, left, right));
 }
@@ -51,22 +71,53 @@ describe('GestureStateMachine', () => {
         expect(fsm.getMode()).toBe('idle');
     });
     // ── idle → panning ─────────────────────────────────────────────────────────
-    it('transitions to panning after the dwell elapses (two frames, dwell=0)', () => {
+    it('transitions to panning when left fist is held (two frames, dwell=0)', () => {
         const fistHand = makeHand('fist');
         fsm.update(makeFrame(0, fistHand, null)); // starts dwell
         const out = fsm.update(makeFrame(0, fistHand, null)); // 0 >= 0 → panning
         expect(out.mode).toBe('panning');
     });
     // ── idle → zooming ─────────────────────────────────────────────────────────
-    it('transitions to zooming when two open palms are held (two frames, dwell=0)', () => {
-        const left = makeHand('openPalm');
-        const right = makeHand('openPalm');
+    it('transitions to zooming when right fist is held (two frames, dwell=0)', () => {
+        const right = makeHand('fist');
+        fsm.update(makeFrame(0, null, right));
+        const out = fsm.update(makeFrame(0, null, right));
+        expect(out.mode).toBe('zooming');
+    });
+    // ── idle → rotating ────────────────────────────────────────────────────────
+    it('transitions to rotating when both fists are held stably (5 frames: dwell + 3 escalation)', () => {
+        const left = makeHand('fist');
+        const right = makeHand('fist');
+        fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
         fsm.update(makeFrame(0, left, right));
         const out = fsm.update(makeFrame(0, left, right));
-        expect(out.mode).toBe('zooming');
+        expect(out.mode).toBe('rotating');
+    });
+    it('prefers rotating over zooming once both fists are held stably', () => {
+        const left = makeHand('fist');
+        const right = makeHand('fist');
+        fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
+        fsm.update(makeFrame(0, left, right));
+        const out = fsm.update(makeFrame(0, left, right));
+        // both fists stable for ESCALATION_FRAMES = rotating, not zooming
+        expect(out.mode).toBe('rotating');
+    });
+    it('does NOT transition to rotating if second hand only appears for 1-2 frames (noise guard)', () => {
+        const left = makeHand('fist');
+        const right = makeHand('fist');
+        // Only 2 frames with both hands — below ESCALATION_FRAMES threshold
+        fsm.update(makeFrame(0, left, null)); // establish left pan
+        fsm.update(makeFrame(0, left, null)); // → panning
+        fsm.update(makeFrame(1, left, right)); // right appears — 1 frame, not stable yet
+        const out = fsm.update(makeFrame(1, left, right)); // 2 frames — still below threshold
+        expect(out.mode).toBe('panning');
     });
     // ── panning → idle ─────────────────────────────────────────────────────────
-    it('returns to idle when the fist is released (releaseGraceMs=0)', () => {
+    it('returns to idle when the left fist is released (releaseGraceMs=0)', () => {
         enterPanning(fsm);
         expect(fsm.getMode()).toBe('panning');
         fsm.update(makeFrame(1, null, null)); // starts release timer
@@ -74,13 +125,21 @@ describe('GestureStateMachine', () => {
         expect(out.mode).toBe('idle');
     });
     // ── zooming → idle ─────────────────────────────────────────────────────────
-    it('returns to idle when open palms are released (releaseGraceMs=0)', () => {
+    it('returns to idle when right fist is released (releaseGraceMs=0)', () => {
         enterZooming(fsm);
         expect(fsm.getMode()).toBe('zooming');
         fsm.update(makeFrame(1, null, null)); // starts release timer
         const out = fsm.update(makeFrame(1, null, null)); // 0 >= 0 → idle
         expect(out.mode).toBe('idle');
     });
+    // ── rotating → idle ────────────────────────────────────────────────────────
+    it('returns to idle when both fists are released (releaseGraceMs=0)', () => {
+        enterRotating(fsm);
+        expect(fsm.getMode()).toBe('rotating');
+        fsm.update(makeFrame(1, null, null)); // starts release timer
+        const out = fsm.update(makeFrame(1, null, null)); // 0 >= 0 → idle
+        expect(out.mode).toBe('idle');
+    });
     // ── panDelta output ────────────────────────────────────────────────────────
     it('emits no panDelta on the first panning frame (no previous position)', () => {
         const fistHand = makeHand('fist');
@@ -108,27 +167,63 @@ describe('GestureStateMachine', () => {
     });
     // ── zoomDelta output ───────────────────────────────────────────────────────
     it('emits no zoomDelta on the first zooming frame', () => {
-        const left = makeHand('openPalm');
-        const right = makeHand('openPalm');
-        fsm.update(makeFrame(0, left, right));
-        const out = fsm.update(makeFrame(0, left, right)); // enters zooming, sets prevZoomDist
+        const right = makeHand('fist');
+        fsm.update(makeFrame(0, null, right));
+        const out = fsm.update(makeFrame(0, null, right)); // enters zooming, sets prevZoomDist
         expect(out.zoomDelta).toBeNull();
     });
-    it('emits zoomDelta once a previous distance is established', () => {
-        const lmL1 = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.4, y: 0.5, z: 0 } });
-        const lmR1 = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.6, y: 0.5, z: 0 } });
-        const lmL2 = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.3, y: 0.5, z: 0 } });
-        const lmR2 = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.7, y: 0.5, z: 0 } });
+    it('emits zoomDelta once a previous position is established', () => {
+        // Right wrist starts lower (y=0.6), then moves up (y=0.4) → zoom in (positive delta)
+        const lmR1 = makeLandmarks({ [LANDMARKS.WRIST]: { x: 0.5, y: 0.6, z: 0 } });
+        const lmR2 = makeLandmarks({ [LANDMARKS.WRIST]: { x: 0.5, y: 0.4, z: 0 } });
         // 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)));
+        fsm.update(makeFrame(0, null, makeHand('fist', lmR1)));
+        fsm.update(makeFrame(0, null, makeHand('fist', lmR1)));
         // 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)));
+        fsm.update(makeFrame(1, null, makeHand('fist', lmR1)));
+        // Frame 4: hand moved up → zoom in (positive delta)
+        const out = fsm.update(makeFrame(2, null, makeHand('fist', lmR2)));
         expect(out.mode).toBe('zooming');
         expect(out.zoomDelta).not.toBeNull();
-        expect(out.zoomDelta).toBeGreaterThan(0);
+        expect(out.zoomDelta).toBeGreaterThan(0); // hand moved up = zoom in
+    });
+    it('emits negative zoomDelta when hand moves down (zoom out)', () => {
+        const lmR1 = makeLandmarks({ [LANDMARKS.WRIST]: { x: 0.5, y: 0.4, z: 0 } });
+        const lmR2 = makeLandmarks({ [LANDMARKS.WRIST]: { x: 0.5, y: 0.6, z: 0 } });
+        fsm.update(makeFrame(0, null, makeHand('fist', lmR1)));
+        fsm.update(makeFrame(0, null, makeHand('fist', lmR1)));
+        fsm.update(makeFrame(1, null, makeHand('fist', lmR1)));
+        const out = fsm.update(makeFrame(2, null, makeHand('fist', lmR2)));
+        expect(out.zoomDelta).not.toBeNull();
+        expect(out.zoomDelta).toBeLessThan(0); // hand moved down = zoom out
+    });
+    // ── rotateDelta output ─────────────────────────────────────────────────────
+    it('emits no rotateDelta on the first rotating frame', () => {
+        // enterRotating drives into rotating mode (5 frames); the escalation frame
+        // itself returns null (no prevAngle yet). The *next* frame sets prevAngle,
+        // still no delta. Only the frame after that can emit a delta.
+        enterRotating(fsm);
+        // First full frame inside rotating — sets prevRotateAngle, no delta yet
+        const out = fsm.update(makeFrame(1, makeHand('fist'), makeHand('fist')));
+        expect(out.rotateDelta).toBeNull();
+    });
+    it('emits rotateDelta once a previous angle is established', () => {
+        // Left wrist at (0.2, 0.5), right wrist at (0.8, 0.5) → angle = 0 (horizontal)
+        const lmL1 = makeLandmarks({ [LANDMARKS.WRIST]: { x: 0.2, y: 0.5, z: 0 } });
+        const lmR1 = makeLandmarks({ [LANDMARKS.WRIST]: { x: 0.8, y: 0.5, z: 0 } });
+        // Tilt clockwise: right wrist drops, left wrist rises → angle increases
+        const lmL2 = makeLandmarks({ [LANDMARKS.WRIST]: { x: 0.2, y: 0.4, z: 0 } });
+        const lmR2 = makeLandmarks({ [LANDMARKS.WRIST]: { x: 0.8, y: 0.6, z: 0 } });
+        // Get into rotating mode (5 frames with lmL1/lmR1)
+        for (let i = 0; i < 5; i++) {
+            fsm.update(makeFrame(0, makeHand('fist', lmL1), makeHand('fist', lmR1)));
+        }
+        // First frame inside rotating: sets prevRotateAngle, no delta
+        fsm.update(makeFrame(1, makeHand('fist', lmL1), makeHand('fist', lmR1)));
+        // Second frame: emits delta
+        const out = fsm.update(makeFrame(2, makeHand('fist', lmL2), makeHand('fist', lmR2)));
+        expect(out.mode).toBe('rotating');
+        expect(out.rotateDelta).not.toBeNull();
     });
     // ── reset ──────────────────────────────────────────────────────────────────
     it('reset() returns the FSM to idle', () => {
@@ -137,6 +232,12 @@ describe('GestureStateMachine', () => {
         fsm.reset();
         expect(fsm.getMode()).toBe('idle');
     });
+    it('reset() returns the FSM to idle from rotating', () => {
+        enterRotating(fsm);
+        expect(fsm.getMode()).toBe('rotating');
+        fsm.reset();
+        expect(fsm.getMode()).toBe('idle');
+    });
     // ── dwell timer ────────────────────────────────────────────────────────────
     it('does NOT transition before actionDwellMs elapses', () => {
         const slowFsm = new GestureStateMachine({ ...FAST_TUNING, actionDwellMs: 200 });

package/dist/WebcamOverlay.js

@@ -145,6 +145,7 @@ export class WebcamOverlay {
             idle: 'Idle',
             panning: 'Pan',
             zooming: 'Zoom',
+            rotating: 'Rotate',
         };
         this.badge.textContent = labels[mode];
         this.badge.className = `ol-gesture-badge ol-gesture-badge--${mode}`;

package/dist/constants.d.ts

@@ -13,12 +13,15 @@ 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: {
     readonly idle: "#888888";
     readonly panning: "#00ccff";
     readonly zooming: "#00ffcc";
+    readonly rotating: "#ff9900";
     readonly landmark: "rgba(255,255,255,0.6)";
     readonly connection: "rgba(255,255,255,0.3)";
     readonly fingertipGlow: "#4488ff";

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,
@@ -47,6 +53,7 @@ export const COLORS = {
     idle: '#888888',
     panning: '#00ccff',
     zooming: '#00ffcc',
+    rotating: '#ff9900',
     landmark: 'rgba(255,255,255,0.6)',
     connection: 'rgba(255,255,255,0.3)',
     fingertipGlow: '#4488ff',

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';