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 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. Each color is associated with one or more of the following main color classes: white, black, grey-light, grey, grey-dark, red-light, red, red-dark, pink-light, pink, pink-dark, orange-light, orange, orange-dark, green-light, green, green-dark, yellow-light, yellow, yellow-dark, blue-light, blue, blue-dark, violet-light, violet, violet-dark, brown-light, brown and brown-dark.

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.

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

curl https://multicolorengine.tineye.com/<company>/rest/extract_image_colors/  \
     -F "image=@image1.jpg"                                                    \
     -F "ignore_background=true"                                               \
     -F "ignore_interior_background=true"                                      \
     -F "limit=10"                                                             \
     -F "color_format=hex"

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"

curl https://multicolorengine.tineye.com/<company>/rest/extract_image_colors/  \
     -F "url=http://example.com/image1.jpg"                                    \
     -F "target_number_colors=6"                                               \
     -F "color_format=rgb"

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"

{
    "method": "extract_image_colors",
    "status": "ok",
    "error": [],
    "result": [
        {
            "color": [
                194,
                66,
                28
            ],
            "rank": 1,
            "class": "orange-dark,red",
            "weight": 76.37
        },
        {
            "color": [
                141,
                125,
                83
            ],
            "rank": 2,
            "class": "brown-light",
            "weight": 23.63
        }
    ],
    "stats": {
        "time_resize": 41.47,
        "time_extract": 85.44,
        "time_total": 127.49
    }
}

{
    "method": "extract_image_colors",
    "status": "ok",
    "error": [],
    "result": [
        {
            "color": "262321",
            "rank": 1,
            "class": "black",
            "weight": 50.46
        },
        {
            "color": "484821",
            "rank": 2,
            "class": "brown,green-dark",
            "weight": 49.54
        }
    ],
    "stats": {
        "time_download": 160.25,
        "time_resize": 79.49,
        "time_extract": 118.85,
        "time_total": 359.52
    }
}

<?xml version="1.0" encoding="utf-8"?>
<data>
    <method>extract_image_colors</method>
    <status>ok</status>
    <error/>
    <result>
        <item>
            <color>
                <item>194</item>
                <item>66</item>
                <item>28</item>
            </color>
            <rank>1</rank>
            <class>orange-dark,red</class>
            <weight>76.37</weight>
        </item>
        <item>
            <color>
                <item>141</item>
                <item>125</item>
                <item>83</item>
            </color>
            <rank>2</rank>
            <class>brown-light</class>
            <weight>23.63</weight>
        </item>
    </result>
    <stats>
        <time_resize>41.47</time_resize>
        <time_extract>85.44</time_extract>
        <time_total>127.49</time_total>
    </stats>
</data>

<?xml version="1.0" encoding="utf-8"?>
<data>
    <method>extract_image_colors</method>
    <status>ok</status>
    <error/>
    <result>
        <item>
            <color>262321</color>
            <rank>1</rank>
            <class>black</class>
            <weight>50.46</weight>
        </item>
        <item>
            <color>484821</color>
            <rank>2</rank>
            <class>brown,green-dark</class>
            <weight>49.54</weight>
        </item>
    </result>
    <stats>
        <time_download>160.25</time_download>
        <time_resize>79.49</time_resize>
        <time_extract>118.85</time_extract>
        <time_total>359.52</time_total>
    </stats>
</data>