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");
Jimp.read("lenna.png", function (err, lenna) {
if (err) throw err;
lenna.resize(256, 256)
.quality(60)
.greyscale()
.write("lena-small-bw.jpg");
});
Using promises:
Jimp.read("lenna.png").then(function (lenna) {
lenna.resize(256, 256)
.quality(60)
.greyscale()
.write("lena-small-bw.jpg")
}).catch(function (err) {
console.error(err);
});
Basic usage
The static Jimp.read
method takes the path to a PNG, JPEG or BMP file and (optionally) a Node-style callback and returns a Promise:
Jimp.read("./path/to/image.jpg", function (err, image) {
});
Jimp.read("./path/to/image.jpg").then(function (image) {
}).catch(function (err) {
});
The method can also read a PNG, JPEG or BMP buffer:
Jimp.read(buffer, function (err, image) {
});
Once the callback is filed or the promise fulfilled, 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 );
image.opaque();
image.clone();
(Contributions of more methods are welcome!)
Writing to files and buffers
Writing to files
The image can be written to disk in PNG, JPEG or BMP format (determined by the file extension) using:
image.write( path, cb );
Writing to 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;
PNG and JPEG quality
The quality of JPEGs can be set with:
image.quality( n );
The format of 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;
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);
Creating new images
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 and (optionally) a Node-style callback:
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 instance methods can be chained together, for example as follows:
Jimp.read("lenna.png", function (err, image) {
this.greyscale().scale(0.5).write("lena-half-bw.png");
});
Alternatively, methods can be passed Node-style callbacks:
Jimp.read("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.