@map-gesture-controls/core 0.1.3

package/dist/index.js

@@ -0,0 +1,360 @@
+var w = Object.defineProperty;
+var b = (o, t, e) => t in o ? w(o, t, { enumerable: !0, configurable: !0, writable: !0, value: e }) : o[t] = e;
+var a = (o, t, e) => b(o, typeof t != "symbol" ? t + "" : t, e);
+import { FilesetResolver as E } from "@mediapipe/tasks-vision";
+const L = {
+  enabled: !0,
+  mode: "corner",
+  opacity: 0.85,
+  position: "bottom-right",
+  width: 320,
+  height: 240
+}, H = {
+  actionDwellMs: 80,
+  releaseGraceMs: 150,
+  panDeadzonePx: 10,
+  zoomDeadzoneRatio: 5e-3,
+  smoothingAlpha: 0.5,
+  minDetectionConfidence: 0.65,
+  minTrackingConfidence: 0.65,
+  minPresenceConfidence: 0.6
+}, h = {
+  WRIST: 0,
+  THUMB_TIP: 4,
+  INDEX_TIP: 8,
+  INDEX_MCP: 5,
+  MIDDLE_TIP: 12,
+  MIDDLE_MCP: 9,
+  RING_TIP: 16,
+  RING_MCP: 13,
+  PINKY_TIP: 20,
+  PINKY_MCP: 17
+}, I = [
+  h.INDEX_TIP,
+  h.MIDDLE_TIP,
+  h.RING_TIP,
+  h.PINKY_TIP
+], y = [
+  h.INDEX_MCP,
+  h.MIDDLE_MCP,
+  h.RING_MCP,
+  h.PINKY_MCP
+], T = {
+  idle: "#888888",
+  panning: "#00ccff",
+  zooming: "#00ffcc",
+  landmark: "rgba(255,255,255,0.6)",
+  connection: "rgba(255,255,255,0.3)",
+  fingertipGlow: "#4488ff"
+}, C = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm";
+function g(o, t) {
+  const e = o.x - t.x, n = o.y - t.y;
+  return Math.sqrt(e * e + n * n);
+}
+function M(o) {
+  const t = o[h.WRIST];
+  for (let i = 0; i < I.length; i++) {
+    const d = o[I[i]], c = o[y[i]];
+    if (g(d, t) < g(c, t) * 0.9)
+      return !1;
+  }
+  const e = N(o);
+  if (e === 0) return !1;
+  const n = I.map((i) => o[i]);
+  let s = 1 / 0;
+  for (let i = 0; i < n.length - 1; i++) {
+    const d = g(n[i], n[i + 1]);
+    d < s && (s = d);
+  }
+  return s >= e * 0.18;
+}
+function _(o) {
+  const t = o[h.WRIST];
+  let e = 0;
+  for (let n = 0; n < I.length; n++) {
+    const s = o[I[n]], l = o[y[n]];
+    g(s, t) < g(l, t) * 1.1 && e++;
+  }
+  return e >= 3;
+}
+function N(o) {
+  const t = o[h.WRIST], e = o[h.MIDDLE_MCP];
+  return !t || !e ? 0 : g(t, e);
+}
+function S(o, t) {
+  const e = o[h.INDEX_TIP], n = t[h.INDEX_TIP];
+  return !e || !n ? 0 : g(e, n);
+}
+function x(o) {
+  return o.length < 21 ? "none" : _(o) ? "fist" : M(o) ? "openPalm" : "none";
+}
+class k {
+  constructor(t, e) {
+    a(this, "landmarker", null);
+    a(this, "videoEl", null);
+    a(this, "stream", null);
+    a(this, "rafHandle", null);
+    a(this, "running", !1);
+    a(this, "onFrame");
+    a(this, "tuning");
+    a(this, "lastVideoTime", -1);
+    this.tuning = t, this.onFrame = e;
+  }
+  /**
+   * Initialise MediaPipe and request webcam access.
+   * Returns the video element so the overlay can render it.
+   */
+  async init() {
+    const t = await E.forVisionTasks(C), { 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",
+        delegate: "GPU"
+      },
+      runningMode: "VIDEO",
+      numHands: 2,
+      minHandDetectionConfidence: this.tuning.minDetectionConfidence,
+      minHandPresenceConfidence: this.tuning.minPresenceConfidence,
+      minTrackingConfidence: this.tuning.minTrackingConfidence
+    }), this.videoEl = document.createElement("video"), this.videoEl.setAttribute("playsinline", ""), this.videoEl.setAttribute("autoplay", ""), this.videoEl.muted = !0, this.videoEl.width = 640, this.videoEl.height = 480, this.stream = await navigator.mediaDevices.getUserMedia({
+      video: { width: 640, height: 480, facingMode: "user" }
+    }), this.videoEl.srcObject = this.stream, await new Promise((n) => {
+      this.videoEl.addEventListener("loadeddata", () => n(), { once: !0 });
+    }), this.videoEl;
+  }
+  start() {
+    this.running || (this.running = !0, this.loop());
+  }
+  stop() {
+    this.running = !1, this.rafHandle !== null && (cancelAnimationFrame(this.rafHandle), this.rafHandle = null);
+  }
+  destroy() {
+    var t, e;
+    this.stop(), (t = this.stream) == null || t.getTracks().forEach((n) => n.stop()), (e = this.landmarker) == null || e.close(), this.landmarker = null, this.videoEl = null, this.stream = null;
+  }
+  loop() {
+    this.running && (this.rafHandle = requestAnimationFrame(() => this.loop()), this.processFrame());
+  }
+  processFrame() {
+    const t = this.videoEl, e = this.landmarker;
+    if (!t || !e || t.readyState < 2) return;
+    const n = performance.now();
+    if (t.currentTime === this.lastVideoTime) return;
+    this.lastVideoTime = t.currentTime;
+    let s;
+    try {
+      s = e.detectForVideo(t, n);
+    } catch {
+      return;
+    }
+    const l = this.buildFrame(s, n);
+    this.onFrame(l);
+  }
+  buildFrame(t, e) {
+    const n = t.landmarks.map((i, d) => {
+      var f, v;
+      const c = t.handedness[d], u = ((f = c == null ? void 0 : c[0]) == null ? void 0 : f.categoryName) === "Left" ? "Left" : "Right", m = ((v = c == null ? void 0 : c[0]) == null ? void 0 : v.score) ?? 0, p = x(i);
+      return { handedness: u, score: m, landmarks: i, gesture: p };
+    }), s = n.find((i) => i.handedness === "Left") ?? null, l = n.find((i) => i.handedness === "Right") ?? null;
+    return { timestamp: e, hands: n, leftHand: s, rightHand: l };
+  }
+  getVideoElement() {
+    return this.videoEl;
+  }
+}
+class R {
+  constructor(t) {
+    a(this, "value", null);
+    this.alpha = t;
+  }
+  update(t, e) {
+    return this.value === null ? this.value = { x: t, y: e } : this.value = {
+      x: this.alpha * t + (1 - this.alpha) * this.value.x,
+      y: this.alpha * e + (1 - this.alpha) * this.value.y
+    }, this.value;
+  }
+  reset() {
+    this.value = null;
+  }
+}
+class F {
+  constructor(t) {
+    a(this, "value", null);
+    this.alpha = t;
+  }
+  update(t) {
+    return this.value === null ? this.value = t : this.value = this.alpha * t + (1 - this.alpha) * this.value, this.value;
+  }
+  reset() {
+    this.value = null;
+  }
+}
+class B {
+  constructor(t) {
+    a(this, "mode", "idle");
+    a(this, "actionDwell", null);
+    a(this, "releaseTimer", null);
+    a(this, "panSmoother");
+    a(this, "prevPanPos", null);
+    a(this, "zoomSmoother");
+    a(this, "prevZoomDist", null);
+    this.tuning = t, this.panSmoother = new R(t.smoothingAlpha), this.zoomSmoother = new F(t.smoothingAlpha);
+  }
+  getMode() {
+    return this.mode;
+  }
+  update(t) {
+    const e = t.timestamp, { actionDwellMs: n, releaseGraceMs: s } = this.tuning, { leftHand: l, rightHand: i } = t, d = l !== null && i !== null && l.gesture === "openPalm" && i.gesture === "openPalm", c = l !== null && l.gesture === "fist" && i === null || i !== null && i.gesture === "fist" && l === null, r = d ? "zooming" : c ? "panning" : "idle";
+    if (this.mode === "idle")
+      return r !== "idle" ? this.actionDwell === null || this.actionDwell.gesture !== r ? this.actionDwell = { gesture: r, startMs: e } : e - this.actionDwell.startMs >= n && this.transitionTo(r) : this.actionDwell = null, this.buildOutput(null, null);
+    if (this.mode === "panning") {
+      if (r !== "panning")
+        return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= s && this.transitionTo("idle"), this.buildOutput(null, null);
+      this.releaseTimer = null;
+      const u = (l == null ? void 0 : l.gesture) === "fist" ? l : i;
+      if (!u)
+        return this.transitionTo("idle"), this.buildOutput(null, null);
+      const m = u.landmarks[0], p = this.panSmoother.update(m.x, m.y);
+      let f = null;
+      if (this.prevPanPos !== null) {
+        const v = p.x - this.prevPanPos.x, P = p.y - this.prevPanPos.y, D = this.tuning.panDeadzonePx / 640;
+        (Math.abs(v) > D || Math.abs(P) > D) && (f = { x: v, y: P });
+      }
+      return this.prevPanPos = p, this.buildOutput(f, null);
+    }
+    if (this.mode === "zooming") {
+      if (r !== "zooming")
+        return this.releaseTimer === null ? this.releaseTimer = e : e - this.releaseTimer >= s && this.transitionTo("idle"), this.buildOutput(null, null);
+      if (this.releaseTimer = null, !l || !i)
+        return this.transitionTo("idle"), this.buildOutput(null, null);
+      const u = S(l.landmarks, i.landmarks), m = this.zoomSmoother.update(u);
+      let p = null;
+      if (this.prevZoomDist !== null) {
+        const f = m - this.prevZoomDist;
+        Math.abs(f) > this.tuning.zoomDeadzoneRatio && (p = f);
+      }
+      return this.prevZoomDist = m, this.buildOutput(null, p);
+    }
+    return this.buildOutput(null, null);
+  }
+  transitionTo(t) {
+    this.mode = t, this.releaseTimer = null, this.actionDwell = null, t !== "panning" && (this.panSmoother.reset(), this.prevPanPos = null), t !== "zooming" && (this.zoomSmoother.reset(), this.prevZoomDist = null);
+  }
+  buildOutput(t, e) {
+    return { mode: this.mode, panDelta: t, zoomDelta: e };
+  }
+  reset() {
+    this.transitionTo("idle");
+  }
+}
+const O = [
+  [0, 1],
+  [1, 2],
+  [2, 3],
+  [3, 4],
+  // thumb
+  [0, 5],
+  [5, 6],
+  [6, 7],
+  [7, 8],
+  // index
+  [0, 9],
+  [9, 10],
+  [10, 11],
+  [11, 12],
+  // middle
+  [0, 13],
+  [13, 14],
+  [14, 15],
+  [15, 16],
+  // ring
+  [0, 17],
+  [17, 18],
+  [18, 19],
+  [19, 20],
+  // pinky
+  [5, 9],
+  [9, 13],
+  [13, 17]
+  // palm cross
+], z = [
+  h.THUMB_TIP,
+  h.INDEX_TIP,
+  h.MIDDLE_TIP,
+  h.RING_TIP,
+  h.PINKY_TIP
+];
+class U {
+  constructor(t) {
+    a(this, "container");
+    a(this, "canvas");
+    a(this, "ctx");
+    a(this, "badge");
+    a(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);
+    const e = this.canvas.getContext("2d");
+    if (!e) throw new Error("Cannot get 2D canvas context");
+    this.ctx = e;
+  }
+  /** Attach video element produced by GestureController */
+  attachVideo(t) {
+    t.className = "ol-gesture-video", t.style.cssText = "position:absolute;top:0;left:0;width:100%;height:100%;object-fit:cover;transform:scaleX(-1);", this.container.insertBefore(t, this.canvas);
+  }
+  /** Mount the overlay into the given parent (usually document.body or map container) */
+  mount(t) {
+    t.appendChild(this.container);
+  }
+  unmount() {
+    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, s = this.config.height;
+    if (this.canvas.width = n, this.canvas.height = s, this.ctx.clearRect(0, 0, n, s), t !== null)
+      for (const l of t.hands)
+        this.drawSkeleton(l.landmarks, e, l.gesture === "fist");
+  }
+  drawSkeleton(t, e, n) {
+    const { ctx: s } = this, l = this.config.width, i = this.config.height, d = (r) => (1 - r.x) * l, c = (r) => r.y * i;
+    s.strokeStyle = T.connection, s.lineWidth = 1.5;
+    for (const [r, u] of O)
+      !t[r] || !t[u] || (s.beginPath(), s.moveTo(d(t[r]), c(t[r])), s.lineTo(d(t[u]), c(t[u])), s.stroke());
+    for (let r = 0; r < t.length; r++) {
+      const u = t[r], m = z.includes(r), p = e !== "idle" && m ? T.fingertipGlow : T.landmark;
+      s.beginPath(), s.arc(d(u), c(u), m ? 5 : 3, 0, Math.PI * 2), s.fillStyle = p, s.fill(), e !== "idle" && m && (s.shadowBlur = n ? 12 : 6, s.shadowColor = T.fingertipGlow, s.fill(), s.shadowBlur = 0);
+    }
+  }
+  updateBadge(t) {
+    const e = {
+      idle: "Idle",
+      panning: "Pan",
+      zooming: "Zoom"
+    };
+    this.badge.textContent = e[t], this.badge.className = `ol-gesture-badge ol-gesture-badge--${t}`;
+  }
+  applyContainerStyles() {
+    const { mode: t, position: e, width: n, height: s, opacity: l } = this.config;
+    if (this.container.style.cssText = "", this.container.style.position = "fixed", this.container.style.zIndex = "9999", this.container.style.overflow = "hidden", this.container.style.borderRadius = "8px", this.container.style.opacity = String(l), this.container.style.display = t === "hidden" ? "none" : "block", t === "corner") {
+      this.container.style.width = `${n}px`, this.container.style.height = `${s}px`;
+      const i = "16px";
+      e === "bottom-right" ? (this.container.style.bottom = i, this.container.style.right = i) : e === "bottom-left" ? (this.container.style.bottom = i, this.container.style.left = i) : e === "top-right" ? (this.container.style.top = i, this.container.style.right = i) : (this.container.style.top = i, this.container.style.left = i);
+    } else t === "full" && (this.container.style.top = "0", this.container.style.left = "0", this.container.style.width = "100vw", this.container.style.height = "100vh", this.container.style.borderRadius = "0");
+  }
+  updateConfig(t) {
+    Object.assign(this.config, t), this.applyContainerStyles();
+  }
+}
+export {
+  T as COLORS,
+  H as DEFAULT_TUNING_CONFIG,
+  L as DEFAULT_WEBCAM_CONFIG,
+  k as GestureController,
+  B as GestureStateMachine,
+  h as LANDMARKS,
+  U as WebcamOverlay,
+  x as classifyGesture,
+  N as getHandSize,
+  S as getTwoHandDistance
+};

package/dist/types.d.ts

@@ -0,0 +1,47 @@
+export type GestureMode = 'idle' | 'panning' | 'zooming';
+export type HandednessLabel = 'Left' | 'Right';
+export type GestureType = 'openPalm' | 'fist' | 'none';
+export interface Point2D {
+    x: number;
+    y: number;
+}
+export interface HandLandmark {
+    x: number;
+    y: number;
+    z: number;
+}
+export interface DetectedHand {
+    handedness: HandednessLabel;
+    score: number;
+    landmarks: HandLandmark[];
+    gesture: GestureType;
+}
+export interface GestureFrame {
+    timestamp: number;
+    hands: DetectedHand[];
+    leftHand: DetectedHand | null;
+    rightHand: DetectedHand | null;
+}
+export interface WebcamConfig {
+    enabled: boolean;
+    /** 'full' | 'corner' | 'hidden' */
+    mode: 'full' | 'corner' | 'hidden';
+    opacity: number;
+    position: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    width: number;
+    height: number;
+}
+export interface TuningConfig {
+    actionDwellMs: number;
+    releaseGraceMs: number;
+    panDeadzonePx: number;
+    zoomDeadzoneRatio: number;
+    smoothingAlpha: number;
+    minDetectionConfidence: number;
+    minTrackingConfidence: number;
+    minPresenceConfidence: number;
+}
+export interface SmoothedPoint {
+    x: number;
+    y: number;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@map-gesture-controls/core",
+  "version": "0.1.3",
+  "description": "Map-agnostic hand gesture detection and state machine (MediaPipe)",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./style.css": "./dist/style.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build:lib": "tsc -p tsconfig.lib.json && vite build --config vite.lib.config.ts",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mediapipe/tasks-vision": "^0.10.14"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.5",
+    "vite": "^5.2.11"
+  },
+  "keywords": [
+    "mediapipe",
+    "hand-gestures",
+    "gesture-detection"
+  ],
+  "overrides": {
+    "esbuild": "^0.25.0"
+  },
+  "license": "MIT"
+}