Imagga Color Extraction and Multi-Color Search API

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:

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:

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 ...

?>