node package manager


easy-gd Build Status

A simplified Node.js wrapper around GD image manipulation library with extra features:

Why should one use easy-gd?

Because it is fast. Easy-gd uses C++ buindings for libgd that add very little overhead. For example, it resizes images two times faster than gm, which executes graphicsmagick commands in the background.


Node.js 0.8-0.10.



sudo apt-get install libgd2-xpm-dev
npm install easy-gd

Mac OS X:

brew install gd
npm install easy-gd

Usage recipes

Resizing images

var gd = require('easy-gd')
var image, resized
image ='image-800x600.jpg') // Source image size is 800×600 
// Resize to feat into 100×100 box, yields 100×75 image 
resized = image.resize({width: 100, height: 100})
// Resize by width, yields 200×150 image 
resized = image.resize({width: 200})
// Resize by height, yields 267×200 image 
resized = image.resize({height: 200})
// Resize and crop to 100×100 
resized = image.crop({width: 100, height: 100})
resized = image.resize({width: 100, height: 100, method: 'crop'})
// Resize without resampling; faster but lowers the quality 
resized = image.resize({width: 100, height: 100, resample: false})
// Save the resized image'resized.jpg')

See also: Reading/writing files, Asynchronous processing, Image transform streams.

Placing a watermark

var gd = require('easy-gd')
var image, watermarked
image ='source-image.jpg')
// Place a logo at the center of the image 
watermarked = image.watermark('logo.png')
watermarked = image.watermark('logo.png', {x: 0.5, y: 0.5})
// At the left top corner 
watermarked = image.watermark('logo.png', {x: 0, y: 0})
// At the right bottom corner 
watermarked = image.watermark('logo.png', {x: 1, y: 1})
// Choose the most contrast position for a logo at the bottom 
watermarked = image.watermark('logo.png', [{x: 0, y: 1}, {x: 0.5, y: 1}, {x: 1, y: 1}])
// Using gd.Image object as a watermark 
var logo ='logo.png')
watermarked = image.watermark(logo)
// Save the watermarked image'watermarked.jpg')

See also: Reading/writing files, Reading/writing buffers, Reading/writing streams, Asynchronous processing, Error handling.

Reading/writing image files

var gd = require('easy-gd')
var image ='image.png')
// Do something to the image'processed.jpg', {quality: 90})

See also: Reading/writing buffers, Reading/writing streams, Asynchronous processing, Controlling the output format, Error handling.

Reading/writing buffers

var gd = require('easy-gd')
// Reading image from buffer 
var image =
// Saving image to a buffer 
var imageData =
// Using buffer as a watermark source 
var watermarked = image.watermark(imageData)

See also: Reading/writing files, Reading/writing streams, Asynchronous processing, Controlling the output format, Error handling.

Reading/writing streams

var gd = require('easy-gd')
// Reading image from stream, function (error, image) {
  if (!error) {
    // Process the image 
// Saving image to a stream, function (error) {
  if (!error) {
    // Some action 
// Using stream as a watermark source 
image.watermark(stream, function (error, watermarked) {
  if (!error) {
    // Process the watermarked image 

See also: Image transform streams, Reading/writing files, Reading/writing buffers, Controlling the output format, Error handling.

Image transform streams

All the image manipulation methods called directly on the module object produce chainable transform streams:

var gd = require('easy-gd')
// Making thumbnails 
  .pipe(gd.crop({width: 100, height: 100}))
// Watermarking 
// Changing image format 
// Combine everything 
    gd.resize({width: 800, height: 600})
      .watermark('logo.png', {x:1, y:1})
      .options({format: 'jpeg', quality: '90'})

See also: Reading/writing files, Reading/writing buffers, Reading/writing streams, Controlling the output format, Error handling.

Synchronous image processing

With easy-gd you can synchronously process files and buffers:

var gd = require('easy-gd')
// Processing files'input.png')
  .resize({width: 800, height: 600})
  .save('output.jpg', {quality: 90})
// Processing buffers 
var outputData =
  .resize({width: 800, height: 600})
  .save({format: 'jpeg', quality: 90})

See also: Asynchronous processing, Error handling.

Asynchronous image processing

You can asynchronously process files, buffers and streams by passing additional callback argument:

var gd = require('easy-gd')
// Processing files'input.png', function (error, image) {
  if (error) throw error
  image.resize({width: 800, height: 600}, function (error, resized) {
    if (error) throw error'output.jpg', {quality: 90}, function (error) {
      if (error) throw error
// Processing buffers, function (error, image) {
  if (error) throw error
  image.resize({width: 800, height: 600}, function (error, resized) {
    if (error) throw error{format: 'jpeg', quality: 90}, function (error, outputData) {
      if (error) throw error
      // Process outputData buffer 
// Processing streams, function (error, image) {
  if (error) throw error
  image.resize({width: 800, height: 600}, function (error, resized) {
    if (error) throw error, {format: 'jpeg', quality: 90}, function (error) {
      if (error) throw error

See also: Image transform streams, Synchronous processing, Error handling.

Controlling the output format

var gd = require('easy-gd')
// Format is inherited from the source image 
var image ='input.jpg')
var resizedBuffer = image.resize({width: 100}).save() // Saved in JPEG 
// Format can be specified explicitly with target filename extension 
var image ='input.jpg')'output.png') // Saved in PNG 
// Format can be specified explicitly with save({format: 'format_name'}) 
var image ='input.jpg')
var pngBuffer ={format: 'png'}) // Saved in PNG 
// Target file extension has higher priority 
var image ='input.png')'output.jpg') // Saved in JPEG 

Format specification priority: filename extension > save 'format' option > inherited format.

See also: Controlling image quality/compression, Automatic filename extensions, Error handling.

Controlling image quality/compression

var gd = require('easy-gd')
var image ='input.jpg')
// Setting JPEG file quality, 0-100'output.jpg', {quality: 90})
// Setting PNG file compression level, 0-9'ouput.png', {compression: 6})
// Transform stream options 
inputStream.pipe(gd.options({format: 'jpeg', quality: 90}).pipe(outputStream)
// Buffer saving options 
var outputBuffer ={format: 'jpeg', quality: 90})
var outputBuffer ={format: 'png', compression: 6})

See also: Controlling the output format, Automatic filename extensions.

Automatic filename extensions

var gd = require('easy-gd')
var image ='input.jpg')'output.{ext}', {format: 'png'}) // Writes ouput.png 
var image ='input.jpg')
  .resize({width: 100})
  .save('output.{ext}') // Writes output.jpg since format was inherited 

See also: Controlling the output format, Controlling image quality/compression.

Reading Exif data

Exif data are being parsed automatically for JPEG images.

var gd = require('easy-gd')
var image ='input.jpg')
// Accessing Exif tags 
if (image.exif) {
  console.log('%s %s', image.exif.GPSLongitude, image.exif.GPSLatitude)
} else {
  console.log('No Exif data')

Note: image.exif property will be copied by resize() and other methods, but will not be written to the destination image.

See also: Automatic image orientation.

Automatic image orientation

GD does not process Exif data, resulting rotated images in the output. Easy-gd fixes this by automatically orienting the image.

var gd = require('easy-gd')
// The image gets automatically oriented by Exif data 
var image ='photo.jpg')
// Turn automatic orientation off 
var original ='photo.jpg', {autoOrient: false})
// Automatically orient existing image 
var rotated = original.autoOrient()

See also: Reading Exif data.

Error handling

var gd = require('easy-gd')
// Synchronous methods throw exceptions 
try {
  var image ='non-existent.png')
} catch (error) {
  console.log('Failed to open the image: %s', error)
// Asynchronous methods return errors as the first callback argument; 
// null means there was no error'non-existent.png', function (error, image) {
  if (error) {
    console.log('Failed to open the image: %s', error)
  // ... 
// Every error raised or returned by easy-gd is a descendant or gd.Error 
try {
} catch (error) {
  if (error instanceof gd.Error) {
    console.log('Image processing error: %s', error)
  } else {
    // Some other error happened 

There are some subclasses you can use to catch specific errors:

  • gd.UnknownSourceType - unknown source type.
  • gd.EmptySource - empty source file or buffer.
  • gd.UnknownImageFormat - unknown image format (or not an image at all).
  • gd.IncompleteImage - corrupted or incomplete image.
  • gd.UnsupportedOrientation - unsupported image Exif orientation tag value.
  • gd.DestinationFormatRequired - destination image format required.
  • gd.UnknownDestinationType - unknown destination type.
  • gd.FileOpen - file opening error.
  • gd.FileDoesNotExist - file does not exist.
  • gd.FileWrite - file writing error.
  • gd.SynchronousStreamAccess - a stream cannot be read or written synchronously.
  • gd.OptionsRequired - options argument should be passed in.