canvas-transform-context

Canvas Transform Context

A canvas context extension based on this example by phrogz.

A class wrapper for a 2D canvas context that keeps track of transform information, allowing for easy coordinate control with scaled/transformed canvases. Perfect for visual web apps that requires extra canvas functionalities without the hassle of custom canvas implementations.

Demo

Installation

via npm

npm i canvas-transform-context

import { TransformContext } from "canvas-transform-context"

via browser

import { TransformContext } from "https://unpkg.com/canvas-transform-context@latest/dist/bundle.min.js";

Usage

Basic setup

const canvas = getDocumentById(/* canvas id */)
const ctx = canvas.getContext('2d')

const transformCtx = new TransformContext(ctx);

transformCtx.onDraw((ctx) => {
  /* Draw on canvas... */
})

// Mouse dragging
canvas.addEventListener("mousedown", (e) => transformCtx.beginMousePan(e));
canvas.addEventListener("mousemove", (e) => transformCtx.moveMousePan(e));
canvas.addEventListener("mouseup", (e) => transformCtx.endPan(e));

// Wheel zooming
canvas.addEventListener("wheel", (e) => transformCtx.zoomByMouse(e));

Documentation

Action Methods

Batteries-included methods for commonly use actions, included methods that can directly take mouse events as a parameter.

beginMousePan(e)

Begins a pan given the current position from the mouse event. Use on mousedown.

Param	Description
e	mousedown event

moveMousePan(e)

Pans the canvas to the new position from the mouse event. Use on mousemove. Does nothing if beginMousePan wasn't called, or if endPan was just called.

Param	Description
e	mousemove event

endMousePan()

Ends a mouse pan. Use on mouseup.

zoomByMouse(e, zoomScale)

Zooms via the mouse wheel event.

Param	Default	Description
e		mouse wheel event
zoomScale	1.1	The scale percentage to zoom by. Default is 1.1

beginPan(start, transform)

Sets the anchor for a panning action.

Param	Default	Description
start		Starting coordinates for a pan
transform	true	Whether or not to transform the start coordinates

movePan(current, transform)

Pans the canvas to the new coordinates given the starting point in beginPan. Does nothing if beginPan was not called, or if endPan was just called.

Param	Default	Description
current
transform	true	Whether or not to transform the start coordinates

endPan()

Stops a pan

zoomBy(amount, zoomScale, center, transform) ⇒

Zoom by a given integer amount.

Returns: Current zoom amount in integers

Param	Default	Description
amount		Amount to zoom by in integers. Positive integer zooms in
zoomScale	1.1	The scale percentage to zoom by. Default is 1.1
center	undefined	The point to zoom in towards. If undefined, it will zoom towards the latest panned position
transform	true	Whether or not to transform the center coordinates

reset()

Resets all transformations

Action Helpers

onDraw(callback)

Creates a callback to be called after each action method above.

Param	Description
callback	A callback function with the canvas context as a parameter

Transform Helpers

Helper methods to deal with coordinate transformations

transformPoint(canvasPoint) ⇒

Converts canvas coordinates to transformed coordinates

Returns: Transformed coordinates

Param	Description
canvasPoint	Canvas coordinates

mouseToTransformed(e) ⇒

Converts a mouse event to the transformed coordinates within the canvas

Returns: Transformed point

Param	Description
e	mouse event

clearCanvas()

Clear the canvas given the current transformations

General Helpers

General purpose canvas helpers unrelated to transform

mouseToCanvas(e) ⇒

Converts a mouse event to the correct canvas coordinates

Returns: Canvas coordinates

Param	Description
e	mouse event

Attributions

Main implementation based on code by phrogz:

• http://phrogz.net/tmp/canvas_zoom_to_cursor.html
• https://github.com/Phrogz