Pure JS implementation of an image drawing and encoding api, based on HTML Canvas
Clone or download
Latest commit 24b8136 Nov 17, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Pull Request Template Jan 24, 2018
firstimages add missing image Jul 8, 2017
src fix arc() method: sin/cos were interchanged, rename the clockwise opt… Nov 17, 2018
tests switch to adaptive subdivision Jul 12, 2018
.esdoc.json Move Tests Jan 16, 2018
.gitignore Move Tests Jan 16, 2018
.travis.yml Run Build on Trusty Jan 25, 2018
LICENSE Initial commit Nov 12, 2014
README.md Fix typo Jun 19, 2018
package-lock.json hook up measureText with unit tests #51 Mar 21, 2018
package.json bump version number Apr 2, 2018


Build Status


PureImage is a pure JavaScript implementation of the HTML Canvas 2d drawing api for NodeJS. It has no native dependencies.

New 0.1.x release

I've completely refactored the code so that it should be easier to maintain and implement new features. For the most part there are no API changes (since the API is defined by the HTML Canvas spec), but if you were using the font or image loading extensions you will need to use the new function names and switch to promises. For more information, please see the API docs

I'm also using Node buffers instead of arrays internally, so you can work with large images faster than before. Rich text is no longer supported, which is fine because it never really worked anyway. We'll have to find a different way to do it.

I've tried to maintain all of the patches that have been sent in, but if you contributed a patch please check that it still works. Thank you all! - josh

supported Canvas Features

  • set pixels
  • stroke and fill paths (rectangles, lines, quadratic curves, bezier curves, arcs/circles)
  • copy and scale images (nearest neighbor)
  • import and export JPG and PNG from streams using promises
  • render basic text (no bold or italics yet)
  • anti-aliased strokes and fills
  • transforms
  • standard globalAlpha and rgba() alpha compositing
  • clip shapes

On the roadmap, but still missing

  • gradients fills
  • image fills
  • blend modes besides SRC OVER
  • smooth clip shapes
  • bold/italic fonts
  • measure text
  • smooth image interpolation


The are more than enough drawing APIs out there. Why do we need another? My personal hatred of C/C++ compilers is widely known. The popular Node modules Canvas.js does a great job, but it's backed by Cairo, a C/C++ layer. I hate having native dependencies in Node modules. They often don't compile, or break after a system update. They often don't support non-X86 architectures (like the Raspberry Pi). You have to have a compiler already installed to use them, along with any other native dependencies pre-installed (like Cairo).

So, I made PureImage. It's goal is to implement the HTML Canvas spec in a headless Node buffer. No browser or window required.

PureImage is meant to be a small and maintainable Canvas library. It is not meant to be fast. If there are two choices of algorithm we will take the one with the simplest implementation, and preferably the fewest lines. We avoid special cases and optimizations to keep the code simple and maintainable. It should run everywhere and be always produce the same output. But it will not be fast. If you need speed go use something else.

PureImage uses only pure JS dependencies. OpenType for font parsing, PngJS for PNG import/export, and jpeg-js for JPG import/export.


Documentation can now be found at: http://joshmarinacci.github.io/node-pureimage


Make a new empty image, 100px by 50px. Automatically filled with 100% opaque black.

var PImage = require('pureimage');
var img1 = PImage.make(100,50);

Fill with a red rectangle with 50% opacity

var ctx = img1.getContext('2d');
ctx.fillStyle = 'rgba(255,0,0, 0.5)';

Fill a green circle with a radius of 40 pixels in the middle of a 100px square black image.

var img = PImage.make(100,100);
var ctx = img.getContext('2d');
ctx.fillStyle = '#00ff00';
ctx.arc(50,50,40,0,Math.PI*2,true); // Outer circle

image of arcto with some fringing bugs

Draw the string 'ABC' in white in the font 'Source Sans Pro', loaded from disk, at a size of 48 points.

test('font test', (t) => {
    var fnt = PImage.registerFont('tests/fonts/SourceSansPro-Regular.ttf','Source Sans Pro');
    fnt.load(() => {
        var img = PImage.make(200,200);
        var ctx = img.getContext('2d');
        ctx.fillStyle = '#ffffff';
        ctx.font = "48pt 'Source Sans Pro'";
        ctx.fillText("ABC", 80, 80);

Write out to a PNG file

PImage.encodePNGToStream(img1, fs.createWriteStream('out.png')).then(() => {
    console.log("wrote out the png file to out.png");
    console.log("there was an error writing");

Read a jpeg, resize it, then save it out

PImage.decodeJPEGFromStream(fs.createReadStream("tests/images/bird.jpg")).then((img) => {
    console.log("size is",img.width,img.height);
    var img2 = PImage.make(50,50);
    var c = img2.getContext('2d');
        0, 0, img.width, img.height, // source dimensions
        0, 0, 50, 50                 // destination dimensions
    var pth = path.join(BUILD_DIR,"resized_bird.jpg");
    PImage.encodeJPEGToStream(img2,fs.createWriteStream(pth)).then(() => {
        console.log("done writing");


Thanks to Nodebox / EMRG for opentype.js

Thanks to Rosetta Code for Bresenham's in JS

Thanks to Kuba Niegowski for PngJS

Thanks to Eugene Ware for jpeg-js

Thanks for patches from: