dom-2d-camera

DOM 2D Camera

A wrapper for camera-2d that supports pan, zoom, and rotate.

Controls are as follows:

• Pan - Left click and hold + mouse move
• Zoom - Scroll or Alt + Left click and hold with vertical mouse move
• Rotate - Right click or Control + Left click

Based on orbit-camera.

Also see:

• regl-scatterplot for an application and a demo.

Install

npm i dom-2d-camera gl-matrix

Note that gl-matrix is a peer dependency and not automatically bundled with dom-2d-camera as you probably want to use it in your main application.

API

import createDom2dCamera from "dom-2d-camera";

camera = createDom2dCamera(element, options = {})

Binds a camera-2d-simple instance to the DOM element. This effectively attaches event listeners required for pan&zoom interaction.

The following options are available:

• distance: initial distance of the camera. [dtype: number, default: 1]
• target: x, y position the camera is looking in GL coordinates. [dtype: array of numbers, default: [0,0]]
• rotation: rotation in radians around the z axis. [dtype: number, default: 0]
• isNdc: if true the camera operates in normalized device coordinates. This is useful when the camera is used in a WebGL program. [dtype: bool, default: true]
• isFixed: if true panning, rotating, and zooming is disabled. [dtype: bool, default: false]
• isPan: if true x and y panning is enabled. [dtype: bool | [bool, bool], default: true]
• isPanInverted: if true x and y panning is inverted. [dtype: bool | [bool, bool], default: false]
• isRotate: if true rotation is enabled. [dtype: bool, default: true]
• isZoom: if true x and y zooming is enabled. [dtype: bool | [bool, bool], default: true]
• panSpeed: panning speed. [dtype: number, default: 1]
• rotateSpeed: rotation speed. [dtype: number, default: 1]
• zoomSpeed: zooming speed. [dtype: number, default: 1]
• defaultMouseDownMoveAction: default behavior on mousedown + mousemove. [dtype: string, valid: pan or rotate, default: pan]
• mouseDownMoveModKey: modifier key for invoking opposite behavior on mousedown + mousemove.[dtype: string, valid: [alt, shift, ctrl, cmd, meta], default: alt]
• scaleBounds: see camera-2d [dtype: array, default: null]
• viewCenter: see camera-2d [dtype: array, default: null]
• onKeyDown: callback handler for keyDown [dtype: function, default: () => {}]
• onKeyUp: callback handler for keyUp [dtype: function, default: () => {}]
• onMouseDown: callback handler for mouseDown [dtype: function, default: () => {}]
• onMouseUp: callback handler for mouseUp [dtype: function, default: () => {}]
• onMouseMove: callback handler for mouseMove [dtype: function, default: () => {}]
• onWheel: callback handler for wheel [dtype: function, default: () => {}]

Returns a new 2D camera object.

Note the event callback functions are always triggered after the camera updated! This is useful if your main application wants to listen to that specific event and be sure that the camera is up to date.

The camera's API is augmented with the following additional endpoints:

camera.tick()

Call this at the beginning of each frame to update the current position of the camera.

camera.refresh()

Call after the width and height of the related canvas object changed.

Note: the camera does not update the width and height unless you tell it to using this function!

Returns [relX, relY] the WebGL position of x and y.

camera.dispose()

Unsubscribes all event listeners.

camera.config(options)

Configure the canvas camera. options accepts the following options:

• isFixed: if true panning, rotating, and zooming is disabled. [default: false]
• isPan: if true x and y panning is enabled. [dtype: bool | [bool, bool], default: true]
• isPanInverted: if true x and y panning is inverted. [dtype: bool | [bool, bool], default: false]
• isRotate: if true rotation is enabled. [dtype: bool, default: true]
• isZoom: if true x and y zooming is enabled. [dtype: bool | [bool, bool], default: true]
• panSpeed: panning speed. [dtype: float, default: 1.0]
• rotateSpeed: rotation speed. [dtype: float, default: 1.0]
• zoomSpeed: zooming speed. [dtype: float, default: 1.0]
• defaultMouseDownMoveAction: default behavior on mousedown + mousemove. [dtype: string, valid: pan or rotate, default: pan]
• mouseDownMoveModKey: modifier key for invoking opposite behavior on mousedown + mousemove.[dtype: string, valid: [alt, shift, ctrl, cmd, meta], default: alt]

Changelog

v2.2.6

• Fix: do not prevent default wheel behavior when the camera is fixed.