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, a color name and a color class are returned along with the RGB values. The rank is just 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 to 100. The name is obtained from a list containing thousands of color names extracted from various sources. 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, 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.

../_images/sample_extract_colors.png

Resource URL

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

Parameters

In addition to the Common parameters there are:

Collection

Key Description
limit (optional) The maximum number of colors to be extracted, defaults to 32.
color_format (optional) RGB or hex formatted colors, can be either rgb or hex, defaults to rgb.

Metadata

Key Description
metadata The metadata to be used for image filtering.
limit (optional) The maximum number of colors to be extracted, defaults to 32.
color_format (optional) RGB or hex formatted colors, can be either rgb or hex, defaults to rgb.

Colors

Key Description
colors[0] A color to be used for image filtering. Can be entered as either RGB format (255,255,255) or hex format (ffffff).
... ...
colors[n] (optional) A color to be used for image filtering.
weights[0] (optional but required for all colors if specified) A weight for the first color, should be between 1 and 100 and add up to 100.
... ...
weights[n] (optional) A weight for the nth color.
limit (optional) The maximum number of colors to be extracted, defaults to 32.
color_format (optional) RGB or hex formatted colors, can be either rgb or hex, defaults to rgb.

Filepaths

Key Description
filepaths[0] An image file from the collection whose colors will be extracted.
... ...
filepaths[n] (optional) An image file from the collection whose colors will be extracted.
limit (optional) The maximum number of colors to be extracted, defaults to 32.
color_format (optional) RGB or hex formatted colors, can be either rgb or hex, defaults to rgb.

Request example

Collection

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

Metadata

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"

Colors

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"

Filepaths

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"

Response example

JSON (RGB, 2 colors shown)

{
    "status": "ok",
    "error": [],
    "method": "extract_collection_colors",
    "result": [
        {
            "color": [
                141,
                125,
                83
            ],
            "weight": 76.37,
            "name": "Clay Creek",
            "rank": 1,
            "class": "Grey"
        },
        {
            "color": [
                35,
                22,
                19
            ],
            "weight": 23.63,
            "name": "Seal Brown",
            "rank": 2,
            "class": "Black"
        }
    ]
}

JSON (Hex, 2 colors shown)

{
    "status": "ok",
    "error": [],
    "method": "extract_collection_colors",
    "result": [
        {
            "color": "11d45f",
            "weight": 78,
            "name": "Malachite",
            "rank": 1,
            "class": "Green"
        },
        {
            "color": "edc9af",
            "weight": 22,
            "name": "Desert Sand",
            "rank": 2,
            "class": "Brown"
        }
    ]
}

XML (RGB, 2 colors shown)

<?xml version="1.0" encoding="utf-8"?>
<data>
    <error/>
    <method>extract_collection_colors</method>
    <result>
        <item>
            <class>Grey</class>
            <color>
                <item>141</item>
                <item>125</item>
                <item>83</item>
            </color>
            <name>Clay Creek</name>
            <rank>1</rank>
            <weight>76.37</weight>
        </item>
        <item>
            <class>Black</class>
            <color>
                <item>35</item>
                <item>22</item>
                <item>19</item>
            </color>
            <name>Seal Brown</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_collection_colors</method>
    <result>
        <item>
            <class>Green</class>
            <color>11d45f</color>
            <name>Malachite</name>
            <rank>1</rank>
            <weight>78.0</weight>
        </item>
        <item>
            <class>Brown</class>
            <color>edc9af</color>
            <name>Desert Sand</name>
            <rank>2</rank>
            <weight>22.0</weight>
        </item>
    </result>
    <status>ok</status>
</data>