@map-gesture-controls/google-maps 0.2.0

package/README.md

@@ -0,0 +1,139 @@
+# @map-gesture-controls/google-maps
+
+[![npm version](https://img.shields.io/npm/v/@map-gesture-controls/google-maps?style=flat-square)](https://www.npmjs.com/package/@map-gesture-controls/google-maps)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Bundle size](https://img.shields.io/bundlephobia/minzip/@map-gesture-controls/google-maps?style=flat-square&label=minzipped)](https://bundlephobia.com/package/@map-gesture-controls/google-maps)
+[![TypeScript](https://img.shields.io/badge/TypeScript-typed-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
+
+**Control Google Maps with hand gestures.** No mouse, no touch, no backend. Point your webcam and use a fist or pinch to pan, zoom, and rotate. Powered by [MediaPipe](https://developers.google.com/mediapipe) hand-tracking running entirely in the browser. Your camera feed never leaves the device.
+
+## Demo
+
+Try it live at **[sanderdesnaijer.github.io/map-gesture-controls](https://sanderdesnaijer.github.io/map-gesture-controls/)**
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/sanderdesnaijer/map-gesture-controls/main/docs/public/google-maps-gesture-controls-mediapipe.gif" alt="Screen recording of the Google Maps gesture demo: a Google Maps instance with a small webcam preview; the user pans with the left fist, zooms with the right fist, and rotates with both fists, all in the browser via MediaPipe." width="720" />
+</p>
+
+## Install
+
+```bash
+npm install @map-gesture-controls/google-maps @googlemaps/js-api-loader
+npm install -D @types/google.maps
+```
+
+## Quick start
+
+```ts
+import { Loader } from '@googlemaps/js-api-loader';
+import { GestureMapController } from '@map-gesture-controls/google-maps';
+import '@map-gesture-controls/google-maps/style.css';
+
+const loader = new Loader({ apiKey: 'YOUR_API_KEY', version: 'weekly' });
+const { Map } = await loader.importLibrary('maps');
+
+const map = new Map(document.getElementById('map')!, {
+  center: { lat: 0, lng: 0 },
+  zoom: 2,
+  mapId: 'YOUR_MAP_ID', // enables vector maps (required for rotation)
+});
+
+const controller = new GestureMapController({ map });
+
+// Must be called from a user interaction (e.g. button click) for webcam permission
+await controller.start();
+
+// Later, to tear down:
+controller.stop();
+```
+
+You need a Google Maps API key and a Map ID from the [Google Cloud Console](https://console.cloud.google.com/google/maps-apis). Create the Map ID with the **Vector** map type to enable rotation support.
+
+## How it works
+
+1. **Webcam capture** - `GestureController` opens the camera and feeds each frame to MediaPipe Hand Landmarker, returning 21 3D landmarks per hand.
+2. **Gesture classification** - `GestureStateMachine` classifies frames in real time: left fist or pinch = pan, right fist or pinch = zoom (vertical movement), both hands active = rotate, anything else is idle. Dwell timers and grace periods prevent accidental triggers.
+3. **Map integration** - `GoogleMapsGestureInteraction` translates hand movement deltas into Google Maps `moveCamera()` calls for pan, zoom, and heading changes. Pan deltas are rotated by the current heading so gesture direction always matches what you see on screen, even on rotated vector maps.
+
+## Gestures
+
+Both **fist** and **pinch** (thumb and index finger touching) trigger the same actions, use whichever feels more comfortable.
+
+| Gesture | How to perform | Map action |
+| --- | --- | --- |
+| **Pan** | Left fist or pinch, move hand in any direction | Drags the map |
+| **Zoom** | Right fist or pinch, move hand up or down | Zooms in (up) or out (down) |
+| **Rotate** | Both hands fist or pinch, tilt wrists clockwise or counter-clockwise | Rotates the map |
+| **Reset** | Bring both hands together (pray/namaste), hold 1 second | Resets pan, zoom, and rotation to initial state |
+| **Idle** | Any other hand position | Map stays still |
+
+## Configuration
+
+All options are optional. Defaults work well out of the box.
+
+```ts
+const controller = new GestureMapController({
+  map,
+  webcam: {
+    position: 'top-left',   // overlay corner position
+    width: 240,
+    height: 180,
+    opacity: 0.7,
+  },
+  tuning: {
+    actionDwellMs: 40,      // ms before confirming a gesture
+    releaseGraceMs: 80,     // ms grace period after gesture ends
+    panDeadzonePx: 5,       // react to smaller movements
+    smoothingAlpha: 0.4,    // smoother but still responsive
+  },
+  debug: true,              // log gesture state to console
+});
+```
+
+See the full configuration reference in the [documentation](https://sanderdesnaijer.github.io/map-gesture-controls/).
+
+## Exports
+
+This package re-exports the entire [`@map-gesture-controls/core`](https://www.npmjs.com/package/@map-gesture-controls/core) API, so you only need one import. On top of core, it adds:
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `GestureMapController` | Class | High-level controller that wires gesture detection to a Google Maps instance |
+| `GoogleMapsGestureInteraction` | Class | Low-level Google Maps interaction for custom setups |
+| `GestureMapControllerConfig` | Type | Configuration interface |
+
+## Use cases
+
+- **Museum and exhibit kiosks** - visitors explore maps without touching a shared screen
+- **Accessibility** - hands-free map navigation for users with limited mobility
+- **Live presentations** - control a projected map from across the room
+- **Public displays** - touchless interaction in medical, retail, or transit environments
+
+## Requirements
+
+- Google Maps JavaScript API (via `@googlemaps/js-api-loader` or a script tag)
+- A Map ID with **Vector** map type for rotation support
+- `@types/google.maps` as a peer dependency
+- A modern browser with WebGL, `getUserMedia`, and WASM support
+- Chrome 111+, Edge 111+, Firefox 115+, Safari 17+
+
+## Related packages
+
+| Package | Description |
+| --- | --- |
+| [`@map-gesture-controls/core`](https://www.npmjs.com/package/@map-gesture-controls/core) | Map-agnostic gesture detection engine (included in this package) |
+| [`@map-gesture-controls/ol`](https://www.npmjs.com/package/@map-gesture-controls/ol) | OpenLayers integration |
+
+## Documentation
+
+Full docs, live demos, and API reference at **[sanderdesnaijer.github.io/map-gesture-controls](https://sanderdesnaijer.github.io/map-gesture-controls/)**
+
+## Privacy
+
+All gesture processing runs locally in the browser. No video data is sent to any server. MediaPipe WASM and model files are loaded from public CDNs.
+
+Built by [Sander de Snaijer](https://www.sanderdesnaijer.com).
+
+## License
+
+MIT

package/dist/GestureMapController.d.ts

@@ -0,0 +1,56 @@
+import type { GestureMapControllerConfig } from './types.js';
+/**
+ * GestureMapController
+ *
+ * Top-level public API for Google Maps. Wires together all subsystems:
+ *   GestureController -> GestureStateMachine -> GoogleMapsGestureInteraction
+ *                                            -> WebcamOverlay
+ *
+ * Usage:
+ *   const ctrl = new GestureMapController({ map });
+ *   await ctrl.start();
+ *   // ...
+ *   ctrl.stop();
+ */
+export declare class GestureMapController {
+    private config;
+    private gestureController;
+    private stateMachine;
+    private overlay;
+    private interaction;
+    private lastFrame;
+    private rafHandle;
+    private started;
+    private paused;
+    private resetPoseStart;
+    private resetPoseTriggered;
+    private resetPoseGraceTimer;
+    private readonly resetPoseDurationMs;
+    private readonly resetPoseGraceMs;
+    private readonly initialZoom;
+    private readonly initialCenter;
+    private readonly initialHeading;
+    constructor(userConfig: GestureMapControllerConfig);
+    /**
+     * Initialise webcam + MediaPipe, mount overlay, begin detection loop.
+     * Must be called from a user-gesture event (e.g. button click) to allow
+     * webcam permission prompt.
+     */
+    start(): Promise<void>;
+    /** Stop detection and remove overlay. Safe to call start() again afterwards. */
+    stop(): void;
+    /** Pause detection (overlay stays visible but inactive). */
+    pause(): void;
+    /** Resume after pause. */
+    resume(): void;
+    private renderLoop;
+    /**
+     * Returns true when both hands are held close together based on wrist proximity.
+     * Uses Euclidean distance between the two wrists in normalised screen-space
+     * coordinates (0 to 1). Threshold is 0.45.
+     */
+    private isPrayPose;
+    private handleVisibilityChange;
+    private resetTransientState;
+    private logDebug;
+}

package/dist/GestureMapController.js

@@ -0,0 +1,306 @@
+import { DEFAULT_WEBCAM_CONFIG, DEFAULT_TUNING_CONFIG, LANDMARKS, GestureController, GestureStateMachine, WebcamOverlay, } from '@map-gesture-controls/core';
+import { GoogleMapsGestureInteraction } from './GoogleMapsGestureInteraction.js';
+/**
+ * GestureMapController
+ *
+ * Top-level public API for Google Maps. Wires together all subsystems:
+ *   GestureController -> GestureStateMachine -> GoogleMapsGestureInteraction
+ *                                            -> WebcamOverlay
+ *
+ * Usage:
+ *   const ctrl = new GestureMapController({ map });
+ *   await ctrl.start();
+ *   // ...
+ *   ctrl.stop();
+ */
+export class GestureMapController {
+    constructor(userConfig) {
+        Object.defineProperty(this, "config", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "gestureController", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "stateMachine", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "overlay", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "interaction", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "lastFrame", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "rafHandle", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "started", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "paused", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "resetPoseStart", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "resetPoseTriggered", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "resetPoseGraceTimer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "resetPoseDurationMs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 1000
+        });
+        Object.defineProperty(this, "resetPoseGraceMs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 300
+        });
+        Object.defineProperty(this, "initialZoom", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "initialCenter", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "initialHeading", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "handleVisibilityChange", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: () => {
+                if (document.hidden) {
+                    this.pause();
+                }
+                else {
+                    this.resume();
+                }
+            }
+        });
+        const webcamConfig = { ...DEFAULT_WEBCAM_CONFIG, ...userConfig.webcam };
+        const tuningConfig = { ...DEFAULT_TUNING_CONFIG, ...userConfig.tuning };
+        this.config = {
+            map: userConfig.map,
+            webcam: webcamConfig,
+            tuning: tuningConfig,
+            debug: userConfig.debug ?? false,
+        };
+        this.initialZoom = userConfig.map.getZoom() ?? 10;
+        this.initialCenter = userConfig.map.getCenter() ?? null;
+        this.initialHeading = userConfig.map.getHeading() ?? 0;
+        this.gestureController = new GestureController(tuningConfig, (frame) => {
+            this.lastFrame = frame;
+        });
+        this.stateMachine = new GestureStateMachine(tuningConfig);
+        this.overlay = new WebcamOverlay(webcamConfig);
+        this.interaction = new GoogleMapsGestureInteraction(userConfig.map);
+    }
+    /**
+     * Initialise webcam + MediaPipe, mount overlay, begin detection loop.
+     * Must be called from a user-gesture event (e.g. button click) to allow
+     * webcam permission prompt.
+     */
+    async start() {
+        if (this.started)
+            return;
+        try {
+            const videoEl = await this.gestureController.init();
+            this.overlay.attachVideo(videoEl);
+            const mapDiv = this.config.map.getDiv();
+            this.overlay.mount(mapDiv ?? document.body);
+            this.resetTransientState();
+            this.started = true;
+            this.paused = false;
+            this.interaction.syncFromMap();
+            this.gestureController.start();
+            this.renderLoop();
+            // Pause when tab is hidden to save resources
+            document.addEventListener('visibilitychange', this.handleVisibilityChange);
+        }
+        catch (error) {
+            this.overlay.unmount();
+            this.gestureController.destroy();
+            this.resetTransientState();
+            this.started = false;
+            this.paused = false;
+            document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+            throw error;
+        }
+    }
+    /** Stop detection and remove overlay. Safe to call start() again afterwards. */
+    stop() {
+        this.gestureController.destroy();
+        this.overlay.unmount();
+        this.stateMachine.reset();
+        this.resetTransientState();
+        this.interaction.dispose();
+        // Recreate the interaction so a subsequent start() has fresh listeners.
+        this.interaction = new GoogleMapsGestureInteraction(this.config.map);
+        if (this.rafHandle !== null) {
+            cancelAnimationFrame(this.rafHandle);
+            this.rafHandle = null;
+        }
+        document.removeEventListener('visibilitychange', this.handleVisibilityChange);
+        this.started = false;
+        this.paused = false;
+    }
+    /** Pause detection (overlay stays visible but inactive). */
+    pause() {
+        this.paused = true;
+        this.gestureController.stop();
+        this.stateMachine.reset();
+    }
+    /** Resume after pause. */
+    resume() {
+        if (!this.paused)
+            return;
+        this.paused = false;
+        this.interaction.syncFromMap();
+        this.gestureController.start();
+    }
+    renderLoop() {
+        this.rafHandle = requestAnimationFrame(() => this.renderLoop());
+        if (this.paused) {
+            this.overlay.render(null, 'idle');
+            return;
+        }
+        const frame = this.lastFrame;
+        if (frame === null) {
+            this.overlay.render(null, 'idle');
+            return;
+        }
+        const output = this.stateMachine.update(frame);
+        this.interaction.apply(output);
+        let resetProgress = 0;
+        const { leftHand, rightHand, timestamp } = frame;
+        const resetPoseActive = !!leftHand &&
+            !!rightHand &&
+            leftHand.gesture !== 'fist' &&
+            leftHand.gesture !== 'pinch' &&
+            rightHand.gesture !== 'fist' &&
+            rightHand.gesture !== 'pinch' &&
+            this.isPrayPose(leftHand.landmarks, rightHand.landmarks);
+        if (resetPoseActive) {
+            // Pose is active: clear any grace timer and start/continue dwell
+            this.resetPoseGraceTimer = null;
+            if (this.resetPoseStart === null) {
+                this.resetPoseStart = timestamp;
+                this.resetPoseTriggered = false;
+            }
+            const elapsed = timestamp - this.resetPoseStart;
+            resetProgress = Math.min(1, elapsed / this.resetPoseDurationMs);
+            if (!this.resetPoseTriggered && resetProgress >= 1) {
+                this.resetPoseTriggered = true;
+                this.config.map.moveCamera({
+                    zoom: this.initialZoom,
+                    center: this.initialCenter ?? undefined,
+                    heading: this.initialHeading,
+                });
+                this.interaction.syncFromMap();
+            }
+        }
+        else if (this.resetPoseStart !== null) {
+            // Pose dropped -- start grace period before resetting the timer
+            if (this.resetPoseGraceTimer === null) {
+                this.resetPoseGraceTimer = timestamp;
+            }
+            else if (timestamp - this.resetPoseGraceTimer >= this.resetPoseGraceMs) {
+                this.resetPoseStart = null;
+                this.resetPoseTriggered = false;
+                this.resetPoseGraceTimer = null;
+            }
+            // While in grace period, keep showing the last progress value
+            if (this.resetPoseStart !== null) {
+                const elapsed = timestamp - this.resetPoseStart;
+                resetProgress = Math.min(1, elapsed / this.resetPoseDurationMs);
+            }
+        }
+        else {
+            this.resetPoseGraceTimer = null;
+        }
+        this.overlay.render(frame, output.mode, resetProgress);
+        if (this.config.debug) {
+            this.logDebug(output.mode, frame);
+        }
+    }
+    /**
+     * Returns true when both hands are held close together based on wrist proximity.
+     * Uses Euclidean distance between the two wrists in normalised screen-space
+     * coordinates (0 to 1). Threshold is 0.45.
+     */
+    isPrayPose(left, right) {
+        const lWrist = left[LANDMARKS.WRIST];
+        const rWrist = right[LANDMARKS.WRIST];
+        if (!lWrist || !rWrist)
+            return false;
+        // Hands are together when wrists are close in both X and Y
+        const dx = lWrist.x - rWrist.x;
+        const dy = lWrist.y - rWrist.y;
+        return Math.sqrt(dx * dx + dy * dy) < 0.45;
+    }
+    resetTransientState() {
+        this.lastFrame = null;
+        this.resetPoseStart = null;
+        this.resetPoseTriggered = false;
+        this.resetPoseGraceTimer = null;
+    }
+    logDebug(mode, frame) {
+        const hands = frame.hands
+            .map((h) => `${h.handedness}:${h.gesture}(${h.score.toFixed(2)})`)
+            .join(' ');
+        console.debug(`[gmaps-gestures] mode=${mode} ${hands}`);
+    }
+}

package/dist/GoogleMapsGestureInteraction.d.ts

@@ -0,0 +1,71 @@
+import type { StateMachineOutput } from '@map-gesture-controls/core';
+/**
+ * GoogleMapsGestureInteraction
+ *
+ * Translates GestureStateMachine output into Google Maps API calls.
+ * Uses moveCamera() for all operations to avoid Google Maps' built-in
+ * smooth animations, which cause lag when applied every frame.
+ *
+ * Tracks zoom and heading internally so that small per-frame deltas
+ * accumulate correctly. Google Maps quantizes values returned by
+ * getZoom()/getHeading(), which would swallow fractional increments
+ * if we read them back each frame.
+ *
+ * Listens for zoom_changed / heading_changed so that external changes
+ * (built-in controls, wheel zoom, other app code) are picked up
+ * before the next gesture delta is applied.
+ *
+ * Pan:  left fist wrist delta -> pixel offset converted to lat/lng delta,
+ *       rotated by current heading so screen direction always matches.
+ *       Webcam is mirrored so dx is negated.
+ * Zoom: right fist wrist vertical delta -> zoom level change (up = in, down = out).
+ */
+export declare class GoogleMapsGestureInteraction {
+    private map;
+    private panScale;
+    private zoomScale;
+    private currentZoom;
+    private currentHeading;
+    private applyingChange;
+    private zoomListener;
+    private headingListener;
+    constructor(map: google.maps.Map);
+    /**
+     * Apply a state machine output frame to the map.
+     * Safe to call every animation frame.
+     */
+    apply(output: StateMachineOutput): void;
+    /**
+     * Pan map by a normalised delta (0-1 range from webcam space).
+     * dx/dy are hand movement as a fraction of frame width/height.
+     *
+     * Converts pixel offsets to lat/lng deltas using the current zoom level,
+     * then rotates by the current heading so that pan direction always
+     * matches what the user sees on screen (even on rotated vector maps).
+     * Applies via moveCamera() for instant, animation-free updates.
+     * Webcam is mirrored so dx is negated.
+     */
+    private pan;
+    /**
+     * Rotate map heading. delta in radians: positive = clockwise.
+     * Google Maps uses heading in degrees (0-360).
+     */
+    private rotate;
+    /**
+     * Sync internal state with the map's current values.
+     * Call after external changes (e.g. reset pose) so that
+     * subsequent gesture deltas start from the correct baseline.
+     */
+    syncFromMap(): void;
+    /**
+     * Remove map event listeners. Call when disposing the interaction
+     * to avoid leaking listeners on the map instance.
+     */
+    dispose(): void;
+    /**
+     * Zoom map. delta > 0 = zoom in, delta < 0 = zoom out.
+     * Tracks zoom internally so fractional per-frame deltas accumulate
+     * instead of being lost to Google Maps' integer-snap on getZoom().
+     */
+    private zoom;
+}

package/dist/GoogleMapsGestureInteraction.js

@@ -0,0 +1,192 @@
+/**
+ * GoogleMapsGestureInteraction
+ *
+ * Translates GestureStateMachine output into Google Maps API calls.
+ * Uses moveCamera() for all operations to avoid Google Maps' built-in
+ * smooth animations, which cause lag when applied every frame.
+ *
+ * Tracks zoom and heading internally so that small per-frame deltas
+ * accumulate correctly. Google Maps quantizes values returned by
+ * getZoom()/getHeading(), which would swallow fractional increments
+ * if we read them back each frame.
+ *
+ * Listens for zoom_changed / heading_changed so that external changes
+ * (built-in controls, wheel zoom, other app code) are picked up
+ * before the next gesture delta is applied.
+ *
+ * Pan:  left fist wrist delta -> pixel offset converted to lat/lng delta,
+ *       rotated by current heading so screen direction always matches.
+ *       Webcam is mirrored so dx is negated.
+ * Zoom: right fist wrist vertical delta -> zoom level change (up = in, down = out).
+ */
+export class GoogleMapsGestureInteraction {
+    constructor(map) {
+        Object.defineProperty(this, "map", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "panScale", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 2.0
+        });
+        // Wrist vertical delta is ~0.005-0.02 per frame at natural speed.
+        // zoomScale=15 ~ 1 zoom level/sec at 30fps with moderate hand movement.
+        Object.defineProperty(this, "zoomScale", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 15.0
+        });
+        // Internal state to avoid Google Maps quantization eating small deltas.
+        Object.defineProperty(this, "currentZoom", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "currentHeading", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // Track whether we caused the last change so we can skip our own events.
+        Object.defineProperty(this, "applyingChange", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        // Store listener handles so we can clean up.
+        Object.defineProperty(this, "zoomListener", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "headingListener", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.map = map;
+        this.currentZoom = map.getZoom() ?? 10;
+        this.currentHeading = map.getHeading() ?? 0;
+        this.zoomListener = map.addListener('zoom_changed', () => {
+            if (!this.applyingChange) {
+                this.currentZoom = map.getZoom() ?? this.currentZoom;
+            }
+        });
+        this.headingListener = map.addListener('heading_changed', () => {
+            if (!this.applyingChange) {
+                this.currentHeading = map.getHeading() ?? this.currentHeading;
+            }
+        });
+    }
+    /**
+     * Apply a state machine output frame to the map.
+     * Safe to call every animation frame.
+     */
+    apply(output) {
+        if (output.panDelta) {
+            this.pan(output.panDelta.x, output.panDelta.y);
+        }
+        if (output.zoomDelta !== null) {
+            this.zoom(output.zoomDelta);
+        }
+        if (output.rotateDelta !== null) {
+            this.rotate(output.rotateDelta);
+        }
+    }
+    /**
+     * Pan map by a normalised delta (0-1 range from webcam space).
+     * dx/dy are hand movement as a fraction of frame width/height.
+     *
+     * Converts pixel offsets to lat/lng deltas using the current zoom level,
+     * then rotates by the current heading so that pan direction always
+     * matches what the user sees on screen (even on rotated vector maps).
+     * Applies via moveCamera() for instant, animation-free updates.
+     * Webcam is mirrored so dx is negated.
+     */
+    pan(dx, dy) {
+        const center = this.map.getCenter();
+        if (!center)
+            return;
+        const div = this.map.getDiv();
+        const mapW = div.clientWidth;
+        const mapH = div.clientHeight;
+        // Convert normalised webcam delta to screen pixels.
+        // Negate dx because webcam is mirrored.
+        const screenDx = -dx * mapW * this.panScale;
+        const screenDy = dy * mapH * this.panScale;
+        // Rotate pixel deltas by heading so pan matches screen direction
+        // on rotated maps. Heading is in degrees, clockwise from north.
+        const headingRad = (this.currentHeading * Math.PI) / 180;
+        const cosH = Math.cos(headingRad);
+        const sinH = Math.sin(headingRad);
+        const pixelDx = screenDx * cosH - screenDy * sinH;
+        const pixelDy = screenDx * sinH + screenDy * cosH;
+        // Convert pixel offset to lat/lng offset.
+        // At zoom level z, each pixel covers 360 / (256 * 2^z) degrees of longitude.
+        const degreesPerPixel = 360 / (256 * Math.pow(2, this.currentZoom));
+        const dLng = pixelDx * degreesPerPixel;
+        // Latitude degrees per pixel varies by latitude (Mercator).
+        // Multiply by cos(lat) to shrink the delta at higher latitudes.
+        const latRad = (center.lat() * Math.PI) / 180;
+        const dLat = -pixelDy * degreesPerPixel * Math.cos(latRad);
+        this.map.moveCamera({
+            center: { lat: center.lat() + dLat, lng: center.lng() + dLng },
+        });
+    }
+    /**
+     * Rotate map heading. delta in radians: positive = clockwise.
+     * Google Maps uses heading in degrees (0-360).
+     */
+    rotate(delta) {
+        this.currentHeading = ((this.currentHeading + (delta * 180) / Math.PI) % 360 + 360) % 360;
+        this.applyingChange = true;
+        this.map.moveCamera({
+            heading: this.currentHeading,
+        });
+        this.applyingChange = false;
+    }
+    /**
+     * Sync internal state with the map's current values.
+     * Call after external changes (e.g. reset pose) so that
+     * subsequent gesture deltas start from the correct baseline.
+     */
+    syncFromMap() {
+        this.currentZoom = this.map.getZoom() ?? this.currentZoom;
+        this.currentHeading = this.map.getHeading() ?? this.currentHeading;
+    }
+    /**
+     * Remove map event listeners. Call when disposing the interaction
+     * to avoid leaking listeners on the map instance.
+     */
+    dispose() {
+        this.zoomListener?.remove();
+        this.headingListener?.remove();
+        this.zoomListener = null;
+        this.headingListener = null;
+    }
+    /**
+     * Zoom map. delta > 0 = zoom in, delta < 0 = zoom out.
+     * Tracks zoom internally so fractional per-frame deltas accumulate
+     * instead of being lost to Google Maps' integer-snap on getZoom().
+     */
+    zoom(delta) {
+        this.currentZoom += delta * this.zoomScale;
+        // Clamp to Google Maps' valid range (0-22)
+        this.currentZoom = Math.max(0, Math.min(22, this.currentZoom));
+        this.applyingChange = true;
+        this.map.moveCamera({
+            zoom: this.currentZoom,
+        });
+        this.applyingChange = false;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { GestureMapController } from './GestureMapController.js';
+export { GoogleMapsGestureInteraction } from './GoogleMapsGestureInteraction.js';
+export type { GestureMapControllerConfig } from './types.js';
+export { GestureController, GestureStateMachine, WebcamOverlay, classifyGesture, createHandClassifier, getHandSize, getTwoHandDistance, DEFAULT_WEBCAM_CONFIG, DEFAULT_TUNING_CONFIG, LANDMARKS, COLORS, } from '@map-gesture-controls/core';
+export type { GestureMode, GestureType, HandednessLabel, GestureFrame, DetectedHand, WebcamConfig, TuningConfig, StateMachineOutput, SmoothedPoint, Point2D, HandLandmark, } from '@map-gesture-controls/core';

package/dist/index.js

@@ -0,0 +1,212 @@
+var v = Object.defineProperty;
+var H = (o, e, s) => e in o ? v(o, e, { enumerable: !0, configurable: !0, writable: !0, value: s }) : o[e] = s;
+var t = (o, e, s) => H(o, typeof e != "symbol" ? e + "" : e, s);
+import { DEFAULT_WEBCAM_CONFIG as T, DEFAULT_TUNING_CONFIG as D, GestureController as S, GestureStateMachine as L, WebcamOverlay as G, LANDMARKS as u } from "@map-gesture-controls/core";
+import { COLORS as x, DEFAULT_TUNING_CONFIG as w, DEFAULT_WEBCAM_CONFIG as I, GestureController as E, GestureStateMachine as N, LANDMARKS as W, WebcamOverlay as _, classifyGesture as O, createHandClassifier as R, getHandSize as U, getTwoHandDistance as V } from "@map-gesture-controls/core";
+class p {
+  constructor(e) {
+    t(this, "map");
+    t(this, "panScale", 2);
+    // Wrist vertical delta is ~0.005-0.02 per frame at natural speed.
+    // zoomScale=15 ~ 1 zoom level/sec at 30fps with moderate hand movement.
+    t(this, "zoomScale", 15);
+    // Internal state to avoid Google Maps quantization eating small deltas.
+    t(this, "currentZoom");
+    t(this, "currentHeading");
+    // Track whether we caused the last change so we can skip our own events.
+    t(this, "applyingChange", !1);
+    // Store listener handles so we can clean up.
+    t(this, "zoomListener", null);
+    t(this, "headingListener", null);
+    this.map = e, this.currentZoom = e.getZoom() ?? 10, this.currentHeading = e.getHeading() ?? 0, this.zoomListener = e.addListener("zoom_changed", () => {
+      this.applyingChange || (this.currentZoom = e.getZoom() ?? this.currentZoom);
+    }), this.headingListener = e.addListener("heading_changed", () => {
+      this.applyingChange || (this.currentHeading = e.getHeading() ?? this.currentHeading);
+    });
+  }
+  /**
+   * Apply a state machine output frame to the map.
+   * Safe to call every animation frame.
+   */
+  apply(e) {
+    e.panDelta && this.pan(e.panDelta.x, e.panDelta.y), e.zoomDelta !== null && this.zoom(e.zoomDelta), e.rotateDelta !== null && this.rotate(e.rotateDelta);
+  }
+  /**
+   * Pan map by a normalised delta (0-1 range from webcam space).
+   * dx/dy are hand movement as a fraction of frame width/height.
+   *
+   * Converts pixel offsets to lat/lng deltas using the current zoom level,
+   * then rotates by the current heading so that pan direction always
+   * matches what the user sees on screen (even on rotated vector maps).
+   * Applies via moveCamera() for instant, animation-free updates.
+   * Webcam is mirrored so dx is negated.
+   */
+  pan(e, s) {
+    const i = this.map.getCenter();
+    if (!i) return;
+    const r = this.map.getDiv(), a = r.clientWidth, n = r.clientHeight, l = -e * a * this.panScale, h = s * n * this.panScale, c = this.currentHeading * Math.PI / 180, d = Math.cos(c), m = Math.sin(c), f = l * d - h * m, y = l * m + h * d, g = 360 / (256 * Math.pow(2, this.currentZoom)), P = f * g, C = i.lat() * Math.PI / 180, M = -y * g * Math.cos(C);
+    this.map.moveCamera({
+      center: { lat: i.lat() + M, lng: i.lng() + P }
+    });
+  }
+  /**
+   * Rotate map heading. delta in radians: positive = clockwise.
+   * Google Maps uses heading in degrees (0-360).
+   */
+  rotate(e) {
+    this.currentHeading = ((this.currentHeading + e * 180 / Math.PI) % 360 + 360) % 360, this.applyingChange = !0, this.map.moveCamera({
+      heading: this.currentHeading
+    }), this.applyingChange = !1;
+  }
+  /**
+   * Sync internal state with the map's current values.
+   * Call after external changes (e.g. reset pose) so that
+   * subsequent gesture deltas start from the correct baseline.
+   */
+  syncFromMap() {
+    this.currentZoom = this.map.getZoom() ?? this.currentZoom, this.currentHeading = this.map.getHeading() ?? this.currentHeading;
+  }
+  /**
+   * Remove map event listeners. Call when disposing the interaction
+   * to avoid leaking listeners on the map instance.
+   */
+  dispose() {
+    var e, s;
+    (e = this.zoomListener) == null || e.remove(), (s = this.headingListener) == null || s.remove(), this.zoomListener = null, this.headingListener = null;
+  }
+  /**
+   * Zoom map. delta > 0 = zoom in, delta < 0 = zoom out.
+   * Tracks zoom internally so fractional per-frame deltas accumulate
+   * instead of being lost to Google Maps' integer-snap on getZoom().
+   */
+  zoom(e) {
+    this.currentZoom += e * this.zoomScale, this.currentZoom = Math.max(0, Math.min(22, this.currentZoom)), this.applyingChange = !0, this.map.moveCamera({
+      zoom: this.currentZoom
+    }), this.applyingChange = !1;
+  }
+}
+class Z {
+  constructor(e) {
+    t(this, "config");
+    t(this, "gestureController");
+    t(this, "stateMachine");
+    t(this, "overlay");
+    t(this, "interaction");
+    t(this, "lastFrame", null);
+    t(this, "rafHandle", null);
+    t(this, "started", !1);
+    t(this, "paused", !1);
+    t(this, "resetPoseStart", null);
+    t(this, "resetPoseTriggered", !1);
+    t(this, "resetPoseGraceTimer", null);
+    t(this, "resetPoseDurationMs", 1e3);
+    t(this, "resetPoseGraceMs", 300);
+    t(this, "initialZoom");
+    t(this, "initialCenter");
+    t(this, "initialHeading");
+    t(this, "handleVisibilityChange", () => {
+      document.hidden ? this.pause() : this.resume();
+    });
+    const s = { ...T, ...e.webcam }, i = { ...D, ...e.tuning };
+    this.config = {
+      map: e.map,
+      webcam: s,
+      tuning: i,
+      debug: e.debug ?? !1
+    }, this.initialZoom = e.map.getZoom() ?? 10, this.initialCenter = e.map.getCenter() ?? null, this.initialHeading = e.map.getHeading() ?? 0, this.gestureController = new S(i, (r) => {
+      this.lastFrame = r;
+    }), this.stateMachine = new L(i), this.overlay = new G(s), this.interaction = new p(e.map);
+  }
+  /**
+   * Initialise webcam + MediaPipe, mount overlay, begin detection loop.
+   * Must be called from a user-gesture event (e.g. button click) to allow
+   * webcam permission prompt.
+   */
+  async start() {
+    if (!this.started)
+      try {
+        const e = await this.gestureController.init();
+        this.overlay.attachVideo(e);
+        const s = this.config.map.getDiv();
+        this.overlay.mount(s ?? document.body), this.resetTransientState(), this.started = !0, this.paused = !1, this.interaction.syncFromMap(), this.gestureController.start(), this.renderLoop(), document.addEventListener("visibilitychange", this.handleVisibilityChange);
+      } catch (e) {
+        throw this.overlay.unmount(), this.gestureController.destroy(), this.resetTransientState(), this.started = !1, this.paused = !1, document.removeEventListener("visibilitychange", this.handleVisibilityChange), e;
+      }
+  }
+  /** Stop detection and remove overlay. Safe to call start() again afterwards. */
+  stop() {
+    this.gestureController.destroy(), this.overlay.unmount(), this.stateMachine.reset(), this.resetTransientState(), this.interaction.dispose(), this.interaction = new p(this.config.map), this.rafHandle !== null && (cancelAnimationFrame(this.rafHandle), this.rafHandle = null), document.removeEventListener("visibilitychange", this.handleVisibilityChange), this.started = !1, this.paused = !1;
+  }
+  /** Pause detection (overlay stays visible but inactive). */
+  pause() {
+    this.paused = !0, this.gestureController.stop(), this.stateMachine.reset();
+  }
+  /** Resume after pause. */
+  resume() {
+    this.paused && (this.paused = !1, this.interaction.syncFromMap(), this.gestureController.start());
+  }
+  renderLoop() {
+    if (this.rafHandle = requestAnimationFrame(() => this.renderLoop()), this.paused) {
+      this.overlay.render(null, "idle");
+      return;
+    }
+    const e = this.lastFrame;
+    if (e === null) {
+      this.overlay.render(null, "idle");
+      return;
+    }
+    const s = this.stateMachine.update(e);
+    this.interaction.apply(s);
+    let i = 0;
+    const { leftHand: r, rightHand: a, timestamp: n } = e;
+    if (!!r && !!a && r.gesture !== "fist" && r.gesture !== "pinch" && a.gesture !== "fist" && a.gesture !== "pinch" && this.isPrayPose(r.landmarks, a.landmarks)) {
+      this.resetPoseGraceTimer = null, this.resetPoseStart === null && (this.resetPoseStart = n, this.resetPoseTriggered = !1);
+      const h = n - this.resetPoseStart;
+      i = Math.min(1, h / this.resetPoseDurationMs), !this.resetPoseTriggered && i >= 1 && (this.resetPoseTriggered = !0, this.config.map.moveCamera({
+        zoom: this.initialZoom,
+        center: this.initialCenter ?? void 0,
+        heading: this.initialHeading
+      }), this.interaction.syncFromMap());
+    } else if (this.resetPoseStart !== null) {
+      if (this.resetPoseGraceTimer === null ? this.resetPoseGraceTimer = n : n - this.resetPoseGraceTimer >= this.resetPoseGraceMs && (this.resetPoseStart = null, this.resetPoseTriggered = !1, this.resetPoseGraceTimer = null), this.resetPoseStart !== null) {
+        const h = n - this.resetPoseStart;
+        i = Math.min(1, h / this.resetPoseDurationMs);
+      }
+    } else
+      this.resetPoseGraceTimer = null;
+    this.overlay.render(e, s.mode, i), this.config.debug && this.logDebug(s.mode, e);
+  }
+  /**
+   * Returns true when both hands are held close together based on wrist proximity.
+   * Uses Euclidean distance between the two wrists in normalised screen-space
+   * coordinates (0 to 1). Threshold is 0.45.
+   */
+  isPrayPose(e, s) {
+    const i = e[u.WRIST], r = s[u.WRIST];
+    if (!i || !r) return !1;
+    const a = i.x - r.x, n = i.y - r.y;
+    return Math.sqrt(a * a + n * n) < 0.45;
+  }
+  resetTransientState() {
+    this.lastFrame = null, this.resetPoseStart = null, this.resetPoseTriggered = !1, this.resetPoseGraceTimer = null;
+  }
+  logDebug(e, s) {
+    const i = s.hands.map((r) => `${r.handedness}:${r.gesture}(${r.score.toFixed(2)})`).join(" ");
+    console.debug(`[gmaps-gestures] mode=${e} ${i}`);
+  }
+}
+export {
+  x as COLORS,
+  w as DEFAULT_TUNING_CONFIG,
+  I as DEFAULT_WEBCAM_CONFIG,
+  E as GestureController,
+  Z as GestureMapController,
+  N as GestureStateMachine,
+  p as GoogleMapsGestureInteraction,
+  W as LANDMARKS,
+  _ as WebcamOverlay,
+  O as classifyGesture,
+  R as createHandClassifier,
+  U as getHandSize,
+  V as getTwoHandDistance
+};

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+import type { WebcamConfig, TuningConfig } from '@map-gesture-controls/core';
+export interface GestureMapControllerConfig {
+    map: google.maps.Map;
+    webcam?: Partial<WebcamConfig>;
+    tuning?: Partial<TuningConfig>;
+    debug?: boolean;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@map-gesture-controls/google-maps",
+  "version": "0.2.0",
+  "description": "Control Google Maps with hand gestures via 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": "./style.css"
+  },
+  "files": [
+    "dist",
+    "style.css"
+  ],
+  "scripts": {
+    "build:lib": "tsc -p tsconfig.lib.json && vite build --config vite.lib.config.ts",
+    "type-check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@map-gesture-controls/core": "*"
+  },
+  "peerDependencies": {
+    "@types/google.maps": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@types/google.maps": "^3.58.1",
+    "typescript": "^5.4.5",
+    "vite": "^5.2.11"
+  },
+  "keywords": [
+    "google-maps",
+    "googlemaps",
+    "gmaps",
+    "mediapipe",
+    "hand-gestures",
+    "gesture-control",
+    "gesture-recognition",
+    "hand-tracking",
+    "map",
+    "maps",
+    "webcam",
+    "touchless",
+    "hands-free",
+    "accessibility",
+    "kiosk",
+    "computer-vision",
+    "wasm",
+    "interaction"
+  ],
+  "homepage": "https://sanderdesnaijer.github.io/map-gesture-controls/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sanderdesnaijer/map-gesture-controls.git",
+    "directory": "packages/google-maps-gesture-controls"
+  },
+  "bugs": {
+    "url": "https://github.com/sanderdesnaijer/map-gesture-controls/issues"
+  },
+  "author": "Sander de Snaijer",
+  "overrides": {
+    "esbuild": "^0.25.0"
+  },
+  "license": "MIT"
+}

package/style.css

@@ -0,0 +1,85 @@
+/* Shared overlay chrome for WebcamOverlay.
+   Layout-critical styles remain inline at runtime. */
+.ol-gesture-overlay {
+  box-shadow: 0 4px 24px rgba(0, 0, 0, 0.6);
+  transition: box-shadow 0.3s ease;
+}
+
+.ol-gesture-overlay:hover {
+  box-shadow: 0 4px 32px rgba(68, 136, 255, 0.35);
+}
+
+.ol-gesture-video {
+  display: block;
+}
+
+.ol-gesture-badge {
+  position: absolute;
+  top: 8px;
+  left: 8px;
+  padding: 3px 10px;
+  border-radius: 12px;
+  font-family: system-ui, sans-serif;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  pointer-events: none;
+  transition: background 0.2s, color 0.2s;
+  z-index: 1;
+}
+
+.ol-gesture-badge--idle {
+  background: rgba(80, 80, 80, 0.75);
+  color: #ccc;
+}
+
+.ol-gesture-badge--panning {
+  background: rgba(0, 204, 255, 0.85);
+  color: #000;
+  box-shadow: 0 0 8px rgba(0, 204, 255, 0.6);
+}
+
+.ol-gesture-badge--zooming {
+  background: rgba(0, 255, 204, 0.85);
+  color: #000;
+  box-shadow: 0 0 8px rgba(0, 255, 204, 0.6);
+}
+
+.ol-gesture-reset {
+  position: absolute;
+  bottom: 8px;
+  left: 8px;
+  right: 8px;
+  pointer-events: none;
+  transition: opacity 0.15s ease;
+  z-index: 1;
+}
+
+.ol-gesture-reset-label {
+  display: block;
+  font-family: system-ui, sans-serif;
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: #fff;
+  margin-bottom: 3px;
+  text-shadow: 0 1px 2px rgba(0, 0, 0, 0.8);
+}
+
+.ol-gesture-reset-track {
+  height: 4px;
+  background: rgba(255, 255, 255, 0.2);
+  border-radius: 2px;
+  overflow: hidden;
+}
+
+.ol-gesture-reset-fill {
+  height: 100%;
+  width: 0%;
+  background: rgba(255, 200, 0, 0.9);
+  border-radius: 2px;
+  box-shadow: 0 0 6px rgba(255, 200, 0, 0.6);
+  transition: width 0.05s linear;
+}