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

$3

``
npm i canvas-transform-context
`

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

$3

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

Usage

Basic setup

`javascript
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.

$3

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

| Param | Description |
| ------- | - |
| e | mousedown event |

$3

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 |

$3

Ends a mouse pan. Use on mouseup.

$3

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 |

$3

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 |

$3

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 |

$3

Stops a pan

$3

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 |

$3

Resets all transformations

Action Helpers

$3

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

$3

Converts canvas coordinates to transformed coordinates

Returns: Transformed coordinates

| Param | Description |
| ------------- | -------------------- |
| canvasPoint | Canvas coordinates |

$3

Converts a mouse event to the transformed coordinates within the canvas

Returns: Transformed point

| Param | Description |
| ------- | ------------- |
| e | mouse event |

$3

Clear the canvas given the current transformations

General Helpers

General purpose canvas helpers unrelated to transform

$3

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