@map-gesture-controls/core 0.1.9 → 0.2.0

package/README.md

@@ -70,7 +70,7 @@ Full TypeScript types are exported for `GestureMode`, `GestureFrame`, `DetectedH
 
 ## Gesture recognition
 
-Both **fist** and **pinch** trigger the same map actions — users can use whichever is more comfortable.
+Both **fist** and **pinch** trigger the same map actions, users can use whichever is more comfortable.
 
 | Gesture | Detection rule | Map action |
 | --- | --- | --- |
@@ -81,6 +81,8 @@ Both **fist** and **pinch** trigger the same map actions — users can use which
 | **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.

package/dist/GestureStateMachine.js

@@ -170,7 +170,7 @@ export class GestureStateMachine {
         const { actionDwellMs, releaseGraceMs } = this.tuning;
         const { leftHand, rightHand } = frame;
         // ── Determine desired mode for this frame ─────────────────────────────────
-        // Both fist and pinch trigger the same modes — users can choose either.
+        // 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);

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/index.js

@@ -29,17 +29,17 @@ const Y = {
   RING_MCP: 13,
   PINKY_TIP: 20,
   PINKY_MCP: 17
-}, L = 0.25, z = 0.35, E = [
+}, L = 0.25, z = 0.35, b = [
   r.INDEX_TIP,
   r.MIDDLE_TIP,
   r.RING_TIP,
   r.PINKY_TIP
-], _ = [
+], N = [
   r.INDEX_MCP,
   r.MIDDLE_MCP,
   r.RING_MCP,
   r.PINKY_MCP
-], D = {
+], w = {
   idle: "#888888",
   panning: "#00ccff",
   zooming: "#00ffcc",
@@ -47,21 +47,21 @@ const Y = {
   landmark: "rgba(255,255,255,0.6)",
   connection: "rgba(255,255,255,0.3)",
   fingertipGlow: "#4488ff"
-}, G = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm";
+}, B = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm";
 function T(i, t) {
   const e = i.x - t.x, n = i.y - t.y;
   return Math.sqrt(e * e + n * n);
 }
-function N(i) {
+function _(i) {
   const t = i[r.WRIST];
-  for (let s = 0; s < E.length; s++) {
-    const u = i[E[s]], c = i[_[s]];
+  for (let s = 0; s < b.length; s++) {
+    const u = i[b[s]], c = i[N[s]];
     if (T(u, t) < T(c, t) * 0.9)
       return !1;
   }
-  const e = w(i);
+  const e = D(i);
   if (e === 0) return !1;
-  const n = E.map((s) => i[s]);
+  const n = b.map((s) => i[s]);
   let o = 1 / 0;
   for (let s = 0; s < n.length - 1; s++) {
     const u = T(n[s], n[s + 1]);
@@ -72,39 +72,39 @@ function N(i) {
 function R(i) {
   const t = i[r.WRIST];
   let e = 0;
-  for (let n = 0; n < E.length; n++) {
-    const o = i[E[n]], a = i[_[n]];
+  for (let n = 0; n < b.length; n++) {
+    const o = i[b[n]], a = i[N[n]];
     T(o, t) < T(a, t) * 1.1 && e++;
   }
   return e >= 3;
 }
-function w(i) {
+function D(i) {
   const t = i[r.WRIST], e = i[r.MIDDLE_MCP];
   return !t || !e ? 0 : T(t, e);
 }
-function j(i, t) {
+function k(i, t) {
   const e = i[r.INDEX_TIP], n = t[r.INDEX_TIP];
   return !e || !n ? 0 : T(e, n);
 }
 function F(i) {
-  const t = w(i);
+  const t = D(i);
   if (t === 0) return !1;
   const e = i[r.THUMB_TIP], n = i[r.INDEX_TIP];
   return T(e, n) < t * L;
 }
-function B(i) {
-  const t = w(i);
+function G(i) {
+  const t = D(i);
   if (t === 0) return !1;
   const e = i[r.THUMB_TIP], n = i[r.INDEX_TIP];
   return T(e, n) < t * z;
 }
-function k(i) {
-  return i.length < 21 ? "none" : R(i) ? "fist" : F(i) ? "pinch" : N(i) ? "openPalm" : "none";
+function j(i) {
+  return i.length < 21 ? "none" : R(i) ? "fist" : F(i) ? "pinch" : _(i) ? "openPalm" : "none";
 }
-function C() {
+function M() {
   let i = !1;
   return function(e) {
-    return e.length < 21 ? (i = !1, "none") : R(e) ? (i = !1, "fist") : (i ? i = B(e) : i = F(e), i ? "pinch" : N(e) ? "openPalm" : "none");
+    return e.length < 21 ? (i = !1, "none") : R(e) ? (i = !1, "fist") : (i ? i = G(e) : i = F(e), i ? "pinch" : _(e) ? "openPalm" : "none");
   };
 }
 class $ {
@@ -118,8 +118,8 @@ class $ {
     l(this, "tuning");
     l(this, "lastVideoTime", -1);
     // One stateful classifier per hand label; persists pinch hysteresis across frames.
-    l(this, "leftClassifier", C());
-    l(this, "rightClassifier", C());
+    l(this, "leftClassifier", M());
+    l(this, "rightClassifier", M());
     this.tuning = t, this.onFrame = e;
   }
   /**
@@ -127,7 +127,7 @@ class $ {
    * Returns the video element so the overlay can render it.
    */
   async init() {
-    const t = await H.forVisionTasks(G), { HandLandmarker: e } = await import("@mediapipe/tasks-vision");
+    const t = await H.forVisionTasks(B), { HandLandmarker: e } = await import("@mediapipe/tasks-vision");
     return this.landmarker = await e.createFromOptions(t, {
       baseOptions: {
         modelAssetPath: "https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task",
@@ -174,8 +174,8 @@ class $ {
   }
   buildFrame(t, e) {
     const n = t.landmarks.map((s, u) => {
-      var m, p;
-      const c = t.handedness[u], d = ((m = c == null ? void 0 : c[0]) == null ? void 0 : m.categoryName) === "Left" ? "Left" : "Right", P = ((p = c == null ? void 0 : c[0]) == null ? void 0 : p.score) ?? 0, f = (d === "Left" ? this.leftClassifier : this.rightClassifier)(s);
+      var p, g;
+      const c = t.handedness[u], d = ((p = c == null ? void 0 : c[0]) == null ? void 0 : p.categoryName) === "Left" ? "Left" : "Right", P = ((g = c == null ? void 0 : c[0]) == null ? void 0 : g.score) ?? 0, f = (d === "Left" ? this.leftClassifier : this.rightClassifier)(s);
       return { handedness: d, score: P, landmarks: s, gesture: f };
     }), o = n.find((s) => s.handedness === "Left") ?? null, a = n.find((s) => s.handedness === "Right") ?? null;
     return { timestamp: e, hands: n, leftHand: o, rightHand: a };
@@ -199,7 +199,7 @@ class U {
     this.value = null;
   }
 }
-class M {
+class C {
   constructor(t) {
     l(this, "value", null);
     this.alpha = t;
@@ -211,7 +211,7 @@ class M {
     this.value = null;
   }
 }
-const y = class y {
+const E = class E {
   constructor(t) {
     l(this, "mode", "idle");
     l(this, "actionDwell", null);
@@ -228,7 +228,7 @@ const y = class y {
     // interrupting an ongoing single-hand gesture.
     l(this, "leftActiveFrames", 0);
     l(this, "rightActiveFrames", 0);
-    this.tuning = t, this.panSmoother = new U(t.smoothingAlpha), this.zoomSmoother = new M(t.smoothingAlpha), this.rotateSmoother = new M(t.smoothingAlpha);
+    this.tuning = t, this.panSmoother = new U(t.smoothingAlpha), this.zoomSmoother = new C(t.smoothingAlpha), this.rotateSmoother = new C(t.smoothingAlpha);
   }
   getMode() {
     return this.mode;
@@ -236,53 +236,53 @@ const y = class y {
   update(t) {
     const e = t.timestamp, { actionDwellMs: n, releaseGraceMs: o } = this.tuning, { leftHand: a, rightHand: s } = t, u = (f) => f !== null && (f.gesture === "fist" || f.gesture === "pinch"), c = u(s), h = u(a);
     this.leftActiveFrames = h ? this.leftActiveFrames + 1 : 0, this.rightActiveFrames = c ? this.rightActiveFrames + 1 : 0;
-    const d = this.leftActiveFrames >= y.ESCALATION_FRAMES && this.rightActiveFrames >= y.ESCALATION_FRAMES, g = d ? "rotating" : h && c && !d && (this.mode === "panning" || this.mode === "zooming") ? this.mode : c ? "zooming" : h ? "panning" : "idle";
+    const d = this.leftActiveFrames >= E.ESCALATION_FRAMES && this.rightActiveFrames >= E.ESCALATION_FRAMES, m = d ? "rotating" : h && c && !d && (this.mode === "panning" || this.mode === "zooming") ? this.mode : c ? "zooming" : h ? "panning" : "idle";
     if (this.mode === "idle")
-      return g !== "idle" ? this.actionDwell === null || this.actionDwell.gesture !== g ? this.actionDwell = { gesture: g, startMs: e } : e - this.actionDwell.startMs >= n && this.transitionTo(g) : this.actionDwell = null, this.buildOutput(null, null, null);
+      return m !== "idle" ? this.actionDwell === null || this.actionDwell.gesture !== m ? this.actionDwell = { gesture: m, startMs: e } : e - this.actionDwell.startMs >= n && this.transitionTo(m) : this.actionDwell = null, this.buildOutput(null, null, null);
     if (this.mode === "panning") {
       if (d)
         return this.transitionTo("rotating"), this.buildOutput(null, null, null);
-      if (g !== "panning")
+      if (m !== "panning")
         return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= o && this.transitionTo("idle"), this.buildOutput(null, null, null);
       this.releaseTimer = null;
       const f = u(a) ? a : null;
       if (!f)
         return this.transitionTo("idle"), this.buildOutput(null, null, null);
-      const m = f.landmarks[0], p = this.panSmoother.update(m.x, m.y);
+      const p = f.landmarks[0], g = this.panSmoother.update(p.x, p.y);
       let I = null;
       if (this.prevPanPos !== null) {
-        const b = p.x - this.prevPanPos.x, v = p.y - this.prevPanPos.y, A = this.tuning.panDeadzonePx / 640;
-        (Math.abs(b) > A || Math.abs(v) > A) && (I = { x: b, y: v });
+        const y = g.x - this.prevPanPos.x, v = g.y - this.prevPanPos.y, A = this.tuning.panDeadzonePx / 640;
+        (Math.abs(y) > A || Math.abs(v) > A) && (I = { x: y, y: v });
       }
-      return this.prevPanPos = p, this.buildOutput(I, null, null);
+      return this.prevPanPos = g, this.buildOutput(I, null, null);
     }
     if (this.mode === "zooming") {
       if (d)
         return this.transitionTo("rotating"), this.buildOutput(null, null, null);
-      if (g !== "zooming")
+      if (m !== "zooming")
         return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= o && this.transitionTo("idle"), this.buildOutput(null, null, null);
       if (this.releaseTimer = null, !s)
         return this.transitionTo("idle"), this.buildOutput(null, null, null);
-      const f = s.landmarks[0], m = this.zoomSmoother.update(f.y);
-      let p = null;
+      const f = s.landmarks[0], p = this.zoomSmoother.update(f.y);
+      let g = null;
       if (this.prevZoomDist !== null) {
-        const I = m - this.prevZoomDist;
-        Math.abs(I) > this.tuning.zoomDeadzoneRatio && (p = -I);
+        const I = p - this.prevZoomDist;
+        Math.abs(I) > this.tuning.zoomDeadzoneRatio && (g = -I);
       }
-      return this.prevZoomDist = m, this.buildOutput(null, p, null);
+      return this.prevZoomDist = p, this.buildOutput(null, g, null);
     }
     if (this.mode === "rotating") {
-      if (g !== "rotating")
+      if (m !== "rotating")
         return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= o && this.transitionTo("idle"), this.buildOutput(null, null, null);
       if (this.releaseTimer = null, !a || !s)
         return this.transitionTo("idle"), this.buildOutput(null, null, null);
-      const f = a.landmarks[0], m = s.landmarks[0], p = Math.atan2(m.y - f.y, m.x - f.x), I = this.rotateSmoother.update(p);
-      let b = null;
+      const f = a.landmarks[0], p = s.landmarks[0], g = Math.atan2(p.y - f.y, p.x - f.x), I = this.rotateSmoother.update(g);
+      let y = null;
       if (this.prevRotateAngle !== null) {
         let v = I - this.prevRotateAngle;
-        v > Math.PI && (v -= 2 * Math.PI), v < -Math.PI && (v += 2 * Math.PI), Math.abs(v) > 5e-3 && (b = v);
+        v > Math.PI && (v -= 2 * Math.PI), v < -Math.PI && (v += 2 * Math.PI), Math.abs(v) > 5e-3 && (y = v);
       }
-      return this.prevRotateAngle = I, this.buildOutput(null, null, b);
+      return this.prevRotateAngle = I, this.buildOutput(null, null, y);
     }
     return this.buildOutput(null, null, null);
   }
@@ -296,8 +296,8 @@ const y = class y {
     this.transitionTo("idle");
   }
 };
-l(y, "ESCALATION_FRAMES", 3);
-let S = y;
+l(E, "ESCALATION_FRAMES", 3);
+let S = E;
 const X = [
   [0, 1],
   [1, 2],
@@ -341,8 +341,11 @@ class q {
     l(this, "canvas");
     l(this, "ctx");
     l(this, "badge");
+    l(this, "resetBar");
+    l(this, "resetFill");
     l(this, "config");
-    this.config = t, this.container = document.createElement("div"), this.container.className = "ol-gesture-overlay", this.applyContainerStyles(), this.canvas = document.createElement("canvas"), this.canvas.className = "ol-gesture-canvas", this.canvas.style.cssText = "position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;", this.badge = document.createElement("div"), this.badge.className = "ol-gesture-badge ol-gesture-badge--idle", this.badge.textContent = "Idle", this.container.appendChild(this.canvas), this.container.appendChild(this.badge);
+    l(this, "lastMode", null);
+    this.config = t, this.container = document.createElement("div"), this.container.className = "ol-gesture-overlay", this.applyContainerStyles(), this.canvas = document.createElement("canvas"), this.canvas.className = "ol-gesture-canvas", this.canvas.style.cssText = "position:absolute;top:0;left:0;width:100%;height:100%;pointer-events:none;", 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 e = this.canvas.getContext("2d");
     if (!e) throw new Error("Cannot get 2D canvas context");
     this.ctx = e;
@@ -359,25 +362,30 @@ class q {
     var t;
     (t = this.container.parentElement) == null || t.removeChild(this.container);
   }
-  /** Called each frame with the latest gesture frame and mode. */
-  render(t, e) {
-    this.updateBadge(e);
-    const n = this.config.width, o = this.config.height;
-    if (this.canvas.width = n, this.canvas.height = o, this.ctx.clearRect(0, 0, n, o), t !== null)
-      for (const a of t.hands)
-        this.drawSkeleton(a.landmarks, e, a.gesture === "fist");
+  /** Called each frame with the latest gesture frame, mode, and optional reset progress (0 to 1). */
+  render(t, e, n = 0) {
+    this.updateBadge(e), this.updateResetBar(n);
+    const o = this.config.width, a = this.config.height;
+    if ((this.canvas.width !== o || this.canvas.height !== a) && (this.canvas.width = o, this.canvas.height = a), this.ctx.clearRect(0, 0, o, a), t !== null)
+      for (const s of t.hands)
+        this.drawSkeleton(s.landmarks, e, s.gesture === "fist");
+  }
+  updateResetBar(t) {
+    this.resetFill.style.width = `${t * 100}%`, this.resetBar.style.opacity = t > 0 ? "1" : "0";
   }
   drawSkeleton(t, e, n) {
     const { ctx: o } = this, a = this.config.width, s = this.config.height, u = (h) => (1 - h.x) * a, c = (h) => h.y * s;
-    o.strokeStyle = D.connection, o.lineWidth = 1.5;
+    o.strokeStyle = w.connection, o.lineWidth = 1.5;
     for (const [h, d] of X)
       !t[h] || !t[d] || (o.beginPath(), o.moveTo(u(t[h]), c(t[h])), o.lineTo(u(t[d]), c(t[d])), o.stroke());
     for (let h = 0; h < t.length; h++) {
-      const d = t[h], P = V.includes(h), g = e !== "idle" && P ? D.fingertipGlow : D.landmark;
-      o.beginPath(), o.arc(u(d), c(d), P ? 5 : 3, 0, Math.PI * 2), o.fillStyle = g, o.fill(), e !== "idle" && P && (o.shadowBlur = n ? 12 : 6, o.shadowColor = D.fingertipGlow, o.fill(), o.shadowBlur = 0);
+      const d = t[h], P = V.includes(h), m = e !== "idle" && P ? w.fingertipGlow : w.landmark;
+      o.beginPath(), o.arc(u(d), c(d), P ? 5 : 3, 0, Math.PI * 2), o.fillStyle = m, o.fill(), e !== "idle" && P && (o.shadowBlur = n ? 12 : 6, o.shadowColor = w.fingertipGlow, o.fill(), o.shadowBlur = 0);
     }
   }
   updateBadge(t) {
+    if (t === this.lastMode) return;
+    this.lastMode = t;
     const e = {
       idle: "Idle",
       panning: "Pan",
@@ -399,15 +407,15 @@ class q {
   }
 }
 export {
-  D as COLORS,
+  w as COLORS,
   Z as DEFAULT_TUNING_CONFIG,
   Y as DEFAULT_WEBCAM_CONFIG,
   $ as GestureController,
   S as GestureStateMachine,
   r as LANDMARKS,
   q as WebcamOverlay,
-  k as classifyGesture,
-  C as createHandClassifier,
-  w as getHandSize,
-  j as getTwoHandDistance
+  j as classifyGesture,
+  M as createHandClassifier,
+  D as getHandSize,
+  k as getTwoHandDistance
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@map-gesture-controls/core",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Map-agnostic hand gesture detection and state machine (MediaPipe)",
   "type": "module",
   "main": "dist/index.js",

package/dist/GestureStateMachine.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/GestureStateMachine.test.js

@@ -1,264 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { GestureStateMachine } from './GestureStateMachine.js';
-import { LANDMARKS } from './constants.js';
-// ─── Helpers ──────────────────────────────────────────────────────────────────
-const FAST_TUNING = {
-    actionDwellMs: 0, // dwell=0: transition fires on the SECOND frame (first sets timer)
-    releaseGraceMs: 0, // grace=0: idle on the SECOND frame after release
-    panDeadzonePx: 0,
-    zoomDeadzoneRatio: 0,
-    smoothingAlpha: 1, // no smoothing, raw values pass through
-    minDetectionConfidence: 0.65,
-    minTrackingConfidence: 0.65,
-    minPresenceConfidence: 0.60,
-};
-function makeLandmarks(overrides = {}) {
-    const lm = Array.from({ length: 21 }, () => ({ x: 0.5, y: 0.5, z: 0 }));
-    for (const [idx, vals] of Object.entries(overrides)) {
-        lm[Number(idx)] = { ...lm[Number(idx)], ...vals };
-    }
-    return lm;
-}
-function makeHand(gesture, landmarks = makeLandmarks()) {
-    return { handedness: 'Right', score: 1, landmarks, gesture };
-}
-function makeFrame(timestamp, leftHand, rightHand) {
-    const hands = [leftHand, rightHand].filter(Boolean);
-    return { timestamp, hands, 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
-    fsm.update(makeFrame(0, hand, null)); // dwell elapsed → panning
-}
-/**
- * Drive the FSM into 'zooming' with dwell=0 (requires two identical frames).
- * Zoom = right fist only.
- */
-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));
-}
-// ─── Tests ────────────────────────────────────────────────────────────────────
-describe('GestureStateMachine', () => {
-    let fsm;
-    beforeEach(() => {
-        fsm = new GestureStateMachine(FAST_TUNING);
-    });
-    // ── Initial state ──────────────────────────────────────────────────────────
-    it('starts in idle mode', () => {
-        expect(fsm.getMode()).toBe('idle');
-    });
-    // ── idle → panning ─────────────────────────────────────────────────────────
-    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 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('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 left fist is released (releaseGraceMs=0)', () => {
-        enterPanning(fsm);
-        expect(fsm.getMode()).toBe('panning');
-        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');
-    });
-    // ── zooming → idle ─────────────────────────────────────────────────────────
-    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');
-        fsm.update(makeFrame(0, fistHand, null)); // dwell starts
-        const out = fsm.update(makeFrame(0, fistHand, null)); // enters panning, sets prevPos
-        expect(out.panDelta).toBeNull();
-    });
-    it('emits panDelta once a previous position is established', () => {
-        const wristPos1 = { x: 0.3, y: 0.4, z: 0 };
-        const wristPos2 = { x: 0.35, y: 0.45, z: 0 };
-        const lm1 = makeLandmarks({ [LANDMARKS.WRIST]: wristPos1 });
-        const lm2 = makeLandmarks({ [LANDMARKS.WRIST]: wristPos2 });
-        // Frame 1: start dwell (idle)
-        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
-        fsm.update(makeFrame(1, makeHand('fist', lm1), null));
-        // 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();
-        expect(out.panDelta.x).toBeCloseTo(wristPos2.x - wristPos1.x);
-        expect(out.panDelta.y).toBeCloseTo(wristPos2.y - wristPos1.y);
-    });
-    // ── zoomDelta output ───────────────────────────────────────────────────────
-    it('emits no zoomDelta on the first zooming frame', () => {
-        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 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, 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, 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); // 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', () => {
-        enterPanning(fsm);
-        expect(fsm.getMode()).toBe('panning');
-        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 });
-        const fistHand = makeHand('fist');
-        const out1 = slowFsm.update(makeFrame(0, fistHand, null));
-        expect(out1.mode).toBe('idle');
-        const out2 = slowFsm.update(makeFrame(100, fistHand, null)); // 100 ms < 200 ms
-        expect(out2.mode).toBe('idle');
-        const out3 = slowFsm.update(makeFrame(200, fistHand, null)); // 200 ms >= 200 ms
-        expect(out3.mode).toBe('panning');
-    });
-    // ── release grace period ───────────────────────────────────────────────────
-    it('stays in panning during release grace period', () => {
-        const graceFsm = new GestureStateMachine({ ...FAST_TUNING, releaseGraceMs: 100 });
-        enterPanning(graceFsm);
-        expect(graceFsm.getMode()).toBe('panning');
-        const out1 = graceFsm.update(makeFrame(1, null, null)); // grace starts
-        expect(out1.mode).toBe('panning');
-        const out2 = graceFsm.update(makeFrame(50, null, null)); // 50 ms < 100 ms
-        expect(out2.mode).toBe('panning');
-        const out3 = graceFsm.update(makeFrame(101, null, null)); // 101 ms >= 100 ms
-        expect(out3.mode).toBe('idle');
-    });
-});

package/dist/gestureClassifier.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/gestureClassifier.test.js

@@ -1,98 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { classifyGesture, getTwoHandDistance } from './gestureClassifier.js';
-import { LANDMARKS } from './constants.js';
-/**
- * Build a flat array of 21 landmarks, all at (0.5, 0.5, 0).
- * Individual landmarks can be overridden via the `overrides` map.
- */
-function makeLandmarks(overrides = {}) {
-    const lm = Array.from({ length: 21 }, () => ({ x: 0.5, y: 0.5, z: 0 }));
-    for (const [idx, vals] of Object.entries(overrides)) {
-        lm[Number(idx)] = { ...lm[Number(idx)], ...vals };
-    }
-    return lm;
-}
-/**
- * Build an open-palm hand.
- *
- * Strategy: place wrist at origin, MCP joints at y=0.3, fingertips at y=0.1
- * (tips are farther from the wrist than MCPs) and spread them horizontally
- * so adjacent-tip distance >> 18% of hand size.
- *
- * Hand size = dist(wrist, middle-MCP) = dist({0,0},{0,0.3}) = 0.3
- * Adjacent tip spread = 0.1 per finger → 0.1 > 0.3 * 0.18 = 0.054 ✓
- */
-function makeOpenPalmLandmarks() {
-    const lm = makeLandmarks();
-    // Wrist at origin
-    lm[LANDMARKS.WRIST] = { x: 0.5, y: 0.8, z: 0 };
-    // MCP joints
-    lm[LANDMARKS.INDEX_MCP] = { x: 0.3, y: 0.5, z: 0 };
-    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
-    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 };
-    lm[LANDMARKS.PINKY_TIP] = { x: 0.65, y: 0.1, z: 0 };
-    return lm;
-}
-/**
- * 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.
- *
- * dist(tip, wrist) ≈ 0.1 < dist(mcp, wrist) * 1.1 ≈ 0.33  ✓
- */
-function makeFistLandmarks() {
-    const lm = makeLandmarks();
-    lm[LANDMARKS.WRIST] = { x: 0.5, y: 0.8, z: 0 };
-    lm[LANDMARKS.INDEX_MCP] = { x: 0.4, y: 0.5, z: 0 };
-    lm[LANDMARKS.MIDDLE_MCP] = { x: 0.45, y: 0.5, z: 0 };
-    lm[LANDMARKS.RING_MCP] = { x: 0.5, y: 0.5, z: 0 };
-    lm[LANDMARKS.PINKY_MCP] = { x: 0.55, y: 0.5, z: 0 };
-    lm[LANDMARKS.INDEX_TIP] = { x: 0.4, y: 0.72, z: 0 };
-    lm[LANDMARKS.MIDDLE_TIP] = { x: 0.45, y: 0.72, z: 0 };
-    lm[LANDMARKS.RING_TIP] = { x: 0.5, y: 0.72, z: 0 };
-    lm[LANDMARKS.PINKY_TIP] = { x: 0.55, y: 0.72, z: 0 };
-    return lm;
-}
-// ─── classifyGesture ──────────────────────────────────────────────────────────
-describe('classifyGesture', () => {
-    it('returns "none" when fewer than 21 landmarks are provided', () => {
-        expect(classifyGesture([])).toBe('none');
-        expect(classifyGesture(makeLandmarks().slice(0, 20))).toBe('none');
-    });
-    it('classifies an open palm as "openPalm"', () => {
-        expect(classifyGesture(makeOpenPalmLandmarks())).toBe('openPalm');
-    });
-    it('classifies a fist as "fist"', () => {
-        expect(classifyGesture(makeFistLandmarks())).toBe('fist');
-    });
-    it('returns "none" for an ambiguous / neutral hand', () => {
-        // 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', () => {
-        // The function checks fist first, so a fist should never become openPalm.
-        const fist = makeFistLandmarks();
-        expect(classifyGesture(fist)).toBe('fist');
-    });
-});
-// ─── getTwoHandDistance ───────────────────────────────────────────────────────
-describe('getTwoHandDistance', () => {
-    it('returns the Euclidean distance between the two index fingertips', () => {
-        const handA = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.0, y: 0.0, z: 0 } });
-        const handB = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.3, y: 0.4, z: 0 } });
-        expect(getTwoHandDistance(handA, handB)).toBeCloseTo(0.5);
-    });
-    it('returns 0 when the index fingertips are at the same position', () => {
-        const hand = makeLandmarks({ [LANDMARKS.INDEX_TIP]: { x: 0.5, y: 0.5, z: 0 } });
-        expect(getTwoHandDistance(hand, hand)).toBe(0);
-    });
-    it('returns 0 when landmarks array is empty (missing tips)', () => {
-        expect(getTwoHandDistance([], [])).toBe(0);
-    });
-});