POST compare

Given two images, compare them and return the match score (if any).

Resource URL

https://mobileengine.tineye.com/<company>/rest/compare/

Performance

The MobileEngine API can perform four simultaneous search or comparison operations combined. Any extra requests submitted will be queued up for processing as slots become available. Doing more than four at a time would actually reduce average response time, since the processes are CPU bound.

If you are comparing by image or filepath then operations are performed in the order in which they are received. If you are comparing by URL then the images are downloaded before the operations go into the queue. Thus, it may be advantageous to send a number of simultaneous URL-based requests. You should experiment with the effect of different numbers, since results will vary with things like download speed and network contention.

For maximum performance images should be pre-scaled, as described under Image Limitations below. Thus, in some cases where you could use URLs, it may be better to do the download yourself, scale the image, and send it in the request.

Checking for flips nearly doubles the time taken to perform a comparison; set check_horizontal_flip to false for faster comparisons.

Similarly, getting an enhanced score doubles the time taken to perform a comparison; set enhanced_score to false for faster comparisons.

Image limitations

  • Image size: For optimal performance, images should be 300px 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 MobileEngine server. It would be faster to resize this image to be 450x300 and then send it.
  • Image content: Some images may not contain enough detail to be compared. For example, images that are extremely small or contain only a single color will return an error.
  • Image format: Accepted formats are JPEG, PNG, GIF (non-animated), BMP, and TIFF files.

Parameters

A request may specify images or URLs, but not a mixture of both.

In addition to the Common parameters there are:

Key Description
image1 The first image file object that will be compared. Required if filepath1 or url1 is not specified.
filepath1 The collection path of the first image file that will be Required if image1 or url1 is not specified.
url1 The URL of the first image file that will be compared. Required if image1 or filepath1 is not specified.
image2 The second image file object that will be compared. Required if filepath2 or url2 is not specified.
filepath2 The collection path of the second image file that will be compared. Required if image2 or url2 is not specified.
url2 The URL of the second image file that will be compared. Required if image2 or filepath2 is not specified.
min_score (optional) The minimum score that should be returned, defaults to 0. Should be between 0 and 100 (inclusive).
check_horizontal_flip (optional) Whether the comparison incorporates checking for horizontal flips, defaults to false.
generate_overlay (optional) Whether an overlay URL will be generated and returned, defaults to false.
enhanced_score (optional) Compute a more stable score for the comparison (twice as slow), defaults to false.
color_compare (optional) Compute color differences between the two images, defaults to false.

enhanced_score

Set the enhanced_score request parameter to true to generate a more accurate score for your comparisons. enhanced_score will tell the API to run two comparison instead of one, and so will be twice as slow as a normal comparison. The API will run an second comparison on the overlay generated from the first comparison.

For example, comparing these two images returns a score of 25.4:

../_images/364069_a_small.jpg ../_images/364069_a_rotated.jpg

However, asking for an enhanced score would run the earlier comparison’s overlay through a second comparison pass (overlay slightly sized down):

../_images/364069_overlay.jpg

which is sent to a second comparison pass. This second comparison will return what we call an enhanced score (named score_enhanced in the API response) of 53.3.

color_compare

Set the color_compare request parameter to true to run a color comparison between the two images. The API will extract colors that are different between the two images (query_colors_diff, target_colors_diff), and return those to you as well as a score representing how closely the colors match (score_colors) and the percentage of the area of the images that differ in color (color_percent_diff).

Comparing these two car images:

../_images/original_blue_car.jpg ../_images/original_red_car.jpg

results in these colors being different:

../_images/diff_blue_car.png ../_images/diff_red_car.png

and the returned differing colors (query_colors_diff and target_colors_diff):

../_images/data_blue_car.png ../_images/data_red_car.png

Response

Key Description
score How closely the image matches the query image.
filepath The matching image’s file path.
match_percent How much the images overlap each other, as a percentage.
query_overlap_percent How much of the query image overlaps the matching image, as a percentage.
target_overlap_percent How much of the match image overlaps the query image, as a percentage.
overlay A URL pointing to the overlay for this search. Returned when generate_overlay parameter is set to true.
score_enhanced A more accurate score for how closely the image matches the query image. Returned when enhanced_score parameter is set to true.

Request example

Images

curl https://mobileengine.tineye.com/<company>/rest/compare/     \
     -F "image1=@query.jpg"                                      \
     -F "image2=@match.jpg"

URLs

curl https://mobileengine.tineye.com/<company>/rest/compare/     \
     -F "url1=http://example.com/query.jpg"                      \
     -F "url2=http://example.com/match.jpg"

Response example

JSON

{
    "status": "ok",
    "error": [],
    "method": "compare",
    "result": [
        {
            "target_overlap_percent": 82.18,
            "query_overlap_percent": 99.86,
            "filepath": "match.jpg",
            "score_enhanced": 47.4,
            "score": 65.1,
            "match_percent": 94.42
        }
    ]
}

JSON (with generate_overlay)

{
    "status": "ok",
    "error": [],
    "method": "compare",
    "result": [
        {
            "target_overlap_percent": 82.18,
            "filepath": "match.jpg",
            "overlay": "overlay/?query=query.jpg&target=match.jpg&fd_2=735.361&fd_1=760.714&sc_2=0.985895&tr_2_x=-1.87551&tr_2_y=-0.792598&rot_1_y=0.349066&rot_1_x=0.0&rot_1_z=0.0&rot_2_z=0.00328435&rot_2_x=-0.0159526&rot_2_y=0.332645&compare=1",
            "query_overlap_percent": 99.86,
            "score_enhanced": 47.4,
            "score": 65.1,
            "match_percent": 94.42
        }
    ]
}

JSON (with color_compare)

{
    "status": "ok",
    "error": [],
    "method": "compare",
    "result": [
        {
            "color_compare": {
                "color_percent_diff": 35.77,
                "target_colors_diff": [
                    {
                        "color": [
                            179,
                            25,
                            22
                        ],
                        "name": "Fire Brick",
                        "class": "Red"
                    },
                    {
                        "color": [
                            178,
                            72,
                            71
                        ],
                        "name": "Chestnut",
                        "class": "Brown"
                    }
                ],
                "query_colors_diff": [
                    {
                        "color": [
                            46,
                            65,
                            208
                        ],
                        "name": "Cerulean Blue",
                        "class": "Blue"
                    },
                    {
                        "color": [
                            89,
                            110,
                            210
                        ],
                        "name": "Slate Blue",
                        "class": "Blue"
                    }
                ]
            },
            "target_overlap_percent": 82.18,
            "query_overlap_percent": 99.86,
            "filepath": "match.jpg",
            "score": 65.1,
            "match_percent": 94.42,
            "score_colors": 29
        }
    ]
}

XML

<?xml version="1.0" encoding="utf-8"?>
<data>
    <error/>
    <method>compare</method>
    <result>
        <item>
            <filepath>match.jpg</filepath>
            <match_percent>94.42</match_percent>
            <query_overlap_percent>99.86</query_overlap_percent>
            <score>65.1</score>
            <score_enhanced>47.4</score_enhanced>
            <target_overlap_percent>82.18</target_overlap_percent>
        </item>
    </result>
    <status>ok</status>
</data>

XML (with generate_overlay)

<?xml version="1.0" encoding="utf-8"?>
<data>
    <error/>
    <method>compare</method>
    <result>
        <item>
            <filepath>match.jpg</filepath>
            <match_percent>94.42</match_percent>
            <overlay>overlay/?query=query.jpg&amp;target=match.jpg&amp;fd_2=735.361&amp;fd_1=760.714&amp;sc_2=0.985895&amp;tr_2_x=-1.87551&amp;tr_2_y=-0.792598&amp;rot_1_y=0.349066&amp;rot_1_x=0.0&amp;rot_1_z=0.0&amp;rot_2_z=0.00328435&amp;rot_2_x=-0.0159526&amp;rot_2_y=0.332645&amp;compare=1</overlay>
            <query_overlap_percent>99.86</query_overlap_percent>
            <score>65.1</score>
            <score_enhanced>47.4</score_enhanced>
            <target_overlap_percent>82.18</target_overlap_percent>
        </item>
    </result>
    <status>ok</status>
</data>

XML (with color_compare)

<?xml version="1.0" encoding="utf-8"?>
<data>
    <error/>
    <method>compare</method>
    <result>
        <item>
            <color_compare>
                <color_percent_diff>35.77</color_percent_diff>
                <query_colors_diff>
                    <item>
                        <class>Blue</class>
                        <color>
                            <item>46</item>
                            <item>65</item>
                            <item>208</item>
                        </color>
                        <name>Cerulean Blue</name>
                    </item>
                    <item>
                        <class>Blue</class>
                        <color>
                            <item>89</item>
                            <item>110</item>
                            <item>210</item>
                        </color>
                        <name>Slate Blue</name>
                    </item>
                </query_colors_diff>
                <target_colors_diff>
                    <item>
                        <class>Red</class>
                        <color>
                            <item>179</item>
                            <item>25</item>
                            <item>22</item>
                        </color>
                        <name>Fire Brick</name>
                    </item>
                    <item>
                        <class>Brown</class>
                        <color>
                            <item>178</item>
                            <item>72</item>
                            <item>71</item>
                        </color>
                        <name>Chestnut</name>
                    </item>
                </target_colors_diff>
            </color_compare>
            <filepath>match.jpg</filepath>
            <match_percent>94.42</match_percent>
            <query_overlap_percent>99.86</query_overlap_percent>
            <score>65.1</score>
            <score_colors>29.0</score_colors>
            <target_overlap_percent>82.18</target_overlap_percent>
        </item>
    </result>
    <status>ok</status>
</data>