easy-gd
A simplified Node.js wrapper around GD image manipulation library with extra features:
- Image format autodetection: just
gd.open(file)
instead of choosing between gd.createFromJpeg() or gd.createFromPng() or whatever. - Handy resizing and watermarking shortcuts:
image.resize({width: 100, height:100})
andimage.watermark('logo.png')
. - Reads/writes files, buffers and streams.
- Provides synchronous, asynchronous and transform stream interfaces.
- Has built-in Exif parsing and supports automatic image orientation.
- A drop-in replacement for node-gd. You can just
require('easy-gd')
instead ofrequire('node-gd')
and everything will be working as before.
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.
Compatibility
Node.js 0.8-0.10.
Installation
Ubuntu:
sudo apt-get install libgd2-xpm-devnpm install easy-gd
Mac OS X:
brew install gdnpm install easy-gd
Usage recipes
- Resizing images
- Placing a watermark
- Reading/writing image files
- Reading/writing buffers
- Reading/writing streams
- Image transform streams
- Synchronous image processing
- Asynchronous image processing
- Controlling the output format
- Controlling image quality/compression
- Automatic filename extensions
- Reading Exif data
- Automatic image orientation
- Error handling
Resizing images
var gd = var image resized image = gd // Source image size is 800×600 // Resize to feat into 100×100 box, yields 100×75 imageresized = image // Resize by width, yields 200×150 imageresized = image // Resize by height, yields 267×200 imageresized = image // Resize and crop to 100×100resized = imageresized = image // Resize without resampling; faster but lowers the qualityresized = image // Save the resized imageresized
See also: Reading/writing files, Asynchronous processing, Image transform streams.
Placing a watermark
var gd = var image watermarked image = gd // Place a logo at the center of the imagewatermarked = imagewatermarked = image // At the left top cornerwatermarked = image // At the right bottom cornerwatermarked = image // Choose the most contrast position for a logo at the bottomwatermarked = image // Using gd.Image object as a watermarkvar logo = gdwatermarked = image // Save the watermarked imagewatermarked
See also: Reading/writing files, Reading/writing buffers, Reading/writing streams, Asynchronous processing, Error handling.
Reading/writing image files
var gd = var image = gd // Do something to the image image
See also: Reading/writing buffers, Reading/writing streams, Asynchronous processing, Controlling the output format, Error handling.
Reading/writing buffers
var gd = // Reading image from buffervar image = gd // Saving image to a buffervar imageData = image // Using buffer as a watermark sourcevar watermarked = image
See also: Reading/writing files, Reading/writing streams, Asynchronous processing, Controlling the output format, Error handling.
Reading/writing streams
var gd = // Reading image from streamgd // Saving image to a streamimage // Using stream as a watermark sourceimage
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 = // Making thumbnailsprocessstdin // Watermarkingprocessstdin // Changing image formatprocessstdin // Combine everythingprocessstdin
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 = // Processing filesgd // Processing buffersvar outputData = gd
See also: Asynchronous processing, Error handling.
Asynchronous image processing
You can asynchronously process files, buffers and streams by passing additional callback
argument:
var gd = // Processing filesgd // Processing buffersgd // Processing streamsgd
See also: Image transform streams, Synchronous processing, Error handling.
Controlling the output format
var gd = // Format is inherited from the source imagevar image = gdvar resizedBuffer = image // Saved in JPEG // Format can be specified explicitly with target filename extensionvar image = gdimage // Saved in PNG // Format can be specified explicitly with save({format: 'format_name'})var image = gdvar pngBuffer = image // Saved in PNG // Target file extension has higher priorityvar image = gdimage // 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 = var image = gd // Setting JPEG file quality, 0-100image // Setting PNG file compression level, 0-9image // Transform stream optionsinputStreaminputStreaminputStream
See also: Controlling the output format, Automatic filename extensions.
Automatic filename extensions
var gd = var image = gdimage // Writes ouput.png var image = gdimage // 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 = var image = gd // Accessing Exif tagsif imageexif console else console
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 = // The image gets automatically oriented by Exif datavar image = gd // Turn automatic orientation offvar original = gd // Automatically orient existing imagevar rotated = original
See also: Reading Exif data.
Error handling
var gd = // Synchronous methods throw exceptionstry var image = gd catch error console // Asynchronous methods return errors as the first callback argument;// null means there was no errorgd // Every error raised or returned by easy-gd is a descendant or gd.Errortry catch error if error instanceof gdError console 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.