POST count_image_colors

Given a list of images or a list of image URLs and given a color palette, generate counters for each color from the palette specifying how many of the input images contain that color.

The response to this request will contain each input palette color along with two counters, a color name and a color class. The first counter (num_images_partial_area) gives how many of the input images contain the palette color (in any percentage). The second counter (num_images_full_area) gives how many of the input images contain the palette color in a very large percentage (are mostly covered by that color). 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.

Resource URL

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

Image limitations

  • Image size: For optimal performance, uploaded images (those given by image[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 counted.
... ...
images[n] (optional) An image file object whose colors will be counted.
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.
count_colors[0] A color which you want to count. Can be entered as either RGB format (255,255,255) or hex format (ffffff).
... ...
count_colors[n] (optional) A color which you want to count.

URLs

Key Description
urls[0] A URL of an image file whose colors will be counted.
... ...
urls[n] (optional) A URL of an image file whose colors will be counted.
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.
count_colors[0] A color which you want to count. Can be entered in either RGB format (255,255,255) or hex format (ffffff).
... ...
count_colors[n] (optional) A color which you want to count.

Request example

Images

curl https://multicolorengine.tineye.com/<company>/rest/count_image_colors/  \
     -F "images[0]=@image1.jpg"                                              \
     -F "images[1]=@image2.jpg"                                              \
     -F "ignore_background=false"                                            \
     -F "ignore_interior_background=false"                                   \
     -F "count_colors[0]=255,112,223"                                        \
     -F "count_colors[1]=95,136,165"                                         \
     -F "count_colors[2]=DF4F23"

URLs

curl https://multicolorengine.tineye.com/<company>/rest/count_image_colors/  \
     -F "urls[0]=http://example.com/image1.jpg"                              \
     -F "urls[1]=http://example.com/image2.jpg"                              \
     -F "count_colors[0]=255,112,223"                                        \
     -F "count_colors[1]=95,136,165"                                         \
     -F "count_colors[2]=DF4F23"

Response example

JSON

{
    "status": "ok",
    "error": [],
    "method": "count_image_colors",
    "result": [
        {
            "color": [
                255,
                112,
                223
            ],
            "num_images_full_area": 0,
            "name": "Pale Magenta",
            "num_images_partial_area": 0,
            "class": "Violet"
        },
        {
            "color": [
                95,
                136,
                165
            ],
            "num_images_full_area": 0,
            "name": "Air Force Blue",
            "num_ images_partial_area": 0,
            "class": "Blue"
        },
        {
            "color": "df4f23",
            "num_images_full_area": 1,
            "name": "Cinnabar",
            "num_images_partial_area": 1,
            "class": "Red"
        }
    ]
}

XML

<?xml version="1.0" encoding="utf-8"?>
<data>
    <error/>
    <method>count_image_colors</method>
    <result>
        <item>
            <class>Violet</class>
            <color>
                <item>255</item>
                <item>112</item>
                <item>223</item>
            </color>
            <name>Pale Magenta</name>
            <num_images_full_area>0</num_images_full_area>
            <num_images_partial_area>0</num_images_partial_area>
        </item>
        <item>
            <class>Blue</class>
            <color>
                <item>95</item>
                <item>136</item>
                <item>165</item>
            </color>
            <name>Air Force Blue</name>
            <num_images_full_area>0</num_images_full_area>
            <num_images_partial_area>0</num_images_partial_area>
        </item>
        <item>
            <class>Red</class>
            <color>df4f23</color>
            <name>Cinnabar</name>
            <num_images_full_area>1</num_images_full_area>
            <num_images_partial_area>1</num_images_partial_area>
        </item>
    </result>
    <status>ok</status>
</data>