Jimp
The "JavaScript Image Manipulation Program" :-)
An image processing library for Node written entirely in JavaScript, with zero external or native dependencies.
Example usage:
var Jimp = require("jimp");
var lenna = new Jimp("lenna.png", function (err, image) {
this.resize(512, 512)
.write("lenna-small.png")
.quality(60)
.write("lenna-small.jpg")
.greyscale()
.write("lena-small-bw.png")
.crop(128, 192, 256, 128)
.write("lena-small-bw-cropped.png");
});
Basic usage
The Jimp constructor takes two arguments, the path to a PNG, JPEG or BMP image and a Node-style callback:
var image = new Jimp("./path/to/image.jpg", function (err, image) {
});
Once the callback has fired, the following methods can be called on the image:
image.crop( x, y, w, h );
image.invert();
image.flip( horz, vert);
image.gaussian( r );
image.blur( r );
image.greyscale();
image.sepia();
image.opacity( f );
image.resize( w, h );
image.scale( f );
image.rotate( deg[, resize] );
image.blit( src, x, y );
image.composite( src, x, y );
image.brightness( val );
image.contrast( val );
image.posterize( n );
image.mask( src, x, y );
image.dither565();
image.cover( w, h );
image.contain( w, h );
image.background( hex );
image.mirror( horz, vert);
image.fade( f );
(Contributions of more methods are welcome!)
Cloning images
To clone a Jimp image, you can use:
image.clone();
The Jimp constructor can also be called using an existing image create a clone of that image:
var clone = new Jimp(image, function (err, clone) {
});
Writing to files and buffers
Saving images
The image can be written to disk in PNG, JPEG or BMP format (determined by the file extension) using:
image.write( path, cb );
The quality of saved JPEGs can be set with:
image.quality( n );
The format of saved PNGs can be set with:
image.rgba( bool );
image.filterType( number );
image.deflateLevel( number );
For convenience, supported filter types are available as static properties:
Jimp.PNG_FILTER_AUTO;
Jimp.PNG_FILTER_NONE;
Jimp.PNG_FILTER_SUB;
Jimp.PNG_FILTER_UP;
Jimp.PNG_FILTER_AVERAGE;
Jimp.PNG_FILTER_PAETH;
Working with Buffers
A PNG, JPEG or BMP binary Buffer of an image (e.g. for storage in a database) can to got using:
image.getBuffer( mime, cb );
For convenience, supported MIME types are available as static properties:
Jimp.MIME_PNG;
Jimp.MIME_JPEG;
Jimp.BMP;
The Jimp constructor can also be called passing a valid Buffer as the first argument to the Jimp constructor:
var image = new Jimp(buffer, function (err, image) {
});
Advanced usage
Colour manipulation
Jimp supports advanced colour manipulation using a single method as follows:
image.color([
{ apply: 'hue', params: [ -90 ] },
{ apply: 'lighten', params: [ 50 ] },
{ apply: 'xor', params: [ '#06D' ] }
]);
The method supports the following modifiers:
Modifier | Description |
---|
lighten {amount} | Lighten the color a given amount, from 0 to 100. Providing 100 will always return white (works through TinyColor) |
brighten {amount} | Brighten the color a given amount, from 0 to 100 (works through TinyColor) |
darken {amount} | Darken the color a given amount, from 0 to 100. Providing 100 will always return black (works through TinyColor) |
desaturate {amount} | Desaturate the color a given amount, from 0 to 100. Providing 100 will is the same as calling greyscale (works through TinyColor) |
saturate {amount} | Saturate the color a given amount, from 0 to 100 (works through TinyColor) |
greyscale {amount} | Completely desaturates a color into greyscale (works through TinyColor) |
spin {degree} | Spin the hue a given amount, from -360 to 360. Calling with 0, 360, or -360 will do nothing - since it sets the hue back to what it was before. (works through TinyColor) |
hue {degree} | Alias for spin |
mix {color, amount} | Mixes colors by their RGB component values. Amount is opacity of overlaying color |
tint {amount} | Same as applying mix with white color |
shade {amount} | Same as applying mix with black color |
xor {color} | Treats the two colors as bitfields and applies an XOR operation to the red, green, and blue components |
red {amount} | Modify Red component by a given amount |
green {amount} | Modify Green component by a given amount |
blue {amount} | Modify Blue component by a given amount |
Low-level manipulation ###
Jimp enables low-level manipulation of images in memory through the bitmap property of each Jimp object:
image.bitmap.data;
image.bitmap.width;
image.bitmap.height
This data can be manipulated directly but remember: garbage in, garbage out.
A helper method is available to scan a region of the bitmap:
image.scan(x, y, w, h, cb);
Example usage:
image.scan(0, 0, image.bitmap.width, image.bitmap.height, function (x, y, idx) {
var red = this.bitmap.data[idx];
var green = this.bitmap.data[idx+1];
var blue = this.bitmap.data[idx+2];
var alpha = this.bitmap.data[idx+3];
});
Alternatively, you can manipulate individual pixels using the following these functions:
image.getPixelColor(x, y);
image.setPixelColor(hex, x, y);
Two static helper functions exist to convert RGBA values into single integer (hex) values:
Jimp.rgbaToInt(r, g, b, a);
Jimp.intToRGBA(hex);
If you want to begin with an empty Jimp image, you can call the Jimp constructor passing the width and height of the image to create:
var image = new Jimp(256, 256, function (err, image) {
});
You can optionally set the pixel colour as follows:
var image = new Jimp(256, 256, 0xFF0000FF, function (err, image) {
});
Chaining or callbacks
All methods can be chained together, for example as follows:
var lenna = new Jimp("lenna.png", function (err, image) {
this.greyscale().scale(0.5).write("lena-half-bw.png");
});
Alternatively, methods can be passed Node-style callbacks:
var lenna = new Jimp("lenna.png", function (err, image) {
image.greyscale(function(err, image) {
image.scale(0.5, function (err, image) {
image.write("lena-half-bw.png");
});
});
});
The Node-style callback pattern allows Jimp to be used with frameworks that expect or build on the Node-style callback pattern.
License
Jimp is licensed under the MIT license.