Skip to content

Commit

Permalink
Merge pull request #32 from tooolbox/master
Browse files Browse the repository at this point in the history 
Added syntax highlighting to readme.
  • Loading branch information
@oliver-moran
oliver-moran committed Aug 28, 2015
2 parents 7f5ddf0 + de6a65a commit 774f4d5
Showing 1 changed file with 107 additions and 75 deletions.
182 changes: 107 additions & 75 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,142 +6,174 @@ An image processing library for Node written entirely in JavaScript, with zero e

Example usage:

var Jimp = require("jimp");

// open a file called "lenna.png"
var lenna = new Jimp("lenna.png", function (err, image) {
this.resize(512, 512) // resize
.write("lenna-small.png") // save
.quality(60) // set JPEG quality
.write("lenna-small.jpg") // save as JPEG
.greyscale() // set greyscale
.write("lena-small-bw.png") // save again
.crop(128, 192, 256, 128) // crop
.write("lena-small-bw-cropped.png"); // save again
});
```js
var Jimp = require("jimp");

// open a file called "lenna.png"
var lenna = new Jimp("lenna.png", function (err, image) {
this.resize(512, 512) // resize
.write("lenna-small.png") // save
.quality(60) // set JPEG quality
.write("lenna-small.jpg") // save as JPEG
.greyscale() // set greyscale
.write("lena-small-bw.png") // save again
.crop(128, 192, 256, 128) // crop
.write("lena-small-bw-cropped.png"); // save again
});
```

## 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) {
// this is the image
});
```js
var image = new Jimp("./path/to/image.jpg", function (err, image) {
// this is the image
});
```

Once the callback has fired, the following methods can be called on the image:

image.crop( x, y, w, h ); // crop to the given region
image.invert(); // invert the image colours
image.flip( horz, vert); // flip the image horizontally or vertically
image.gaussian( r ); // Gaussian blur the image by r pixels (VERY slow)
image.blur( r ); // fast blur the image by r pixels
image.greyscale(); // remove colour from the image
image.sepia(); // apply a sepia wash to the image
image.opacity( f ); // multiply the alpha channel by each pixel by the factor f, 0 - 1
image.resize( w, h ); // resize the image
image.scale( f ); // scale the image by the factor f
image.rotate( deg ); // rotate the image clockwise by a number of degrees (rounded to multiples of 90)
image.blit( src, x, y ); // blit the image with another Jimp image at x, y
image.composite( src, x, y ); // composites another Jimp image over this iamge at x, y
image.brightness( val ); // adjust the brighness by a value -1 to +1
image.contrast( val ); // adjust the contrast by a value -1 to +1
image.posterize( n ); // apply a posterization effect with n level
image.mask( src, x, y ); // masks the image with another Jimp image at x, y using average pixel value
image.dither565(); // ordered dithering of the image and reduce color space to 16-bits (RGB565)
```js
image.crop( x, y, w, h ); // crop to the given region
image.invert(); // invert the image colours
image.flip( horz, vert); // flip the image horizontally or vertically
image.gaussian( r ); // Gaussian blur the image by r pixels (VERY slow)
image.blur( r ); // fast blur the image by r pixels
image.greyscale(); // remove colour from the image
image.sepia(); // apply a sepia wash to the image
image.opacity( f ); // multiply the alpha channel by each pixel by the factor f, 0 - 1
image.resize( w, h ); // resize the image
image.scale( f ); // scale the image by the factor f
image.rotate( deg ); // rotate the image clockwise by a number of degrees (rounded to multiples of 90)
image.blit( src, x, y ); // blit the image with another Jimp image at x, y
image.composite( src, x, y ); // composites another Jimp image over this iamge at x, y
image.brightness( val ); // adjust the brighness by a value -1 to +1
image.contrast( val ); // adjust the contrast by a value -1 to +1
image.posterize( n ); // apply a posterization effect with n level
image.mask( src, x, y ); // masks the image with another Jimp image at x, y using average pixel value
image.dither565(); // ordered dithering of the image and reduce color space to 16-bits (RGB565)
```

(Contributions of more methods are welcome!)

The image can be written to disk in PNG, JPEG or BMP format (determined by the file extension) using:

image.write( path, cb ); // Node-style callback will be fired when write is successful
```js
image.write( path, cb ); // Node-style callback will be fired when write is successful
```

The quality of saved JPEGs can be set with:

image.quality( n ); // set the quality of saved JPEG, 0 - 100
```js
image.quality( n ); // set the quality of saved JPEG, 0 - 100
```

## Cloning images ##

To clone a Jimp image, you can use:

image.clone(); // returns the clone
```js
image.clone(); // returns the 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) {
// this is the clone
});
```js
var clone = new Jimp(image, function (err, clone) {
// this is the clone
});
```

## 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 ); // Node-style callback wil be fired with result
```js
image.getBuffer( mime, cb ); // Node-style callback wil be fired with result
```

For convenience, supported MIME types are available as static properties:

Jimp.MIME_PNG; // "image/png"
Jimp.MIME_JPEG; // "image/jpeg"
Jimp.BMP; // "image/bmp"
```js
Jimp.MIME_PNG; // "image/png"
Jimp.MIME_JPEG; // "image/jpeg"
Jimp.BMP; // "image/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) {
// this is the image
});
```js
var image = new Jimp(buffer, function (err, image) {
// this is the image
});
```

## Direct manipulation ##

Jimp enables low-level manipulation of images in memory through the bitmap property of each Jimp object:

image.bitmap.data; // a Buffer of the raw bitmap data
image.bitmap.width; // the width of the image
image.bitmap.height // the height of the image
```js
image.bitmap.data; // a Buffer of the raw bitmap data
image.bitmap.width; // the width of the image
image.bitmap.height // the height of the image
```

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); // scan a given region of the bitmap and call cb on every pixel
```js
image.scan(x, y, w, h, cb); // scan a given region of the bitmap and call cb on every pixel
```

Example usage:

image.scan(0, 0, image.bitmap.width, image.bitmap.height, function (x, y, idx) {
// x, y is the position of this pixel on the image
// idx is the position start position of this rgba tuple in the bitmap Buffer
// this is the image
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];
// rgba values run from 0 - 255
// e.g. this.bitmap.data[idx] = 0; // removes red from this pixel
});
```js
image.scan(0, 0, image.bitmap.width, image.bitmap.height, function (x, y, idx) {
// x, y is the position of this pixel on the image
// idx is the position start position of this rgba tuple in the bitmap Buffer
// this is the image

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];

// rgba values run from 0 - 255
// e.g. this.bitmap.data[idx] = 0; // removes red from this pixel
});
```

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) {
// this image is 256 x 256, every pixel is set to 0x0
});
```js
var image = new Jimp(256, 256, function (err, image) {
// this image is 256 x 256, every pixel is set to 0x0
});
```

## 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");
});
```js
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");
});
```js
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.

Expand Down

0 comments on commit 774f4d5

Please sign in to comment.