POST compare¶

Resource URL
Performance
Image limitations
Parameters
- compute_enhanced_score
- compare_color
Response
Request examples
- Images
- URLs
Response examples

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

Resource URL ¶

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

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 compute_enhanced_score to false for faster comparisons.

Image limitations ¶

Image size: For optimal performance, images should be 600px in size in the smallest dimension. For example, 1200x800 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 900x600 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, WEBP, AVIF, GIF, BMP and TIFF files. Animated images are not supported.

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.
compute_enhanced_score (optional)	Compute a more stable score for the comparison (twice as slow), defaults to false.
compare_color (optional)	Compute color differences between the two images, defaults to false.

compute_enhanced_score ¶

Set the compute_enhanced_score request parameter to true to generate a more accurate score for your comparisons. compute_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:

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

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.

compare_color ¶

Set the compare_color 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_color) and the percentage of the area of the images that differ in color (color_percent_diff).

Comparing these two car images:

results in these colors being different:

and the returned differing colors (query_colors_diff and target_colors_diff):

Response ¶

Key	Description
filepath	The second image’s file path.
score	How closely the first image matches the second image.
match_percent	How much of the first image’s fingerprint overlaps the second image’s fingerprint, as a percentage.
query_overlap_percent	How much of the first image overlaps the second image, as a percentage.
target_overlap_percent	How much of the second image overlaps the first image, as a percentage.
query_match_rect	Location of the matching area in the first image.
target_match_rect	Location of the matching area in the second image.
overlay	A URL pointing to the overlay for this comparison. Returned when generate_overlay parameter is set to true.
score_enhanced	A more accurate score for how closely the images match each other. Returned when compute_enhanced_score parameter is set to true.

The locations returned by MobileEngine will always refer to the image used for comparison and are provided as bounding boxes. These bounding boxes will be described using four percentage values (left, right, top, bottom) computed relative to image’s dimensions.

Please note that if your image has solid color borders, those might be cropped out by MobileEngine. In that case the locations returned will only refer to the cropped version of the image.

Request examples ¶

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 examples ¶

JSON ¶

{
    "method": "compare",
    "status": "ok",
    "error": [],
    "result": [
        {
            "filepath": "match.jpg",
            "score": 65.1,
            "match_percent": 94.42,
            "query_overlap_percent": 99.86,
            "target_overlap_percent": 82.18,
            "query_match_rect": {
                "left": 12.8,
                "right": 97.56,
                "top": 28.33,
                "bottom": 86.33
            },
            "target_match_rect": {
                "left": 22.63,
                "right": 91.67,
                "top": 26.63,
                "bottom": 94.67
            },
            "score_enhanced": 47.4
        }
    ],
    "stats": {
        "time_download": 64.03,
        "time_resize": 83,
        "time_compare": 382.94,
        "time_total": 531.54
    },
    "query_image": {
        "filepath": "query.jpg"
    }
}

JSON (with generate_overlay)¶

{
    "method": "compare",
    "status": "ok",
    "error": [],
    "result": [
        {
            "filepath": "match.jpg",
            "score": 65.1,
            "match_percent": 94.42,
            "query_overlap_percent": 99.86,
            "target_overlap_percent": 82.18,
            "query_match_rect": {
                "left": 12.8,
                "right": 97.56,
                "top": 28.33,
                "bottom": 86.33
            },
            "target_match_rect": {
                "left": 22.63,
                "right": 91.67,
                "top": 26.63,
                "bottom": 94.67
            },
            "overlay": "overlay/?query=query.jpg&target=match.jpg&sc_2=0.966949&tr_2_x=168.221&tr_2_y=105.965&fd_2_z=1080.12&fd_2_x=290.786&fd_2_y=236.0&rot_1_y=0.0&rot_1_x=-0.523599&rot_1_z=0.0&rot_2_z=-0.00319876&rot_2_x=-0.52825&rot_2_y=0.0294281&fd_1_y=300.0&fd_1_x=400.446&fd_1_z=1400.89&compare=1",
            "score_enhanced": 47.4
        }
    ],
    "stats": {
        "time_download": 64.03,
        "time_resize": 83,
        "time_compare": 382.94,
        "time_total": 531.54
    },
    "query_image": {
        "filepath": "query.jpg"
    }
}

JSON (with compare_color)¶

{
    "method": "compare",
    "status": "ok",
    "error": [],
    "result": [
        {
            "compare_color": {
                "color_percent_diff": 35.77,
                "query_colors_diff": [
                    {
                        "color": [
                            46,
                            65,
                            208
                        ],
                        "class": "blue"
                    },
                    {
                        "color": [
                            89,
                            110,
                            210
                        ],
                        "class": "blue-light"
                    }
                ],
                "target_colors_diff": [
                    {
                        "color": [
                            179,
                            25,
                            22
                        ],
                        "class": "red-dark"
                    },
                    {
                        "color": [
                            178,
                            72,
                            71
                        ],
                        "class": "red"
                    }
                ]
            },
            "filepath": "match.jpg",
            "score": 65.1,
            "match_percent": 94.42,
            "query_overlap_percent": 99.86,
            "target_overlap_percent": 82.18,
            "query_match_rect": {
                "left": 12.8,
                "right": 97.56,
                "top": 28.33,
                "bottom": 86.33
            },
            "target_match_rect": {
                "left": 22.63,
                "right": 91.67,
                "top": 26.63,
                "bottom": 94.67
            },
            "score_color": 29
        }
    ],
    "stats": {
        "time_download": 64.03,
        "time_resize": 83,
        "time_compare": 382.94,
        "time_total": 531.54
    },
    "query_image": {
        "filepath": "query.jpg"
    }
}

XML ¶

<?xml version="1.0" encoding="utf-8"?>
<data>
    <method>compare</method>
    <status>ok</status>
    <error/>
    <result>
        <item>
            <filepath>match.jpg</filepath>
            <score>65.1</score>
            <match_percent>94.42</match_percent>
            <query_overlap_percent>99.86</query_overlap_percent>
            <target_overlap_percent>82.18</target_overlap_percent>
            <query_match_rect>
                <left>12.8</left>
                <right>97.56</right>
                <top>28.33</top>
                <bottom>86.33</bottom>
            </query_match_rect>
            <target_match_rect>
                <left>22.63</left>
                <right>91.67</right>
                <top>26.63</top>
                <bottom>94.67</bottom>
            </target_match_rect>
            <score_enhanced>47.4</score_enhanced>
        </item>
    </result>
    <stats>
        <time_download>64.03</time_download>
        <time_resize>83</time_resize>
        <time_compare>382.941</time_compare>
        <time_total>531.54/time_total>
    </stats>
    <query_image>
            <filepath>query.jpg</filepath>
    </query_image>
</data>

XML (with generate_overlay)¶

<?xml version="1.0" encoding="utf-8"?>
<data>
    <method>compare</method>
    <status>ok</status>
    <error/>
    <result>
        <item>
            <filepath>match.jpg</filepath>
            <score>65.1</score>
            <match_percent>94.42</match_percent>
            <query_overlap_percent>99.86</query_overlap_percent>
            <target_overlap_percent>82.18</target_overlap_percent>
             <query_match_rect>
                <left>12.8</left>
                <right>97.56</right>
                <top>28.33</top>
                <bottom>86.33</bottom>
            </query_match_rect>
            <target_match_rect>
                <left>22.63</left>
                <right>91.67</right>
                <top>26.63</top>
                <bottom>94.67</bottom>
            </target_match_rect>
            <overlay>overlay/?query=query.jpg&amp;target=match.jpg&amp;sc_2=0.966949&amp;tr_2_x=168.221&amp;tr_2_y=105.965&amp;fd_2_z=1080.12&amp;fd_2_x=290.786&amp;fd_2_y=236.0&amp;rot_1_y=0.0&amp;rot_1_x=-0.523599&amp;rot_1_z=0.0&amp;rot_2_z=-0.00319876&amp;rot_2_x=-0.52825&amp;rot_2_y=0.0294281&amp;fd_1_y=300.0&amp;fd_1_x=400.446&amp;fd_1_z=1400.89&amp;compare=1</overlay>
            <score_enhanced>47.4</score_enhanced>
        </item>
    </result>
    <stats>
        <time_download>64.03</time_download>
        <time_resize>83</time_resize>
        <time_compare>382.941</time_compare>
        <time_total>531.54/time_total>
    </stats>
    <query_image>
            <filepath>query.jpg</filepath>
    </query_image>
</data>

XML (with compare_color)¶

<?xml version="1.0" encoding="utf-8"?>
<data>
    <method>compare</method>
    <status>ok</status>
    <error/>
    <result>
        <item>
            <compare_color>
                <color_percent_diff>35.77</color_percent_diff>
                <query_colors_diff>
                    <item>
                        <color>
                            <item>46</item>
                            <item>65</item>
                            <item>208</item>
                        </color>
                        <class>blue</class>
                    </item>
                    <item>
                        <color>
                            <item>89</item>
                            <item>110</item>
                            <item>210</item>
                        </color>
                        <class>blue-light</class>
                    </item>
                </query_colors_diff>
                <target_colors_diff>
                    <item>
                        <color>
                            <item>179</item>
                            <item>25</item>
                            <item>22</item>
                        </color>
                        <class>red-dark</class>
                    </item>
                    <item>
                        <color>
                            <item>178</item>
                            <item>72</item>
                            <item>71</item>
                        </color>
                        <class>red</class>
                    </item>
                </target_colors_diff>
            </compare_color>
            <filepath>match.jpg</filepath>
            <score>65.1</score>
            <match_percent>94.42</match_percent>
            <query_overlap_percent>99.86</query_overlap_percent>
            <target_overlap_percent>82.18</target_overlap_percent>
            <query_match_rect>
                <left>12.8</left>
                <right>97.56</right>
                <top>28.33</top>
                <bottom>86.33</bottom>
            </query_match_rect>
            <target_match_rect>
                <left>22.63</left>
                <right>91.67</right>
                <top>26.63</top>
                <bottom>94.67</bottom>
            </target_match_rect>
            <score_color>29.0</score_color>
        </item>
    </result>
    <stats>
        <time_download>64.03</time_download>
        <time_resize>83</time_resize>
        <time_compare>382.941</time_compare>
        <time_total>531.54/time_total>
    </stats>
    <query_image>
            <filepath>query.jpg</filepath>
    </query_image>
</data>

Developers