libgd C++ bindings for Node.js


GD graphic library, libgd, C++ bindings for Node.js. This version is the community-maintained official NodeJS node-gd repo. With node-gd you can easily create, manipulate, open and save paletted and true color images from and to a variety of image formats including JPEG, PNG, GIF and BMP.

$ sudo apt-get install libgd2-xpm-dev # libgd
$ npm install node-gd
$ sudo yum install gd-devel
$ npm install node-gd

Using Homebrew

$ brew install gd
$ npm install node-gd

...or using MacPorts

$ sudo port install gd2
$ npm install node-gd

Please open an issue if you have the answer. I'm sure it works, I just don't have ready the exact commands.

There are different flavours of images, of which the main ones are palette-based (up to 256 colors) and true color images (millions of colors). GIFs are always palette-based, PNGs can be both palette-based or true color. JPEGs are always true color images. gd.create() will create a palette-based base image while gd.createTrueColor() will create a true color image.

// Require library 
var gd = require('node-gd');
// Create blank new image in memory 
var img = gd.create(200, 80);
// Set background color 
img.colorAllocate(0, 255, 0);
// Set text color 
var txtColor = img.colorAllocate(255, 0, 255);
// Set full path to font file 
var fontPath = '/full/path/to/font.ttf';
// Render string in image 
img.stringFT(txtColor, fontPath, 24, 0, 10, 60, 'Hello world!');
// Write image buffer to disk 
img.savePng('output.png', 1, function(err) {
  if(err) {
    throw err;

Another example:

var gd = require('node-gd');
gd.openFile('/path/to/file.jpg', function(errimg) {
  if (err) {
    throw err;
  img.saveFile('/path/to/newFile.bmp', function(err) {
    if (err) {
      thorw err;
# Require library 
gd = require 'node-gd'
# Create blank new image in memory 
output_img = gd.create widthheight
# Load existing image file on disk into memory 
gd.openPng "test.png"(err, input_img) ->
  console.log "width: "input_img.width
  console.log "height: "input_img.width
# Render input over the top of output 
input_img.copyResampled output_imgdstXdstYsrcXsrcYdstWdstHsrcWsrcH
# Write image buffer to disk 
output_img.savePng "out.png"0(err) ->
  console.log "image saved!"

Create a new image in memory of specified size and return an instance of gd.Image. This is a paletted image, thus has a white background and a limited color range of at most 256 colors.

Returns an object of type gd.Image . This is a true color image, and thus has a black background and a palette of millions of colors.

Open a JPG file. If no callback is supplied, it will return an instance of gd.Image. In case of a supplied callback, it will receive two parameters: error and an instance of gd.Image. Uses fs.readFile() and gd.createFromJpegPtr() to load the image asynchronously.

var gd = require('node-gd');
// open Jpeg image 
gd.openJpeg('/path/to/file.jpg', function(errorimage) {
  if (error) {
    throw error;
  // save it as a PNG image 
  image.savePng('/path/to/file.png', 0, function(error) {
    if (error) {
      throw error;

Synchronous version of gd.openJpeg().

Load an image from a resource which is either a String or a Buffer.

Open a PNG file. The callback, if supplied, gets error and image as parameter. The image is an instance of gd.Image.

Synchronous version of gd.openPng().

Load an image from a resource.

Open a GIF file asynchronously.

Synchronous version of gd.openGif().

Open a WBMP image file. WBMP stands for Wireless Application Protocol Bitmap Format, a monochrome graphics file format.

Open a BMP bitmap image file.

GD will try to find out of what type the supplied image is, and will open it likewise. This is a quite new convenience method for if you don't exactly know what the type is that you will try to open.

A synchronous version of the above.

Returns an integer representation of the supplied color values.

var gd = require('node-gd');
var red = gd.trueColor(255, 0, 0); // 16711680 

Alternatively, you can use the hex notation for color values for parameters for GD likewise:

var red = 0xff0000; // red 

Returns an integer representation of the supplied rgba values. Be aware that in libgd the value for alpha ranges from 0 to 127. From its source code:

[the alpha channel] occupies only the
LOWER 7 BITS of the MSB (most significant
bit). This very small loss of alpha channel
resolution allows gd 2.x to keep backwards
compatibility (...)


var gd = require('node-gd');
var transparentRed = gd.trueColorAlpha(255, 0, 0, 63); // 1073676288 

Will return a string representing the version of your currently installed GD version. Outputs something like 2.1.1

Free up allocated memory for image data.

Set the color of a certain pixel. Use for color either 0xff00ff or gd.trueColor(255, 0, 255).

Draw a line from a certain point to a next point.

Draw a dashed line from a certain point to a next point.

Draw a closed polygon. The first parameter shoud be an Array of Objects containing an x and y property.

// draw a red triangle on a black background 
var gd = require('node-gd');
var img = gd.createTrueColor(100, 100);
var points = [
  { x: 10, y: 10 },
  { x: 70, y: 50 },
  { x: 30, y: 90 }
img.polygon(points, 0xff0000);
img.bmp('test.bmp', 0);

Same as the above but start and end point will not be connected with a line.

Same as the above but color value will be used to fill the polygon.

Create a rectangle. The x and y values indicate upper left and lower right corner respectively.

var gd = require('node-gd');
var img = gd.create(300, 200);
var color0 = img.colorAllocate(255,255,255);
var color1 = img.colorAllocate(255,0,255);
img.rectangle(20, 20, 280, 180, color1);

Create a filled rectangle i.e. a solid bar.

var gd = require('node-gd');
var img = gd.create(300, 200);
var color0 = img.colorAllocate(255,255,255);
var color1 = img.colorAllocate(255,0,255);
img.filledRectangle(20, 20, 280, 180, color1);

Draw an arc. cx and cy denote the center of the arc. The begin and end parameters are in degrees, from 0 to 360.

var gd = require('node-gd');
var img = gd.create(300, 200);
var color0 = img.colorAllocate(255, 255, 255);
var color1 = img.colorAllocate(255, 0, 255);
var color2 = img.colorAllocate(0, 255, 255);
img.arc(150, 100, 200, 160, 0, 270, color1);
img.arc(150, 100, 120, 120, 90, 0, color2);

Draw a filled arc.

Draw an ellipse.

Draw a filled ellipse.

Fill a drawn form up until its border.

var gd = require('node-gd');
var img = gd.create(300, 200);
var color0 = img.colorAllocate(255, 255, 255);
var color1 = img.colorAllocate(255, 0, 255);
var color2 = img.colorAllocate(0, 255, 255);
img.ellipse(150, 100, 160, 160, color2);
img.fillToBorder(150,100, 2, color1);

Set the thickness for lines.

var gd = require('node-gd');
var img = gd.create(300, 200);
var color0 = img.colorAllocate(255, 255, 255);
var color1 = img.colorAllocate(255, 0, 255);
img.line(0, 0, 300, 200, color1);
img.line(0, 200, 300, 0, color1);

Set the clipping area.

Returns an object containing the coordinates of the clipping area.

Unsigned integers should be used for res_x and res_y.

For paletted images, this will return the palette index of the color for that pixel.

This will return the color integer representation.

var gd = require('node-gd');
var img = gd.createTrueColor(300, 200);
var color = img.colorAllocate(255, 0, 255);
img.line(0, 0, 300, 200, color);
img.line(0, 200, 300, 0, color);
// will output ff00ff 
console.log(img.getTrueColorPixel(50, 50).toString(16));

This is the implementation of the PHP-GD specific method imagecolorat.

Returns 0 if either x or y are out of the bounds of the image canvas, or 1 when within the bounds.

The font color can be allocated with img.colorAllocate(r, g, b). The font parameter should be an absolute path to a ttf font file.

Allocate a color in the color table.

Allocate a color in the color table with transparency value.

Specifies a color index (if a palette image) or an RGB color (if a truecolor image) which should be considered 100% transparent. For truecolor images, this is ignored if an alpha channel is being saved. Use gd.Image#saveAlpha(0) to turn off the saving of a full alpha channel in a truecolor image.

Replace one color with another. This returns the amount of changes pixels.

Replace one color with another. The threshold will broaden the range of replaced colors and is a decimal Number between 0 and 100.

Replace colors in fromColors array to toColors array. The arrays should be of equal length.

Remove all color from an image and create a grayscaled image. Only available from libgd2 version 2.1.x.

Apply gaussian blur. Can by applied multiple times to an image to get more blur.

Invert the colors of the image.

Supply an integer between 0 and 100.

The value for contrast is a bit weird. A value of 100 wil return a complete grey image, with gray being exactly rgb(127, 127, 127). For best results, the range applied should be between -900 and 1100 (so actually 100 + 1000 and 100 - 1000).

Flip the image on the canvas over the vertical axis. This means that what's at the right side of the images will be reflected to the left side: pixels move only horizontally.

Flip the image on the canvas over the horizontal axis, the oposite of the above.

Flip the image on the canvas over both axes.

Crop the supplied image from a certain point to a certain size. Will return a new instance of gd.Image. Negative numbers, i.e. when going out of the image bounds, can result in images with black parts.

The mode parameter is a value from 0 to 4, so there are 5 modes: 0: default: 4 corners or background, 1: crop using the transparent color, 2: crop black borders, 3: crop white borders, 4: crop using colors of the 4 corners.

Crop by color, with a threshold. Use for color an integer and for threshold a number.

Does not work on non-true color images. A value lower than 0 for pct is ignored.

Create and return a new palette based image instance of gd.Image. The ditherFlag is either 0 or 1 (a Number, not a Boolean), colorsWanted a value between 1 and 256.

Modify the current image into a palette based image. The ditherFlag is either 0 or 1 (a Number, not a Boolean), colorsWanted a value between 1 and 256.

Modify the current image, if it is a palette based image, into a true color image. From libgd version 2.1.0 this returns either 0 or 1, in version 2.0.26 it is void.

The parameter should be a palette based image, which will be modified and which can be saved afterwards. The return value is a Number. This method tries to better match the colors from the palette based image to those of its true color original.

var gd = require('node-gd');
// open a true color image 
gd.openFile('/path/to/image.jpg', function(errtrueColor) {
  // create a new palette based image 
  var palette = trueColor.createPaletteFromTrueColor(1, 128);
  // match colors to enhance the result of the palette image 
  // save the palette based image 
  palette.saveFile('/path/to/result.gif', function(err) {
    if (err) {
      throw err;

Create an animated GIF.

  • anim is a String referencing a filename to be created, like ./anim.gif
  • useGlobalColorMap a value being -1, 0 or 1 which determines if the colorMap of the current image will be used as the global colorMap for the whole animation. -1 indicates do default.
  • The value for loops can be -1 for no looping, 0 means infinite looping, any other value the amount of loops the animation should run.
  • Add current image to the specified anim.
  • localColorMap is a flag indicating wether GD should use this image's colorMap
  • leftOffset and topOffset indicate the offset of this frame
  • the delay is the delay before next frame (in 1/100 sec)
  • disposal defines how this frame is handled when the next frame is loads. Usually this value should be set to 0, quote from gd's source: meaning that the pixels changed by this frame should remain on the display when the next frame begins to render
  • prevFrame should refer to the previous frame. If the current image is the first frame, supply null.

Write and close the GIF animation. A complete working example could look like this:

var gd = require('node-gd');
var anim = './anim.gif';
// create first frame 
var firstFrame = gd.create(200,200);
// allocate some colors 
var whiteBackground = firstFrame.colorAllocate(255, 255, 255);
var pink = firstFrame.colorAllocate(255, 0, 255);
// create first frame and draw an ellipse 
firstFrame.ellipse(100, -50, 100, 100, pink);
// start animation 
firstFrame.gifAnimBegin(anim, 1, -1);
firstFrame.gifAnimAdd(anim, 0, 0, 0, 5, 1, null);
var totalFrames = [];
for(var i = 0; i < 30; i++) {
totalFrames.forEach(function(iidxarr) {
  var frame = gd.create(200, 200);
  arr[idx] = frame;
  frame.ellipse(100, (* 10 - 40), 100, 100, pink);
  var lastFrame = i === 0 ? firstFrame : arr[- 1];
  frame.gifAnimAdd(anim, 0, 0, 0, 5, 1, lastFrame);

The functions gd.Image#savePng, gd.Image#saveJpeg, gd.Image#saveGif, etc. are convenience functions which will be processed asynchronously when a callback is supplied. All of the following have a counterpart like gd.Image#png and gd.Image#pngPtr which write to disk synchronously or store the image data in a memory pointer respectively. gd.Image#jpeg will return the instance of gd.Image, gd.Image#jpgPtr will return the newly created image data.

var gd = require('node-gd');
gd.openPng('/path/to/input.png', function(errimg) {
  if (err) {
    throw err;
  // create jpg pointer from png 
  var jpgImageData = img.jpegPtr(0); // jpeg quality 0 
  // create gif pointer from png 
  var gifImageData = img.gifPtr();
  // create instance of gd.Image() for jpg file 
  var jpgImage = gd.createFromJpegPtr(jpgImageData);
  jpgImage.saveFile('./test01.jpg', function(err) {
    if (err) throw err;
  // create instance of gd.Image() for gif file 
  var gifImage = gd.createFromGifPtr(gifImageData);
  gifImage.saveFile('./test01.gif', function(err) {
    if (err) throw err;

The above example shows how to create a JPEG and GIF file from a PNG file.

Save image data as a PNG file. The callback will receive an error object as a parameter, only if an error occurred. When a callback is supplied, the image will be written asynchronously by fs.writeFile(), using gd.Image#pngPtr() to first write it to memory in the given format.

Save image data as a JPEG file. The callback will receive an error object as a parameter. Quality can be a Number between 0 and 100.

Save image data as a GIF file.

Save image data as a GD file.

Save image data as a GD2 file.

Save image as a 2 color WBMP file. foreground is an integer value or 0x000000 value which defines the dark color of the image. All other colors will be changed into white.

Only available from GD version 2.1.1. The compression parameter is eiterh 0 for no compression and 1 for compression. This value only affects paletted images.

Currently, opening TIFF files with GD has some errors, but saving image data as TIFF works fine. Therefore, there is no gd.openTiff() at this moment. Only available from GD version 2.1.1.

Lets GD decide in which format the image should be stored to disk, based on the supplied file name extension. Only available from GD version 2.1.1.

Any instance of gd.Image() has a basic set of instance properties accessible as read only values.

var gd = require('node-gd');
var img = gd.creatTrueColor(100,100);

Will yield to something like:

  colorsTotal: 0,
  interlace: true,
  height: 100,
  width: 100,
  trueColor: 1

For paletted images, returns the amount of colors in the palette.

Boolean value for if the image is interlaced or not. This property can also be set. When set to true for Jpeg images, GD will save it as a progressive Jpeg image.

var gd = require('node-gd');
var img = gd.createTrueColor(100,100);
img.interlace = true; // set interlace to true 
// will save jpeg as progressive jpeg image. 
img.saveJpeg('/path/to/output.jpg', 100, function(err) {
  if (err) throw err;

Returns the height of the image as Number.

Returns the width of the image as Number.

Returns nonzero if the image is a truecolor image, zero for a palette image.

Be aware that since node-gd version 0.3.x libgd2 version 2.1.x is mostly supported. node-gd version 0.2.x is backed at best with libgd2 version 2.0.x. Run gdlib-config --version to check the version of libgd2 on your system. node-gd should build successfully for both libgd2 version 2.0.x as wel as for 2.1.x. The main difference is that some functions will not be available. These include:

  • toGrayscale()
  • emboss()
  • gaussianBlur()
  • negate()
  • brightness()
  • contrast()
  • selectiveBlur()
  • openBmp()
  • openFile()
  • createFromBmp()
  • createFromBmpPtr()
  • createFromFile()
  • saveBmp()
  • saveTiff()
  • saveImage()

Another way to check the installed GD version on your system:

var gd = require('node-gd');
// as of node-gd 0.4.x 
var version = gd.getGDVersion();
console.log(version); // 2.0.1 or 2.1.1 or the like 
$ npm test

The test/output/ directory contains the resulting images of the test script. The tests use, in some cases, a GNU Freefont font, which is licensed under the GNU General Public License v3.