Imagga Color Extraction and Multi-Color Search API

This page explains how you can integrate our color extraction and mutli-color search functionality in your project.

Contents

Color Extraction API

The technology behind the API analyzes the pixel content of each given image in order to extract representative colors if the image.

Once the colors are extracted, the API customer can use them to organize their images, e.g. to group them by similar color, to display the color information alongside the images, to allow people to search in the image collection using keywords and checking them against the extracted color names or creating a color selection user interface and then finding images with (approximately) the same color.
You can get an immediate hands-on experience by testing our color extraction and multi-color search tool ColorsLike.me.

Color Extraction API Functionality

An input digital image defined by public image URL is analyzed. As a result of the analysis the API outputs up to five representative colors that approximate the various colors present in the input image. The API also tries to suggest up to three representative colors for both the foreground and the background of the image wherever such separation is possible.

Whether the systems has to extract only overall colors or only foreground and background colors or both can be specified by the API customer when making calls to the API.

The output data for each color contains RGB (Reg, Green, Blue) values defining the extracted color, the percentage of the color presence in the image, the respective HTML (Hyper Text Markup Language”) code of the color and the most similar color from a palette predefined and provided by the API customer, or a default palette if no palette is provided.

Color Extraction API Call

You need to make a POST request to a server-side script hosted in the API endpoint that your API account is associated to. The URL is:
http://<your-api-endpoint-here>/colorsearchserver.php

The parameters that should be supplied when making the POST request to this URL are given below.

Call POST parameters:
    • method
      required
    • The identifier of the particular method. For this particular call it is always fixed to imagga.colorsearch.extract
    • v
      required
    • The API version number. Currenly always fixed to 1.0
    • urls
      required (if upload_code is not present)
    • Comma-separated list of (one or more) public image URLs to be processed for color extraction.
      Example Value:
      http://www.stockpodium.com/stock-photo-8244245/smiling-presenting-2-apples-image.jpg,http://www.stockpodium.com/stock-photo-9289532/car-dirving-very-fast-under-image.jpg
    • upload_code
      required (if urls is not present)
    • Upload code generated after uploading image for processing, instead of providing URL. You can learn more about using upload for processing here.
      Example Value:
      73f/1365268432-951977319.png
    • delete_afterwards
      optional
    • This parameter is only meaningful if combined with upload_code. If its value is 1 the image that has been uploaded will be deleted after the processing task. Otherwise the image associated with the corresponding upload code will be available for other processings in the next one hour.
      Example Value: 1
    • ids
      optional
    • Comma-separated list of (one or more) numerical ids to serve as unique identifiers of the images whose color info should be stored in the index. The ids should be listed in the same order as the corresponding images in the urls parameter explained above. If this parameter is omitted or some of the ids are 0 (zero) the extracted info for the correspodning images is NOT stored in the API customer color search index. Example Value: 8244245,0
    • extract_overall_colors
      optional
    • Specify if the overall image colors should be extracted. The possbile values are 1 which means 'yes', and 0 which means 'no'.
      Default Value: 1
    • extract_object_colors
      optional
    • Specify if the service should try to extract object and non-object (a.k.a. foreground and background) colors separately. The possbile values are 1 which means 'yes', and 0 which means 'no'.
      Default Value: 1
    • api_key
      required
    • API customer key. This is the key you've been given when creating your API account.
      Example Value: aaaa1111bbbb2222
    • sig
      required
    • API call signature. The signature serve as simple and secure scheme to protect your call against spoofing and other identity thieft attacks. The signature is generated by hashing all current paramers and values and the API customer secret. More information about how to generate the signature can be found here.

If PHP is the language of your choice you can benefit from the existing implementation of this method as part of the Color API client included in the PHP API kit.

Sample call is given below.

Making the call using the PHP client library:
$color_api_client = new ColorAPIClient(IMAGGA_API_KEY, IMAGGA_API_SECRET, IMAGGA_API_ENDPOINT);

// eventually some other code here ...

try {
    $colors = $color_api_client->colors_by_urls(
        array(
			array(
				'id' => 8244245, // also store in the color-search index (with id 8244245)
				'url' => 'http://www.stockpodium.com/stock-photo-8244245/smiling-presenting-2-apples-image.jpg'
			),
			array(
				'id' => 0, // don't store the image color info in the index, only extract it for now
				'url' => 'http://www.stockpodium.com/stock-photo-9289532/car-dirving-very-fast-under-image.jpg'
			),
        ),
		1, // extract overall image colors
		1 // try to extract foreground and background colors separately
    );
}
catch (Exception $e) {
    echo 'Caught exception: ' . $e->getMessage();
}

Sample Response (the raw JSON encoded response that will be read by either your implementation or the existing PHP client library. Click below to expand!):
{
   "colors":[
      {
         "url":"http:\/\/www.stockpodium.com\/stock-photo-8244245\/smiling-presenting-2-apples-image.jpg",
         "info":{
            "image_colors":[
               {
                  "percent":"38.90",
                  "r":"247",
                  "g":"245",
                  "b":"243",
                  "html_code":"#f7f5f3",
                  "closest_palette_color":"white",
                  "closest_palette_color_parent":"white",
                  "closest_palette_distance":1.8304102578
               },
               {
                  "percent":"35.16",
                  "r":"206",
                  "g":"167",
                  "b":"146",
                  "html_code":"#cea792",
                  "closest_palette_color":"fresco",
                  "closest_palette_color_parent":"beige",
                  "closest_palette_distance":4.93287465177
               },
               {
                  "percent":"10.41",
                  "r":"150",
                  "g":"60",
                  "b":"45",
                  "html_code":"#963c2d",
                  "closest_palette_color":"ribbon red",
                  "closest_palette_color_parent":"red",
                  "closest_palette_distance":5.6423821179
               },
               {
                  "percent":"8.38",
                  "r":"55",
                  "g":"37",
                  "b":"31",
                  "html_code":"#37251f",
                  "closest_palette_color":"espresso",
                  "closest_palette_color_parent":"brown",
                  "closest_palette_distance":5.91329502182
               },
               {
                  "percent":"7.15",
                  "r":"168",
                  "g":"181",
                  "b":"45",
                  "html_code":"#a8b52d",
                  "closest_palette_color":"mint",
                  "closest_palette_color_parent":"olive green",
                  "closest_palette_distance":10.7126507469
               }
            ],
            "foreground_colors":[
               {
                  "percent":"45.92",
                  "r":"200",
                  "g":"180",
                  "b":"112",
                  "html_code":"#c8b470",
                  "closest_palette_color":"medium olive",
                  "closest_palette_color_parent":"skin",
                  "closest_palette_distance":7.22056402093
               },
               {
                  "percent":"34.21",
                  "r":"162",
                  "g":"79",
                  "b":"61",
                  "html_code":"#a24f3d",
                  "closest_palette_color":"fiesta",
                  "closest_palette_color_parent":"red",
                  "closest_palette_distance":6.29194294147
               },
               {
                  "percent":"19.86",
                  "r":"52",
                  "g":"35",
                  "b":"31",
                  "html_code":"#34231f",
                  "closest_palette_color":"espresso",
                  "closest_palette_color_parent":"brown",
                  "closest_palette_distance":6.49089812519
               }
            ],
            "background_colors":[
               {
                  "percent":"58.05",
                  "r":"249",
                  "g":"248",
                  "b":"247",
                  "html_code":"#f9f8f7",
                  "closest_palette_color":"white",
                  "closest_palette_color_parent":"white",
                  "closest_palette_distance":2.48109615666
               },
               {
                  "percent":"36.41",
                  "r":"206",
                  "g":"177",
                  "b":"161",
                  "html_code":"#ceb1a1",
                  "closest_palette_color":"pearl pink",
                  "closest_palette_color_parent":"light pink",
                  "closest_palette_distance":4.11506425614
               },
               {
                  "percent":"5.55",
                  "r":"150",
                  "g":"100",
                  "b":"77",
                  "html_code":"#96644d",
                  "closest_palette_color":"light bronze",
                  "closest_palette_color_parent":"skin",
                  "closest_palette_distance":6.37479340147
               }
            ],
            "object_percentage":38.4,
            "color_variance":"33"
         }
      },
      {
         "url":"http:\/\/www.stockpodium.com\/stock-photo-9289532\/car-dirving-very-fast-under-image.jpg",
         "info":{
            "image_colors":[
               {
                  "percent":"38.53",
                  "r":"103",
                  "g":"98",
                  "b":"98",
                  "html_code":"#676262",
                  "closest_palette_color":"blue steel",
                  "closest_palette_color_parent":"grey",
                  "closest_palette_distance":10.486937593
               },
               {
                  "percent":"26.31",
                  "r":"42",
                  "g":"37",
                  "b":"33",
                  "html_code":"#2a2521",
                  "closest_palette_color":"espresso",
                  "closest_palette_color_parent":"brown",
                  "closest_palette_distance":8.14492880108
               },
               {
                  "percent":"16.19",
                  "r":"178",
                  "g":"182",
                  "b":"190",
                  "html_code":"#b2b6be",
                  "closest_palette_color":"frost",
                  "closest_palette_color_parent":"light grey",
                  "closest_palette_distance":2.82095071372
               },
               {
                  "percent":"12.06",
                  "r":"197",
                  "g":"51",
                  "b":"45",
                  "html_code":"#c5332d",
                  "closest_palette_color":"fiesta",
                  "closest_palette_color_parent":"red",
                  "closest_palette_distance":5.41278686601
               },
               {
                  "percent":"6.91",
                  "r":"86",
                  "g":"97",
                  "b":"28",
                  "html_code":"#56611c",
                  "closest_palette_color":"moss",
                  "closest_palette_color_parent":"olive green",
                  "closest_palette_distance":9.97695248255
               }
            ],
            "foreground_colors":[
               {
                  "percent":"62.98",
                  "r":"199",
                  "g":"50",
                  "b":"43",
                  "html_code":"#c7322b",
                  "closest_palette_color":"fiesta",
                  "closest_palette_color_parent":"red",
                  "closest_palette_distance":5.44027296941
               },
               {
                  "percent":"22.01",
                  "r":"140",
                  "g":"132",
                  "b":"144",
                  "html_code":"#8c8490",
                  "closest_palette_color":"shadow",
                  "closest_palette_color_parent":"light grey",
                  "closest_palette_distance":3.40761167276
               },
               {
                  "percent":"15.01",
                  "r":"61",
                  "g":"38",
                  "b":"43",
                  "html_code":"#3d262b",
                  "closest_palette_color":"espresso",
                  "closest_palette_color_parent":"brown",
                  "closest_palette_distance":5.85441000013
               }
            ],
            "background_colors":[
               {
                  "percent":"41.07",
                  "r":"103",
                  "g":"97",
                  "b":"97",
                  "html_code":"#676161",
                  "closest_palette_color":"blue steel",
                  "closest_palette_color_parent":"grey",
                  "closest_palette_distance":10.6345471176
               },
               {
                  "percent":"39.63",
                  "r":"53",
                  "g":"51",
                  "b":"34",
                  "html_code":"#353322",
                  "closest_palette_color":"graphite",
                  "closest_palette_color_parent":"black",
                  "closest_palette_distance":9.18317865786
               },
               {
                  "percent":"19.29",
                  "r":"174",
                  "g":"180",
                  "b":"187",
                  "html_code":"#aeb4bb",
                  "closest_palette_color":"frost",
                  "closest_palette_color_parent":"light grey",
                  "closest_palette_distance":2.03931376316
               }
            ],
            "object_percentage":17.99,
            "color_variance":"37",
            "image_packed":null,
            "foreground_packed":null,
            "background_packed":null
         }
      }
   ]
}

Note: If you use the PHP kit client library you'll have the JSON response already decoded and returned as an Object that you can use in your code.

Multi-Color Search API

As expalined above - having the extracted colors, the API customers can handle a basic color search on their own. However, we also offer a dedicated live color-search API (where the extracted color matching/similarity is done on our servers) for customers who need a very fast and accurate color search or a search that needs to allow combination of multiple colors at the same time (the so called "multi-color search").

Multi-Color Search API Functionality

Perform multi-color similarity search among the images that have been processed by the API customer (via color extraction with provided id's) and are currently stored in the dedicated index.

The multi-color search aims to maximally approximate the human perception of how similar are two color combinations and thus to ranks the result images based on their colors' similarity to the query color combination (one or more colors with their prominance percentages that must total 100%).

Multi-Color Search API Call

Call POST parameters:
    • method
      required
    • The identifier of the particular method. For the multi-color search it shoukd be imagga.colorsearch.rank
    • v
      required
    • The API version number. Currenly always fixed to 1.0
    • color_vector
      required
    • Comma-separated list of (one or more) quadruples of interger values for 'percent, red, green, blue'. The percent should be in the range [1,100], and the reg, green, and blue values should be in the range [0, 255]. Up to five such quadruples can be listed as parts of the color combination.
      Example Value (that will search for the images with colors distribution similar to 60% red and 40% green):
      60,255,0,0,40,0,255,0
    • type
      required
    • This parameter specifies which type of color index should be used for the search. The possible values are:
      overall meaning to search in the color index that contains the color info for the whole images.
      object meaning to search in the color index that contains the color info for the main "object" (or foreground) in the images.
      background meaning to search in the color index that contains the color info for the background in the images.
      Note: Only images that are processed with the foreground/background option turned on during extraction are included in object and background indices.
      Example Value: overall
    • dist
      required
    • This is the so called 'similarity distance' tolerance. The larger this value, (eventually) the more results you get, though in this case the last results may not be that similar to the query color combination.
      Unfortunately there is no intuitive scale to use as a reference. The best approach is to experiment and see what works best in your particular case. Value around 3000 is a good starting point if you want to start experimenting or to use it out of the box.
      Example Value: 3000
    • count
      required
    • This limits how many results to be returned (even if more are available). The maximum value is 1000, meaning that no more than 1000 results may be returned as a response of this call.
      Example Value: 200
    • api_key
      required
    • API customer key. This is the key you've been given when creating your API account.
      Example Value: aaaa1111bbbb2222
    • sig
      required
    • API call signature. The signature serve as simple and secure scheme to protect your call against spoofing and other identity thieft attacks. The signature is generated by hashing all current paramers and values and the API customer secret. More information about how to generate the signature can be found here.

If PHP is the language of your choice you can benefit from the existing implementation of this method as part of the Color API client included in the PHP API kit.

Sample call is given below.

Making the call using the PHP client library:
$color_api_client = new ColorAPIClient(IMAGGA_API_KEY, IMAGGA_API_SECRET, IMAGGA_API_ENDPOINT);

// eventually some other code here ...

// the color combination below is hard coded, but in real-life scenario
// this combination is typically user-driven or part of the user experience/interface
$color_combination = array(
	array(
		'percent' => 60,
		'r' => 255,
		'g' => 0,
		'b' => 0
	),
	array(
		'percent' => 40,
		'r' => 0,
		'g' => 255,
		'b' => 0
	),
);

try {
	$similarly_colored_images = $color_api_client->rank_similar_color(
		$color_combination,
		3000,  // similar enough
		200  // only the first 200 most similar images
	);
}
catch (Exception $e) {
	// handling the exception here...
}
Sample Response (the raw JSON encoded response that will be read by either your implementation or the existing PHP client library. Click below to expand!):
{
  "rank_similarity":[
    {
      "id":8774077,
      "dist":2597.38299
    },
    {
      "id":9085916,
      "dist":2681.33259
    }
  ]
}

PHP API Kit

After you successfully register for an API account you are going to recieve an e-mail containing links to the API kits for several different platform, including PHP.
You'll be able to test the kit immediately after you deploy its content on some of your test servers and navigate a browser to the "color_demo.php" file.
Below is given a brief overview of the files in the kit.

The 'usual suspect' in the kit the is the "account_config.php" file where you need to fill in your API key, secret, and endpoint.

account_config.php
<?php

// please replace your_api_key_here with your actual Imagga API key
define('IMAGGA_API_KEY', 'your_api_key_here');

// please replace your_api_secret_here with your actual Imagga API secret
define('IMAGGA_API_SECRET', 'your_api_secret_here');

// please replace your_api_endpoint_here with your actual Imagga API endpoint
define('IMAGGA_API_ENDPOINT', 'your_api_endpoint_here');

?>

The API client (PHP class) that implements the calls to the particular color-related API methods

lib/color_api_client.php
<?php

// some legal words here...

class ColorAPIClient
{
	// the actual class implementation here ...
}


class ColorAPIClientException extends Exception
{
}

?>

And a sample script that demonstrate how to use the color API methods. This script instantiate the ColorAPIClient class mentioned above, call its methods and visualize the results. It can be used as a blue-print for further tests and/or actual production-mode usage of the API.

color_demo.php
<?php

// some other code here ...

include "account_config.php";  // include your API credentials
require_once "lib/color_api_client.php";  // include the API client library

$color_api_client = new ColorAPIClient(IMAGGA_API_KEY, IMAGGA_API_SECRET, IMAGGA_API_ENDPOINT);

// eventually some other code here ...

try {
    $colors = $color_api_client->colors_by_urls(/* parameters here... */);
}
catch (Exception $e) {
    // handling the exception here...
}

// some other code here ...

try {
    $similarly_colored_images = $color_api_client->rank_similar_color(/* parameters here... */);
}
catch (Exception $e) {
    // handling the exception here...
}

// some other code here ...

?>

Java API Kit

We have a Java API kit kindly donated! by Jakob Vad Nielsen on GitHub - https://github.com/lazee/imagga-java-kit.

Ruby API Kit

We have a Ruby API kit kindly donated! by Mart Karu on GitHub - https://github.com/martkaru/imagga.

Note: the Ruby kit doesn't implement the upload support yet. If you prefer uploading image rather than providing image URL you have to implement it on your own for now, based on the documentation above.

Python API Kit

We have a Python API kit kindly donated! by Ivan Penchev on GitHub - https://github.com/ivanpenchev/imagga-py.

Node.js API Kit

We have a Node.js API kit kindly donated! by Georgi Kostadinov on GitHub - https://github.com/gkostadinov/imagga-nodejs.

Samples

The Roll
'The Roll' is a mobile dashboard & gallery for your photos. It not only displays photos of places where you’ve been, but also sorts it by time, color etc. so you know when you’ve taken and shared them the most. It was one of the honorable mentions during Photo Hack Day 4. The app utilizes EyeEm API and Imagga Color API.
The source code is available on GitHub - https://github.com/eyeem/TheRoll/.

Instagram Color Search
'Instagram Color Search' is a demo web app that performs multi-color search in Instagram photos, developed by Georgi Kostadinov. The app utilizes Instagram API and Imagga Color API.
The source code is available on GitHub:
in PHP: https://github.com/gkostadinov/Instagram-Color-Search; and
in Python: https://github.com/gkostadinov/Instagram-Color-Search-Python.