What is this?

This is a Node.js client for Imagga's APIs.

Quick usage example

This quick example will load the module and will get the overall colors of an image.

Imagga = require('imagga');
imagga = new Imagga('<YOUR-IMAGGA-KEY>', '<YOUR-IMAGGA-SECRET>', '<YOUR-IMAGGA-ENDPOINT>');

imagga.color.colorsByUrls(
    {
        'id': 8244245,
        'url': 'http://www.stockpodium.com/stock-photo-8244245/smiling-presenting-2-apples-image.jpg'
    },
    {
        success: function(data) {
            # The data variable holds the overall colors of the image
            console.log(data);
        }
    }
);

Installation and setup

Firstly, you will have to install the module using this command in the terminal.

$ npm install imagga

Once you have installed it, in order to use it, you will have to require the library in your code.

Imagga = require('imagga')

Now create a new instance and set your key, secret and endpoint credentials.

imagga = new Imagga('<YOUR-IMAGGA-KEY>', '<YOUR-IMAGGA-SECRET>', '<YOUR-IMAGGA-ENDPOINT>');

That is it! Now use imagga.color for the color API or imagga.crop for the crop/slice API. imagga.utils and imagga itself both have some usefull methods too, which are described in the next paragraph.

Available methods

It is highly recommended that you follow the technical documentation located at Imagga's website - http://imagga.com/api/docs/

There is one main argument for all methods. This is the events object. If the method has completed successfully it will fire the success function in the events object, if an error occurs it will respectively fire the error function in the object. Note that both success and error functions are not required, but recommended. If there are none supplied, the module will print all output in the console. Those arguments marked italics are optional. Please refer to the technical documentation.

imagga.getApiUsage

Method: imagga.getApiUsage(events, startTime, endTime)

Quick description: Fetches user's API usage stats

Example usage:

imagga.getApiUsage({
    success: function(data) {
        # The API usage is fetched
    },
    error: function(type, error) {
        # An error occurred.
    }
})

imagga.utils.uploadForProcessing

Method: imagga.utils.uploadForProcessing(localFilePath, events)

Quick description: `Uploads an image in the endpoint server for future processing (returns an upload code)

Example usage:

# Any result will be outputed in the console
imagga.utils.uploadForProcessing('./test/file/image.jpg')

For the color API

imagga.color.colorsByUrls

Method: imagga.color.colorsByUrls(images, events, extractOverallColors, extractObjectColors)

Quick description: Fetches colors from given list of images

Example usage:

imagga.color.colorsByUrls(
    {
        'id': 8244245,
        'url': 'http://www.stockpodium.com/stock-photo-8244245/smiling-presenting-2-apples-image.jpg'
    },
    {
        success: function(data) {
            # The data variable holds the overall colors of the image
            console.log(data);
        }
    }
);

imagga.color.colorsByUploadCode

Method: imagga.color.colorsByUploadCode(uploadCode, events, deleteAfterwards, id, extractOverall, extractObjectColors)

Quick description: Gets the colors of an image by a given upload code

imagga.color.rankSimilarColor

Method: imagga.color.rankSimilarColor(colors, events, maxDist, maxCount, rankType)

Quick description: Perfoms an overall color similarity search

Example usage:

imagga.color.rankSimilarColor(
   [
        {
            'percent': 60,
            'r': 250,
            'g': 0,
            'b': 0
        },
        {
            'percent': 40,
            'r': 0,
            'g': 255,
            'b': 0
        }
    ],
    {
        success: function(data) {
            console.log(data);
        }
    }
);

imagga.color.rankSimilarColorObject

Method: imagga.color.rankSimilarColorObject(colors, events, maxDist, maxCount, rankType)

Quick description: Performs foreground color similarity search

imagga.color.rankSimilarColorBackground

Method: imagga.color.rankSimilarColorBackground(colors, events, maxDist, maxCount, rankType)

Quick description: Performs background color similarity search

For the crop/slice API

imagga.crop.divideRegionsByUrls

Method: imagga.crop.divideRegionsByUrls(images, events)

Quick description: Performs a region dividing using Imagga Collage Slicing API

imagga.crop.smartCropByUrls

Method: imagga.crop.smartCropByUrls(images, resolutions, events, noScaling)

Quick description: Performs a smart cropping for given image urls

Example usage:

imagga.crop.smartCropByUrls(
    [
        'http://www.stockpodium.com/stock-photo-7890736/couple-child-spending-time-together-image.jpg',
        'http://www.stockpodium.com/stock-photo-7314730/hand-keys-car-image.jpg'
    ],
    ['150x200', '100x50', '75x75'],
    {
        success: function(data) {
            console.log(data);
        }
    }
);

imagga.crop.smartCropByUploadcode

Method: imagga.crop.smartCropByUploadcode(uploadCode, resolutions, events, deleteAfterwards, noScaling)

Quick description: Performs a smart cropping for a local image.

imagga.crop.removeBackgroundByUrls

Method: imagga.crop.removeBackgroundByUrls(images, events)

Quick description: Performs a background removal using Imagga Background Removal API

Tests

If you would like to run the test suite, you can do this with the command:

$ npm test

Before you run the tests, you will have to change the config located in src/initialize.js

Note that you need the module assert. Install it using npm:

$ npm install assert