puppet-canvas

puppet-canvas is a Puppeteer backed implementation of HTML Canvas API for NodeJS.

Installation

$ npm install puppet-canvas --save

Usage

Following example draws a house and grabs the data url of the image.

import { createCanvas, close } from 'puppet-canvas';
// OR const { createCanvas, close } = require('puppet-canvas')

async(() => {

const canvas = await createCanvas(400, 400);
const ctx = await canvas.getContext('2d');

// Draw a house
ctx.lineWidth = 10;
ctx.strokeRect(75, 140, 150, 110);
ctx.fillRect(130, 190, 40, 60);
ctx.moveTo(50, 140);
ctx.lineTo(150, 60);
ctx.lineTo(250, 140);
ctx.closePath();
ctx.stroke();

// Get the image as a data url
const dataUrl = await canvas.toDataURL();

// Release
await close();

})();

Using images

To use external images in your canvas, first load the image using the loadImage method.

import { createCanvas, loadImage } from 'puppet-canvas';

const canvas = await createCanvas(400, 400);
const ctx = await canvas.getContext('2d');
const image = await loadImage('https://....', canvas);
await ctx.drawImage(image, 100, 100);

Using complex objects

Any non-serializable object returned by puppeteer is automatically proxied as well. So one can use/pass more complex objects like a gradient:

const gradient = await ctx.createLinearGradient(20, 0, 220, 0);
gradient.addColorStop(0, 'green');
gradient.addColorStop(.5, 'cyan');
gradient.addColorStop(1, 'green');
ctx.fillStyle = gradient;
ctx.fillRect(20, 20, 200, 100);

Using custom fonts

When using a custom font for rendering text, you can ensure the font is loaded by calling the loadFont methods.

import { createCanvas, loadFont } from 'puppet-canvas';

const canvas = await createCanvas(400, 400);
const ctx = await canvas.getContext('2d');

await loadFont(
  'Bangers',
  'https://fonts.gstatic.com/s/bangers/v12/FeVQS0BTqb0h60ACH55Q2J5hm24.woff2',
  canvas
);
ctx.font = `bold 48px Bangers`;
ctx.fillText('Hello world', 50, 100);

Implementation

puppet-canvas creates a canvas on a puppeteer instance, and exposes the API via a JavaScript Proxy.

A side effect of this is that all calls, essentially become async. For normal drawing, one doesn't need to await each command unless a value is being returned.

A proxied solution is somewhat better than alternate ones because, firstly, the rendering is exactly what the browser would have rendered (Chrome). Secondly, this is mostly future-proof since all methods are just proxied to the actual instance. So, any new API added to the Canvas, should automagically work.

Implentation Shortcomings

Though a proxied implementation is simpler, smaller, and more flexible, it can be slower than alternative native implementations. For example, manipulating lots of pixels, one pixel at a time, may be slow and not recommended.

The other shortcoming is from a dev experience, everything is an async call. So it creates more code for getting child object and properties. The following code:

const imageDataLength = ctx.createImageData(10, 10).data.length;

has to be refactored as

const imageData = await ctx.createImageData(10, 10);
const imageDataLength = await (await imageData.data).length;

Why don't I just use puppeteer

Yes, you can and for some cases it may even be a better dev experience.

puppet-canvas provides a simple abstraction layer so you don't have to jump in and out of Puppeteer's execution context all the time. You treat the canvas very similar to canvas on the web, and not worry much about anything else.

Full API

createCanvas(width: number, height: number) => Promise<HTMLCanvasElement>

Creates a canvas instance with the specified width and height (in pixels)

linkCanvas(canvas: ElementHandle<HTMLCanvasElement>) => Promise<HTMLCanvasElement>

Say, you want to use this with an existing instance of puppeteer, you can pass in the ElementHandle of the canvase in your page.

close() => Promise

Close associated puppeteer instance. Usually called at the end.

releaseCanvas(canvas: HTMLCanvasElement) => Promise

Release the canvas instance, if you do not want puppet-canvas to proxy it anymore, but still want to keep the canvas instance around

screenshotCanvas(canvas: HTMLCanvasElement, options?: ScreenshotOptions) => Promise<string | Buffer>

Take a screenshot of the canvas. The method optionally takes in ScreenshotOptions which are the same options as described in Puppeteer screenshot method

loadFont(name: string, url: string, canvas: HTMLCanvasElement) => Promise

Load a font for the canvas element to use. name is the font-family name of the font. url is the url to the font file (like a woff file)

loadImage(url: string, canvas: HTMLCanvasElement, page?: Page) => Promise<HTMLImageElement>

Load an image from a URL that could be used by the canvas, e.g. for drawing the image on the canvas.

License

MIT License (c) Preet Shihn

pshihn/puppet-canvas