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: