@map-gesture-controls/core 0.1.3

package/dist/WebcamOverlay.js

@@ -0,0 +1,194 @@
+import { COLORS, LANDMARKS } from './constants.js';
+// MediaPipe hand connection pairs (landmark index pairs)
+const HAND_CONNECTIONS = [
+    [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
+];
+const FINGERTIP_LANDMARKS = [
+    LANDMARKS.THUMB_TIP,
+    LANDMARKS.INDEX_TIP,
+    LANDMARKS.MIDDLE_TIP,
+    LANDMARKS.RING_TIP,
+    LANDMARKS.PINKY_TIP,
+];
+/**
+ * WebcamOverlay
+ *
+ * Manages a DOM container with:
+ *   - <video> element (webcam feed)
+ *   - <canvas> for landmark drawing
+ *   - mode badge
+ *
+ * Supports 'corner', 'full', and 'hidden' modes.
+ */
+export class WebcamOverlay {
+    constructor(config) {
+        Object.defineProperty(this, "container", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "canvas", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "ctx", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "badge", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.config = config;
+        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 ctx = this.canvas.getContext('2d');
+        if (!ctx)
+            throw new Error('Cannot get 2D canvas context');
+        this.ctx = ctx;
+    }
+    /** Attach video element produced by GestureController */
+    attachVideo(video) {
+        video.className = 'ol-gesture-video';
+        video.style.cssText =
+            'position:absolute;top:0;left:0;width:100%;height:100%;object-fit:cover;transform:scaleX(-1);';
+        this.container.insertBefore(video, this.canvas);
+    }
+    /** Mount the overlay into the given parent (usually document.body or map container) */
+    mount(parent) {
+        parent.appendChild(this.container);
+    }
+    unmount() {
+        this.container.parentElement?.removeChild(this.container);
+    }
+    /** Called each frame with the latest gesture frame and mode. */
+    render(frame, mode) {
+        this.updateBadge(mode);
+        const w = this.config.width;
+        const h = this.config.height;
+        this.canvas.width = w;
+        this.canvas.height = h;
+        this.ctx.clearRect(0, 0, w, h);
+        if (frame === null)
+            return;
+        for (const hand of frame.hands) {
+            this.drawSkeleton(hand.landmarks, mode, hand.gesture === 'fist');
+        }
+    }
+    drawSkeleton(landmarks, mode, isActionHand) {
+        const { ctx } = this;
+        const w = this.config.width;
+        const h = this.config.height;
+        // Mirror x because video is mirrored
+        const px = (lm) => (1 - lm.x) * w;
+        const py = (lm) => lm.y * h;
+        // Draw connections
+        ctx.strokeStyle = COLORS.connection;
+        ctx.lineWidth = 1.5;
+        for (const [a, b] of HAND_CONNECTIONS) {
+            if (!landmarks[a] || !landmarks[b])
+                continue;
+            ctx.beginPath();
+            ctx.moveTo(px(landmarks[a]), py(landmarks[a]));
+            ctx.lineTo(px(landmarks[b]), py(landmarks[b]));
+            ctx.stroke();
+        }
+        // Draw landmark dots
+        for (let i = 0; i < landmarks.length; i++) {
+            const lm = landmarks[i];
+            const isTip = FINGERTIP_LANDMARKS.includes(i);
+            const color = mode !== 'idle' && isTip
+                ? COLORS.fingertipGlow
+                : COLORS.landmark;
+            ctx.beginPath();
+            ctx.arc(px(lm), py(lm), isTip ? 5 : 3, 0, Math.PI * 2);
+            ctx.fillStyle = color;
+            ctx.fill();
+            // Glow effect on fingertips when active
+            if (mode !== 'idle' && isTip) {
+                ctx.shadowBlur = isActionHand ? 12 : 6;
+                ctx.shadowColor = COLORS.fingertipGlow;
+                ctx.fill();
+                ctx.shadowBlur = 0;
+            }
+        }
+    }
+    updateBadge(mode) {
+        const labels = {
+            idle: 'Idle',
+            panning: 'Pan',
+            zooming: 'Zoom',
+        };
+        this.badge.textContent = labels[mode];
+        this.badge.className = `ol-gesture-badge ol-gesture-badge--${mode}`;
+    }
+    applyContainerStyles() {
+        const { mode, position, width, height, opacity } = this.config;
+        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(opacity);
+        this.container.style.display = mode === 'hidden' ? 'none' : 'block';
+        if (mode === 'corner') {
+            this.container.style.width = `${width}px`;
+            this.container.style.height = `${height}px`;
+            const margin = '16px';
+            if (position === 'bottom-right') {
+                this.container.style.bottom = margin;
+                this.container.style.right = margin;
+            }
+            else if (position === 'bottom-left') {
+                this.container.style.bottom = margin;
+                this.container.style.left = margin;
+            }
+            else if (position === 'top-right') {
+                this.container.style.top = margin;
+                this.container.style.right = margin;
+            }
+            else {
+                this.container.style.top = margin;
+                this.container.style.left = margin;
+            }
+        }
+        else if (mode === '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(config) {
+        Object.assign(this.config, config);
+        this.applyContainerStyles();
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,26 @@
+import type { WebcamConfig, TuningConfig } from './types.js';
+export declare const DEFAULT_WEBCAM_CONFIG: WebcamConfig;
+export declare const DEFAULT_TUNING_CONFIG: TuningConfig;
+export declare const LANDMARKS: {
+    readonly WRIST: 0;
+    readonly THUMB_TIP: 4;
+    readonly INDEX_TIP: 8;
+    readonly INDEX_MCP: 5;
+    readonly MIDDLE_TIP: 12;
+    readonly MIDDLE_MCP: 9;
+    readonly RING_TIP: 16;
+    readonly RING_MCP: 13;
+    readonly PINKY_TIP: 20;
+    readonly PINKY_MCP: 17;
+};
+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 landmark: "rgba(255,255,255,0.6)";
+    readonly connection: "rgba(255,255,255,0.3)";
+    readonly fingertipGlow: "#4488ff";
+};
+export declare const MEDIAPIPE_WASM_URL = "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm";

package/dist/constants.js

@@ -0,0 +1,54 @@
+export const DEFAULT_WEBCAM_CONFIG = {
+    enabled: true,
+    mode: 'corner',
+    opacity: 0.85,
+    position: 'bottom-right',
+    width: 320,
+    height: 240,
+};
+export const DEFAULT_TUNING_CONFIG = {
+    actionDwellMs: 80,
+    releaseGraceMs: 150,
+    panDeadzonePx: 10,
+    zoomDeadzoneRatio: 0.005,
+    smoothingAlpha: 0.5,
+    minDetectionConfidence: 0.65,
+    minTrackingConfidence: 0.65,
+    minPresenceConfidence: 0.60,
+};
+// MediaPipe landmark indices
+export const LANDMARKS = {
+    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,
+};
+// Fingertip indices for open-palm detection
+export const FINGERTIP_INDICES = [
+    LANDMARKS.INDEX_TIP,
+    LANDMARKS.MIDDLE_TIP,
+    LANDMARKS.RING_TIP,
+    LANDMARKS.PINKY_TIP,
+];
+export const FINGER_BASE_INDICES = [
+    LANDMARKS.INDEX_MCP,
+    LANDMARKS.MIDDLE_MCP,
+    LANDMARKS.RING_MCP,
+    LANDMARKS.PINKY_MCP,
+];
+// Visual colours
+export const COLORS = {
+    idle: '#888888',
+    panning: '#00ccff',
+    zooming: '#00ffcc',
+    landmark: 'rgba(255,255,255,0.6)',
+    connection: 'rgba(255,255,255,0.3)',
+    fingertipGlow: '#4488ff',
+};
+export const MEDIAPIPE_WASM_URL = 'https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.14/wasm';

package/dist/gestureClassifier.d.ts

@@ -0,0 +1,22 @@
+import type { HandLandmark, GestureType } from './types.js';
+/**
+ * Returns the apparent 2D size of the hand: wrist-to-middle-MCP distance
+ * in normalised screen space (0–1). Used as a depth proxy — hand grows
+ * larger as it moves toward the camera.
+ */
+export declare function getHandSize(landmarks: HandLandmark[]): number;
+/**
+ * Returns the Euclidean distance between the index fingertips of two hands
+ * in normalised screen space (0–1). Used as the two-hand zoom metric —
+ * hands moving apart = positive delta = zoom in.
+ */
+export declare function getTwoHandDistance(landmarksA: HandLandmark[], landmarksB: HandLandmark[]): number;
+/**
+ * Classify the gesture for a single hand from its landmarks.
+ *
+ * Priority: fist > openPalm > none
+ *
+ * Fist: most fingers curled
+ * Open palm: all fingers extended
+ */
+export declare function classifyGesture(landmarks: HandLandmark[]): GestureType;

package/dist/gestureClassifier.js

@@ -0,0 +1,110 @@
+import { LANDMARKS, FINGERTIP_INDICES, FINGER_BASE_INDICES } from './constants.js';
+/**
+ * Euclidean distance between two landmarks (ignoring Z).
+ */
+function dist(a, b) {
+    const dx = a.x - b.x;
+    const dy = a.y - b.y;
+    return Math.sqrt(dx * dx + dy * dy);
+}
+/**
+ * Returns true if all four fingers (index–pinky) are extended AND spread apart.
+ *
+ * "Extended": tip is farther from the wrist than its MCP joint (allows slightly
+ * bent fingers — the 0.9 factor gives ~10% slack).
+ *
+ * "Spread": the minimum distance between any two adjacent fingertips (index–middle,
+ * middle–ring, ring–pinky) must be at least spreadThreshold × handSize. Using the
+ * minimum rather than the mean catches duck/pinch shapes: in a duck the adjacent tips
+ * touch (~2–8% of handSize) even though the outer pair (index↔pinky) stays far apart.
+ * A natural open hand keeps even adjacent tips ~20–35% of handSize apart.
+ * Threshold of 0.18 separates the two with comfortable margin.
+ */
+function areAllFingersExtended(landmarks) {
+    const wrist = landmarks[LANDMARKS.WRIST];
+    for (let i = 0; i < FINGERTIP_INDICES.length; i++) {
+        const tip = landmarks[FINGERTIP_INDICES[i]];
+        const mcp = landmarks[FINGER_BASE_INDICES[i]];
+        if (dist(tip, wrist) < dist(mcp, wrist) * 0.9) {
+            return false;
+        }
+    }
+    // Spread check: minimum pairwise distance between adjacent fingertips vs hand size.
+    // Using the minimum (not mean) catches duck/pinch shapes where adjacent fingertips
+    // touch — the mean can stay high because the outer pair (index↔pinky) is still far
+    // apart, but the minimum collapses to near zero when any two tips cluster together.
+    // A natural open hand has even adjacent tips ~20–35% of handSize apart.
+    // A duck has adjacent tips at ~2–8% of handSize. Threshold of 0.18 separates them.
+    const handSize = getHandSize(landmarks);
+    if (handSize === 0)
+        return false;
+    const tips = FINGERTIP_INDICES.map((idx) => landmarks[idx]);
+    let minDist = Infinity;
+    for (let i = 0; i < tips.length - 1; i++) {
+        const d = dist(tips[i], tips[i + 1]); // only adjacent pairs (index-middle, middle-ring, ring-pinky)
+        if (d < minDist)
+            minDist = d;
+    }
+    const spreadThreshold = 0.18; // fraction of handSize; tune up/down as needed
+    return minDist >= handSize * spreadThreshold;
+}
+/**
+ * Returns true if all four fingers (index–pinky) are curled.
+ * A finger is "curled" when its tip is closer to the wrist than its MCP joint.
+ */
+function areAllFingersCurled(landmarks) {
+    const wrist = landmarks[LANDMARKS.WRIST];
+    let curledCount = 0;
+    for (let i = 0; i < FINGERTIP_INDICES.length; i++) {
+        const tip = landmarks[FINGERTIP_INDICES[i]];
+        const mcp = landmarks[FINGER_BASE_INDICES[i]];
+        if (dist(tip, wrist) < dist(mcp, wrist) * 1.1) {
+            curledCount++;
+        }
+    }
+    // At least 3 of 4 fingers must be curled to count as fist
+    return curledCount >= 3;
+}
+/**
+ * Returns the apparent 2D size of the hand: wrist-to-middle-MCP distance
+ * in normalised screen space (0–1). Used as a depth proxy — hand grows
+ * larger as it moves toward the camera.
+ */
+export function getHandSize(landmarks) {
+    const wrist = landmarks[LANDMARKS.WRIST];
+    const middleMcp = landmarks[LANDMARKS.MIDDLE_MCP];
+    if (!wrist || !middleMcp)
+        return 0;
+    return dist(wrist, middleMcp);
+}
+/**
+ * Returns the Euclidean distance between the index fingertips of two hands
+ * in normalised screen space (0–1). Used as the two-hand zoom metric —
+ * hands moving apart = positive delta = zoom in.
+ */
+export function getTwoHandDistance(landmarksA, landmarksB) {
+    const tipA = landmarksA[LANDMARKS.INDEX_TIP];
+    const tipB = landmarksB[LANDMARKS.INDEX_TIP];
+    if (!tipA || !tipB)
+        return 0;
+    return dist(tipA, tipB);
+}
+/**
+ * Classify the gesture for a single hand from its landmarks.
+ *
+ * Priority: fist > openPalm > none
+ *
+ * Fist: most fingers curled
+ * Open palm: all fingers extended
+ */
+export function classifyGesture(landmarks) {
+    if (landmarks.length < 21)
+        return 'none';
+    if (areAllFingersCurled(landmarks)) {
+        return 'fist';
+    }
+    if (areAllFingersExtended(landmarks)) {
+        return 'openPalm';
+    }
+    return 'none';
+}

package/dist/gestureClassifier.test.d.ts

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

package/dist/gestureClassifier.test.js

@@ -0,0 +1,98 @@
+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);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+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 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';