Light-weight image processor for NodeJS

1. Overview
2. Installation
3. Usage
4. Supported formats
5. Colors specification
6. Note on transparent images
7. API
8. Open an image from file or buffer
9. Create a new blank image
10. Image operations
    1. Resize
    2. Scale
    3. Contain
    4. Cover
    5. Rotate
    6. Crop
    7. Blur
    8. Sharpen
    9. Mirror
    10. Flip
    11. Border
    12. Pad
    13. Adjust saturation
    14. Adjust lightness: lighten / darken
    15. Adjust hue
    16. Fade (adjust transparency)
    17. Opacify
    18. Paste
    19. Set pixel
    20. Set metadata
11. Getters
    1. Width
    2. Height
    3. Pixel
    4. Clone
    5. Extract / Copy
    6. Get as a Buffer
    7. JPEG
    8. PNG
    9. GIF
    10. Write to file
    11. Get metadata
12. Batch operations
13. Copyrights

Overview

This module provides comprehensive, fast, and simple image processing and manipulation capabilities.

There are no external runtime dependencies, which means you don't have to install anything else on your system.

This module is in active development. New features are being added.

Read the background for the development of this module.

Installation

npm install lwip

Or, clone this repo and cd lwip && npm install.

You can run tests with npm test.

Note: Installation of this module involves compiling native code. If npm install lwip failes, you probably need to setup your system. See instructions. Building on Windows with Visual Studio requires version 2013 or higher.

Usage

Typical workflow:

1. Open an image and get an image object.
2. Manipulate it.
3. Save to disk / Send image buffer over network / etc.

Example (batch operations):

// obtain an image object:
require('lwip').open('image.jpg', function(err, image){

  // check err...
  // define a batch of manipulations and save to disk as JPEG:
  image.batch()
    .scale(0.75)          // scale to 75%
    .rotate(45, 'white')  // rotate 45degs clockwise (white fill)
    .crop(200, 200)       // crop a 200X200 square from center
    .blur(5)              // Gaussian blur with SD=5
    .writeFile('output.jpg', function(err){
      // check err...
      // done.
    });

});

Example (non-batch):

var lwip = require('lwip');

// obtain an image object:
lwip.open('image.jpg', function(err, image){

  // check err...
  // manipulate image:
  image.scale(0.5, function(err, image){

    // check err...
    // manipulate some more:
    image.rotate(45, 'white', function(err, image){

      // check err...
      // encode to jpeg and get a buffer object:
      image.toBuffer('jpg', function(err, buffer){

        // check err...
        // save buffer to disk / send over network / etc.

      });

    });

  });

});

Supported formats

Decoding (reading):

• JPEG, 1 & 3 channels (grayscale & RGB).
• PNG, transparency supported.
• GIF, transparency supported. Animated GIFs can be read, but only the first frame will be retrieved.

Encoding (writing):

• JPEG, 3 channels (RGB).
• PNG (lossless), 3 channels (RGB) or 4 channels (RGBA).
• GIF (no animations)

Other formats may also be supported in the future, but are probably less urgent. Check the issues to see which formats are planned to be supported. Open an issue if you need support for a format which is not already listed.

Colors specification

In LWIP colors are coded as RGBA values (red, green, blue and an alpha channel).

Colors are specified in one of three ways:

• As a string. possible values:

Javascript "black" // {r: 0, g: 0, b: 0, a: 100} "white" // {r: 255, g: 255, b: 255, a: 100} "gray" // {r: 128, g: 128, b: 128, a: 100} "red" // {r: 255, g: 0, b: 0, a: 100} "green" // {r: 0, g: 255, b: 0, a: 100} "blue" // {r: 0, g: 0, b: 255, a: 100} "yellow" // {r: 255, g: 255, b: 0, a: 100} "cyan" // {r: 0, g: 255, b: 255, a: 100} "magenta" // {r: 255, g: 0, b: 255, a: 100}

• As an array [R, G, B, A] where R, G and B are integers between 0 and 255 and A is an integer between 0 and 100.
• As an object {r: R, g: G, b: B, a: A} where R, G and B are integers between 0 and 255 and A is an integer between 0 and 100.

Note: The A value (alpha channel) is always optional and defaults to 100 (completely opaque).

Note on transparent images

1. Transparency is supported through an alpha channel which ranges between 0 and 100. 0 is completely transparent and 100 is completely opaque.
2. Not all formats support transparency. If an image with an alpha channel is encoded with a format which does not support transparency, the alpha channel will be ignored (effectively setting it to 100% for all pixels).

API

All operations are done on an image object. An image object can be obtained by:

1. Openning an existing image file or buffer with the open method.
2. Creating a new image object with the create method.
3. Cloning an existing image object with the image.clone method.
4. Extracting a sub-image from an existing image object with the image.extract method.

Open an image

lwip.open(source, type, callback)

1. source {String/Buffer}: The path to the image on disk or an image buffer.
2. type {String/Object}: Optional type of the image. If omitted, the type will be inferred from the file extension. If source is a buffer, type must be specified. If source is an encoded image buffer, type must be a string of the image type (i.e. "jpg"). If source is a raw pixels buffer type must be an object with type.width and type.height properties.
3. callback {Function(err, image)}

Note about raw pixels buffers: source may be a buffer of raw pixels. The buffer may contain pixels of 1-4 channels, where:

1. 1 channel is a grayscale image.
2. 2 channels is a grayscale image with an alpha channel.
3. 3 channels is an RGB image.
4. 4 channels is an RGBA image (with an alpha channel).

In other words, if the image in the buffer has width W and height H, the size of the buffer can be W*H, 2*W*H, 3*W*H or 4*W*H.

The channel values in the buffer must be stored sequentially. I.e. first all the Red values, then all the Green values, etc.

Open file example

var lwip = require('lwip');
lwip.open('path/to/image.jpg', function(err, image){
    // check 'err'. use 'image'.
    // image.resize(...), etc.
});

Open buffer example

var fs = require('fs'),
    lwip = require('lwip');

fs.readFile('path/to/image.png', function(err, buffer){
  // check err
  lwip.open(buffer, 'png', function(err, image){
      // check 'err'. use 'image'.
      // image.resize(...), etc.
  });
});

Create a new image

lwip.create(width, height, color, callback)

1. width {Integer>0}: The width of the new image.
2. height {Integer>0}: The height of the new image.
3. color {String / Array / Object}: Optional Color of the canvas. See colors specification. Defaults to a transparent canvas {r:0, g:0, b:0, a:0}.
4. callback {Function(err, image)}

Example:

var lwip = require('lwip');

lwip.create(500, 500, 'yellow', function(err, image){
  // check err
  // 'image' is a 500X500 solid yellow canvas.
});

Image operations

Resize

image.resize(width, height, inter, callback)

1. width {Integer}: Width in pixels.
2. height {Integer}: Optional height in pixels. If omitted, width will be used.
3. inter {String}: Optional interpolation method. Defaults to "lanczos". Possible values:
4. "nearest-neighbor"
5. "moving-average"
6. "linear"
7. "grid"
8. "cubic"
9. "lanczos"
10. callback {Function(err, image)}

Scale

image.scale(wRatio, hRatio, inter, callback)

1. wRatio {Float}: Width scale ratio.
2. hRatio {Float}: Optional height scale ratio. If omitted, wRatio will be used.
3. inter {String}: Optional interpolation method. Defaults to "lanczos". Possible values:
4. "nearest-neighbor"
5. "moving-average"
6. "linear"
7. "grid"
8. "cubic"
9. "lanczos"
10. callback {Function(err, image)}

Contain

Contain the image in a colored canvas. The image will be resized to the largest possible size such that it's fully contained inside the canvas.

image.contain(width, height, color, inter, callback)

1. width {Integer}: Canvas' width in pixels.
2. height {Integer}: Canvas' height in pixels.
3. color {String / Array / Object}: Optional Color of the canvas. See colors specification.
4. inter {String}: Optional interpolation method. Defaults to "lanczos". Possible values:
5. "nearest-neighbor"
6. "moving-average"
7. "linear"
8. "grid"
9. "cubic"
10. "lanczos"
11. callback {Function(err, image)}

Cover

Cover a canvas with the image. The image will be resized to the smallest possible size such that both its dimensions are bigger than the canvas's dimensions. Margins of the image exceeding the canvas will be discarded.

image.cover(width, height, inter, callback)

1. width {Integer}: Canvas' width in pixels.
2. height {Integer}: Canvas' height in pixels.
3. inter {String}: Optional interpolation method. Defaults to "lanczos". Possible values:
4. "nearest-neighbor"
5. "moving-average"
6. "linear"
7. "grid"
8. "cubic"
9. "lanczos"
10. callback {Function(err, image)}

Rotate

image.rotate(degs, color, callback)

1. degs {Float}: Clockwise rotation degrees.
2. color {String / Array / Object}: Optional Color of the canvas. See colors specification.
3. callback {Function(err, image)}

Crop

Crop with rectangle coordinates

image.crop(left, top, right, bottom, callback)

1. left, top, right, bottom {Integer}: Coordinates of the crop rectangle.
2. callback {Function(err, image)}

Crop a rectangle from center

image.crop(width, height, callback)

1. width, height {Integer}: Width and height of the rectangle to crop from the center of the image.
2. callback {Function(err, image)}

Blur

Gaussian blur.

image.blur(sigma, callback)

1. sigma {Float>=0}: Standard deviation of the Gaussian filter.
2. callback {Function(err, image)}

Sharpen

Inverse diffusion shapren.

image.sharpen(amplitude, callback)

1. amplitude {Float}: Sharpening amplitude.
2. callback {Function(err, image)}

Mirror

Mirror an image along the 'x' axis, 'y' axis or both.

image.mirror(axes, callback)

1. axes {String}: 'x', 'y' or 'xy' (case sensitive).
2. callback {Function(err, image)}

Flip

Alias of mirror.

Border

Add a colored border to the image.

image.border(width, color, callback)

1. width {Integer}: Border width in pixels.
2. color {String / Array / Object}: Optional Color of the border. See colors specification.
3. callback {Function(err, image)}

Pad

Pad image edges with colored pixels.

image.pad(left, top, right, bottom, color, callback)

1. left, top, right, bottom {Integer}: Number of pixels to add to each edge.
2. color {String / Array / Object}: Optional Color of the padding. See colors specification.
3. callback {Function(err, image)}

Saturate

Adjust image saturation.

image.saturate(delta, callback)

1. delta {Float}: By how much to increase / decrease the saturation.
2. callback {Function(err, image)}

Examples:

1. image.saturate(0, ...) will have no effect on the image.
2. image.saturate(0.5, ...) will increase the saturation by 50%.
3. image.saturate(-1, ...) will decrease the saturation by 100%, effectively desaturating the image.

Lighten

Adjust image lightness.

image.lighten(delta, callback)

1. delta {Float}: By how much to increase / decrease the lightness.
2. callback {Function(err, image)}

Examples:

1. image.lighten(0, ...) will have no effect on the image.
2. image.lighten(0.5, ...) will increase the lightness by 50%.
3. image.lighten(-1, ...) will decrease the lightness by 100%, effectively making the image black.