image-clipper

Node.js module for clip & crop JPEG, PNG, WebP images purely using the native Canvas APIs, excellent compatibility with the Browser & Electron & NW.js (Node-webkit), itself doesn't relies on any image processing libraries.

Installation / Download

npm install image-clipper or bower install image-clipper or just download imageClipper.js from the git repo.

Quick Start

var ImageClipper = require('image-clipper');
var clipper = new ImageClipper();

var x = 20;
var y = 20;
var width = 100;
var height = 100;

clipper.loadImageFromUrl('/path/to/image.jpg', function() {
    this.crop(x, y, width, height)
    .resize(50, 50)
    .toFile('/path/to/image-cropped.jpg', function() {
       console.log('saved!');
   });
});

API Documentation

Differences between the server-side and the client-side on usage

1. Since server-side Node.js doesn't natively support Canvas, therefore you must to specify a Canvas implementation library, such as node-canvas. See usage
2. toFile() not support to write the resultant image to file in the truly Browsers (not contain Electron & NW.js)

Benefits for Electron & NW.js application

When we develop Electron or NW.js application, I found it's very inconvenient while using image processing libraries such as gm and sharp, when you publish your application, probably the first thing you have to do is to tell your user to install multiple local dependencies, known that gm relies on GraphicsMagick, sharp relies on libvips.

However, sometimes we just need to use a very small part of gm provided, and do some simple operations to image, use image-clipper to avoid your user to install those cumbersome things which may frustrated them.

Electron & NW.js provide a mixture of Node.js and Browser, image-clipper just right using the Browser's native ability of Canvas and the Node's ability of File I/O, no longer needed the Canvas implementation libraries. Moreover, image-clipper use native Canvas APIs to process images, therefore no longer needed to install any other image processing libraries too.

Your desktop application will remain more stable and lightweight and your user will be peace of mind.

Basic usage in the truly Browser

<img id="preview" alt="imageClipper preview">
<script src="./dist/imageClipper.js"></script>

var preview = document.getElementById('preview');
var clipper = new ImageClipper();
clipper.loadImageFromUrl('/path/to/image.jpg', function() {
    this.crop(x, y, width, height)
    .toDataURL(function(dataUrl) {
        console.log('cropped!');
        preview.src = dataUrl;
    });
});

Also usable via require.js

Supported browsers

See caniuse.com/canvas

API

You can see all possible usages of APIs in the Test Suite (server-side Node.js) and Test Suite (client-side Browser & Electron & NW.js), or run them to verify.

clipper.loadImageFromUrl(url, callback)

Load image from the given url. callback will be executed when loading is complete.

• url: the path where the source image
• callback: function()

Note: in all callbacks, allow using this to call instance methods

clipper.loadImageFromMemory(image)

Load image from the memory.

• image: anything ctx.drawImage() accepts, usually HTMLImageElement, HTMLCanvasElement, HTMLVideoElement or ImageBitmap. Keep in mind that origin policies apply to the image source, and you may not use cross-domain images without CORS.

clipper.loadImageFromUrl will eventually using this method to load image.

Below is an example:

clipper.loadImageFromMemory(image)
    .crop(x, y, width, height)
    .toDataURL(function(dataUrl) {
        console.log('cropped!');
    });

In this case, the best practice is to place the code in onload callback:

var image = new Image;
image.onload(function(){ clipper.loadImageFromMemory(...) });
image.src = '/path/to/image.jpg';

clipper.crop(x, y, width, height)

Crops the resultant image to the given width and height at the given x and y position.

• x: the x axis of the coordinate for the rectangle starting point
• y: the y axis of the coordinate for the rectangle starting point
• width: the rectangle's width
• height: the rectangle's height

clipper.toFile(path, callback)

Write the resultant image to file.

Note: in the Browser (not contain Electron & NW.js), this method is the equivalent of toDataURL, callback will still be executed and will be passed the result data URI.

• path: the path where the resultant image will be saved
• callback: a function to be executed when saving is complete

Below is an example:

clipper.loadImageFromUrl('/path/to/image.jpg', function() {
    this.crop(x, y, width, height)
    .toFile('/path/to/image-cropped.jpg', function() {
        console.log('saved!');
    });
});

clipper.toDataURL([quality, ]callback)

Return a string containing the data URI of current resultant canvas.

• quality: a Number between 1 and 100 indicating image quality.
• callback: function(dataUrl), a function to be executed when converting is complete, callback will be passed the result data URI.

Using on the server-side Node.js:

clipper.toDataURL(function(dataUrl) {...});
clipper.toDataURL(quality, function(dataUrl) {...});

in the Browser & Electron & NW.js, in addition to the above usages, below usages also be supported since converting is synchronized:

var dataUrl = clipper.toDataURL();
var dataUrl = clipper.toDataURL(quality);

If your application will run on both sides, the recommendation is using the "callback" way.

clipper.quality(quality)

Adjusts the jpeg and webp compression level. Level ranges from 0 to 100. Only supported if the requested type is image/jpeg or image/webp.

• quality: a Number between 1 and 100 indicating image quality.

Below is an example:

clipper.loadImageFromUrl('/path/to/image.jpg', function() {
    this.quality(68)
    .crop(x, y, width, height).toDataURL(function(dataUrl) {
        console.log('cropped!');
    });
});

clipper.resize(width [, height])

Resize the resultant image to the given width and height.

• width: Number of pixels wide
• height: Number of pixels high

To resize the resultant image to a width of 50px while maintaining aspect ratio:

clipper.resize(50);

To resize the resultant image to a height of 50px while maintaining aspect ratio:

clipper.resize(null, 50);

To resize the resultant image to fit a 50x100 rectangle (lose aspect ratio):

clipper.resize(50, 100);

clipper.clear(x, y, width, height)

Removes rectangular pixels from the given width and height at the given x and y position.

• x: the x axis of the coordinate for the rectangle starting point
• y: the y axis of the coordinate for the rectangle starting point
• width: Number of pixels wide will be removed
• height: Number of pixels high will be removed

Below is an example:

clipper.loadImageFromUrl('/path/to/image.jpg', function() {
    this.clear(50, 50, 100, 100)
    .crop(0, 0, 300, 300).toDataURL(function(dataUrl) {
        preview.src = dataUrl;
    });
});

clipper.reset()

Used to restore the canvas, useful after clear(), crop(), resize() called.

Below is an example:

clipper.loadImageFromUrl('/path/to/image.jpg', function() {
    this.clear(50, 50, 100, 100)
    .crop(0, 0, 300, 300)
    .toDataURL(function(dataUrl) {
        console.log('cropped, part of data has been cleared');

        this.reset()
        .crop(50, 50, 100, 100)
        .toDataURL(function(dataUrl2) {
            console.log('regained the cleared data:', dataUrl2);
        });
    });
});

clipper.injectNodeCanvas(Canvas)

Inject canvas implementation library into the context of instance. Can be used only on the sever-side Node.js.

Usage:

var ImageClipper = require('image-clipper');
var Canvas = require('canvas');
var clipper = new ImageClipper();

clipper.injectNodeCanvas(Canvas);

Be equivalent to:

var ImageClipper = require('image-clipper');
var Canvas = require('canvas');
var clipper = new ImageClipper({
    canvas: Canvas
});

clipper.getCanvas()

Return current Canvas object.

var canvas = clipper.getCanvas();
// canvas.width
// canvas.height

Testing

Testing on the server-side Node.js (with node-canvas)

npm test

Testing on the client-side (Browser & Electron & NW.js)

First install jasmine:

cd test/jasmine && bower install jasmine

Then you can run the tests using npm start and open http://localhost:9100/test/jasmine/runner.html

License

MIT, see the LICENSE file for detail.