Package Exports

@map-gesture-controls/ol

Readme

@map-gesture-controls/ol

Control OpenLayers 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 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

Screen recording of the map gesture demo: an OpenLayers map 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.

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

Webcam capture - GestureController opens the camera and feeds each frame to MediaPipe Hand Landmarker, returning 21 3D landmarks per hand.
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.
Map integration - OpenLayersGestureInteraction translates hand movement deltas into ol/Map pan offsets, zoom adjustments, and view rotation. Pan operates in screen space (using getPixelFromCoordinate/getCoordinateFromPixel), so moving your hand left always moves the map left on screen regardless of the current map rotation.

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.

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:

Export	Type	Description
`GestureMapController`	Class	High-level controller that wires gesture detection to an OpenLayers map
`OpenLayersGestureInteraction`	Class	Low-level OL 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

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+

Package	Description
`@map-gesture-controls/core`	Map-agnostic gesture detection engine (included in this package)

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