GET extract_collection_colors¶

Given an entire image collection or given a subset of the collection filtered using metadata and/or a list of colors and/or a list of collection images, 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, i.e. black, red, yellow, green, blue, white. Colors which are very close to each other are merged. Keep in mind that colors which are close in hue, may vary greatly in brightness and saturation. For example a dark red may look grey or a faint blue may look white. This means that sort order people consider optimal is subjective. It can vary from person to person, from monitor to monitor, and in various lighting conditions.

Note that extracting colors from large collections can be time consuming. For this reason it should be done once and then cached if possible. For example extracting the dominant colors from a 100,000 image collection takes a few seconds, while extracting the dominant colors from a 1 million image collection takes a few minutes.

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

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

curl https://multicolorengine.tineye.com/<company>/rest/extract_collection_colors/ --get  \
     -d "limit=50"                                                                        \
     -d "color_format=hex"

curl https://multicolorengine.tineye.com/<company>/rest/extract_collection_colors/ --get        \
     -F "metadata='{\"_and_operator_\": [{\"keywords\": \"dog\"}, {\"keywords\": \"cat\"}]}'"   \
     -F "limit=50"                                                                              \
     -F "color_format=rgb"

curl https://multicolorengine.tineye.com/<company>/rest/extract_collection_colors/ --get  \
     -d "colors[0]=212,123,225"                                                           \
     -d "colors[1]=126,135,150"                                                           \
     -d "weights[0]=70"                                                                   \
     -d "weights[1]=30"                                                                   \
     -d "limit=50"                                                                        \
     -d "color_format=hex"

curl https://multicolorengine.tineye.com/<company>/rest/extract_collection_colors/ --get  \
     -d "filepaths[0]=path/folder/1.jpg"                                                  \
     -d "filepaths[1]=path/folder/2.jpg"                                                  \
     -d "limit=10"                                                                        \
     -d "color_format=rgb"

{
    "method": "extract_collection_colors",
    "status": "ok",
    "error": [],
    "result": [
        {
            "color": [
                141,
                125,
                83
            ],
            "rank": 1,
            "class": "brown-light",
            "weight": 76.37
        },
        {
            "color": [
                35,
                22,
                19
            ],
            "rank": 2,
            "class": "black",
            "weight": 23.63
        }
    ],
    "stats": {
        "time_extract": 4.98,
        "time_total": 5.52
    }
}

{
    "method": "extract_collection_colors",
    "status": "ok",
    "error": [],
    "result": [
        {
            "color": "11d45f",
            "rank": 1,
            "class": "green",
            "weight": 78
        },
        {
            "color": "edc9af",
            "rank": 2,
            "class": "pink-light",
            "weight": 22
        }
    ],
    "stats": {
        "time_extract": 7.74,
        "time_total": 8.28
    }
}

<?xml version="1.0" encoding="utf-8"?>
<data>
    <method>extract_collection_colors</method>
    <status>ok</status>
    <error/>
    <result>
        <item>
            <color>
                <item>141</item>
                <item>125</item>
                <item>83</item>
            </color>
            <rank>1</rank>
            <class>brown-light</class>
            <weight>76.37</weight>
        </item>
        <item>
            <color>
                <item>35</item>
                <item>22</item>
                <item>19</item>
            </color>
            <rank>2</rank>
            <class>black</class>
            <weight>23.63</weight>
        </item>
    </result>
    <stats>
        <time_extract>4.98</time_extract>
        <time_total>5.52</time_total>
    </stats>
</data>

<?xml version="1.0" encoding="utf-8"?>
<data>
    <method>extract_collection_colors</method>
    <status>ok</status>
    <error/>
    <result>
        <item>
            <rank>1</rank>
            <color>11d45f</color>
            <class>green</class>
            <weight>78.0</weight>
        </item>
        <item>
            <rank>2</rank>
            <color>edc9af</color>
            <class>pink-light</class>
            <weight>22.0</weight>
        </item>
    </result>
    <stats>
        <time_extract>7.74</time_extract>
        <time_total>8.28</time_total>
    </stats>
</data>