POST extract_image_colors

Given a list of images or of image URLs, find the dominant colors.

For each color, a similarity rank, a weight factor, a color name and a color class are returned along with the RGB values. The rank represents the position of the color in the sorted list, starting with 1. The weight specifies the importance of a color relative to all other colors in the list. For example, if several colors are extracted from a single image, a weight of 35.0 means that the associated color covers 35.0% of the image, and all the other colors together cover 65.0% of the image. The weights will sum up to 100. The name is obtained from an internal color name list. Each color name is associated with one of the following eleven main color classes: red, pink, orange, green, yellow, blue, violet, brown, grey, black and white.

The sort order keeps similar colors together, mostly based on their hue, e.g. black, red, yellow, green, blue, white. Colors that are very close to each other are merged. Keep in mind that colors that are close in hue may vary greatly in brightness and saturation (e.g. dark reds may look grey or faint blues may look white). Hence, the sort order is subjective; it varies depending on factors such as the person, the monitor model, and the lighting conditions.

The number of colors to try to extract from each image can be specified using the target_number_colors option. If colors are not similar enough they will not be merged, and if colors are too similar they will always be merged, so this option is a guideline, not a firm number. The largest effective value is 10.

When multiple images are given, this option is applied to each separately. After that all the extracted colors are combined into a single list, and, finally, the limit option is applied to that list.

For example, suppose you have a solid dark blue image with light blue stripes. If hue difference between the blues is low, extract_image_colors might combine them into one returned color. If the target_number_colors value is 2 or more then the algorithm will attempt not to combine them, returning the colors separately, if they are not too similar. Likewise, if there were three distinct hues in the image, setting a target of 2 would force the algorithm to try to combine two of them. This won’t happen if the difference between the colors is too large.

This sample graphic illustrates the results of a color extraction on a set of images.

../_images/sample_extract_colors.png

Resource URL

https://multicolorengine.tineye.com/<company>/rest/extract_image_colors/

Image limitations

  • Image size: For optimal performance, uploaded images (those given by images[n] parameters) should be 200px in size in the smallest dimension. For example, 600x400 pixels is larger than required and it will take longer to transfer this file to your MulticolorEngine server. It would be faster to resize this image to be 300x200 and then send it. Smaller images may work, and need not be scaled up.
  • Image format: Accepted formats are JPEG, PNG, GIF (non-animated), BMP, and TIFF files.

Parameters

In addition to the Common parameters there are:

Images

Key Description
images[0] An image file object whose colors will be extracted.
... ...
images[n] (optional) An image file object whose colors will be extracted.

URLs

Key Description
urls[0] A URL of an image file whose colors will be extracted.
... ...
urls[n] (optional) A URL of an image file whose colors will be extracted.

For images or URLs

ignore_background (optional) Whether to detect and ignore the background region of the image files, can be either true or false, defaults to true.
ignore_interior_background (optional) Whether to detect and ignore regions that have the same color as the background region but are surrounded by one or more non background regions, can be either true or false, defaults to true.
target_number_colors (optional) The desired number of colors to be extracted from an image file. This option is meant to be used as a guideline. Use in conjunction with limit to limit the number of returned colors to an exact number.
limit (optional) The maximum number of colors to be extracted when processing multiple image files, defaults to 32.
color_format (optional) Return RGB or hex formatted colors, can be either rgb or hex, defaults to rgb.

Request example

Images

curl https://multicolorengine.tineye.com/<company>/rest/extract_image_colors/  \
     -F "images[0]=@image1.jpg"                                                \
     -F "images[1]=@image2.jpg"                                                \
     -F "ignore_background=false"                                              \
     -F "ignore_interior_background=false"                                     \
     -F "limit=10"                                                             \
     -F "color_format=rgb"

URLs

curl https://multicolorengine.tineye.com/<company>/rest/extract_image_colors/  \
     -F "urls[0]=http://example.com/image1.jpg"                                \
     -F "urls[1]=http://example.com/image2.jpg"                                \
     -F "target_number_colors=6"                                               \
     -F "color_format=hex"

Response example

JSON (RGB, 2 colors shown)

{
    "status": "ok",
    "error": [],
    "method": "extract_image_colors",
    "result": [
        {
            "color": [
                194,
                66,
                28
            ],
            "weight": 76.37,
            "name": "Rust",
            "rank": 1,
            "class": "Red"
        },
        {
            "color": [
                141,
                125,
                83
            ],
            "weight": 23.63,
            "name": "Clay Creek",
            "rank": 2,
            "class": "Grey"
        }
    ]
}

JSON (Hex, 2 colors shown)

{
    "status": "ok",
    "error": [],
    "method": "extract_image_colors",
    "result": [
        {
            "color": "261821",
            "weight": 50.46,
            "name": "Nero",
            "rank": 1,
            "class": "Black"
        },
        {
            "color": "484821",
            "weight": 49.53,
            "name": "Bronzetone",
            "rank": 2,
            "class": "Green"
        }
    ]
}

XML (RGB, 2 colors shown)

<?xml version="1.0" encoding="utf-8"?>
<data>
    <error/>
    <method>extract_image_colors</method>
    <result>
        <item>
            <class>Red</class>
            <color>
                <item>194</item>
                <item>66</item>
                <item>28</item>
            </color>
            <name>Rust</name>
            <rank>1</rank>
            <weight>76.37</weight>
        </item>
        <item>
            <class>Grey</class>
            <color>
                <item>141</item>
                <item>125</item>
                <item>83</item>
            </color>
            <name>Clay Creek</name>
            <rank>2</rank>
            <weight>23.63</weight>
        </item>
    </result>
    <status>ok</status>
</data>

XML (Hex, 2 colors shown)

<?xml version="1.0" encoding="utf-8"?>
<data>
    <error/>
    <method>extract_image_colors</method>
    <result>
        <item>
            <class>Black</class>
            <color>261821</color>
            <name>Nero</name>
            <rank>1</rank>
            <weight>50.46</weight>
        </item>
        <item>
            <class>Green</class>
            <color>484821</color>
            <name>Bronzetone</name>
            <rank>2</rank>
            <weight>49.53</weight>
        </item>
    </result>
    <status>ok</status>
</data>