@map-gesture-controls/ol

Control OpenLayers maps with hand gestures. No mouse, no touch, no backend. Point your webcam, make a left fist to pan, right fist to zoom, or both fists to rotate. Powered by 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

Install

npm install @map-gesture-controls/ol ol

Quick start

import Map from 'ol/Map.js';
import View from 'ol/View.js';
import TileLayer from 'ol/layer/Tile.js';
import OSM from 'ol/source/OSM.js';
import { fromLonLat } from 'ol/proj.js';
import { GestureMapController } from '@map-gesture-controls/ol';
import '@map-gesture-controls/ol/style.css';

const map = new Map({
  target: 'map',
  layers: [new TileLayer({ source: new OSM() })],
  view: new View({ center: fromLonLat([0, 0]), zoom: 2 }),
});

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();

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 = pan, right fist = zoom (vertical movement), both fists = rotate, anything else is idle. Dwell timers and grace periods prevent accidental triggers.
3. Map integration - OpenLayersGestureInteraction translates hand movement deltas into ol/Map pan offsets, zoom adjustments, and view rotation, with dead-zone filtering and exponential smoothing for a natural feel.

Gestures

Configuration

All options are optional. Defaults work well out of the box.

const controller = new GestureMapController({
  map,
  webcam: {
    position: 'top-left',   // overlay corner position
    width: 240,
    height: 180,
    opacity: 0.7,
  },
  tuning: {
    panScale: 3.0,          // higher = faster panning
    zoomScale: 15.0,        // higher = faster zooming
    actionDwellMs: 80,      // ms before confirming a gesture
    releaseGraceMs: 150,    // ms grace period after gesture ends
  },
  debug: true,              // log gesture state to console
});

See the full configuration reference in the documentation.

Exports

This package re-exports the entire @map-gesture-controls/core API, so you only need one import. On top of core, it adds:

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

• OpenLayers 10.x (ol as a peer dependency)
• A modern browser with WebGL, getUserMedia, and WASM support
• Chrome 111+, Edge 111+, Firefox 115+, Safari 17+

Related packages

Documentation

Full docs, live demos, and API reference at 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.

License

MIT