POST search¶
Given an image or the path of a file already in your collection, search against your collection and return any matches with corresponding scores.
Resource URL¶
https://wineengine.tineye.com/<company>/rest/search/
Performance¶
The WineEngine API can perform four simultaneous search operations. 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 searching by image or filepath then operations are performed in the order in which they are received. If you are searching 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.
Image limitations¶
- Image size: For optimal performance, images given by an image or url parameter should be 1000 pixels in size in the smallest dimension. For example, 1800x1500 pixels is larger than required and it will take longer to transfer this file to your WineEngine server. It would be faster to resize this image to be 1200x1000 and then send it. Smaller images may work, and need not be scaled up.
- Image content: Some images may not contain enough detail to be searched for effectively. For example, images that are extremely small will return an error.
- Image format: Accepted formats are JPEG, PNG, WEBP, GIF, BMP and TIFF files. Animated images are not supported.
Parameters¶
In addition to the Common parameters there are:
| Key | Description |
|---|---|
| image | The image file object that will be used to search against the collection. This is referred to as the query image. Required if filepath or url has not been specified. |
| filepath | The collection path to the image file that will be used to search against the collection. This is referred to as the query image. Required if image or url has not been specified. |
| url | The URL of the image file that will be used to search against the collection. This is referred to as the query image. Required if image or filepath has not been specified. |
| limit (optional) | The maximum number of matches that should be returned, defaults to 10. A value of -1 indicates no limit. |
| generate_overlay (optional) | Whether an overlay URL will be generated and returned, defaults to false. |
Suggested limit parameter¶
You can reliably depend on the first, highest scoring, match being the best. So, in general, there is no need to request more than one match. You can safely set the limit to 1 and avoid processing multiple results.
Response¶
| Key | Description |
|---|---|
| query[‘filepath’] | The query image’s file path. |
| query[‘metadata’] | Metadata pertaining to the query image’s label. Available metadata is:
|
| result[‘filepath’] | The collection image’s file path. |
| result[‘score’] | How closely the query image matches the collection image. |
| result[‘match_percent’] | How much of the query image’s fingerprint overlaps the collection image’s fingerprint, as a percentage. A match_percent less than 10.0 indicates a very small matching region that may contain only few matching letters from two similar words. These kind of matches can safely be thresholded out. |
| result[‘query_overlap_percent’] | How much of the query image overlaps the collection image, as a percentage. |
| result[‘target_overlap_percent’] | How much of the collection image overlaps the query image, as a percentage. |
| result[‘overlay’] | A URL pointing to the overlay for this search. Returned when generate_overlay parameter is set to true. |
| result[‘metadata’] | Metadata pertaining to the collection image’s label. Available metadata is:
|
Highlighting the wine label, vintage and variety info¶
The search response will include label, vintage and variety location information if available so that you can highlight them in your images. For example, the WineEngine API will return the following metadata for this query image:
{
"label_rect": {
"top": 33.33,
"right": 77.54,
"left": 11.71,
"bottom": 85.78
},
"vintage_year": 2016,
"vintage_rect": {
"top": 53.89,
"right": 60.46,
"left": 52.02,
"bottom": 56.89
},
"variety_type": "Pinot Grigio",
"variety_rect": {
"top": 49.22,
"right": 66.6,
"left": 24.76,
"bottom": 54.67
}
}
which can then be used to mask the rest of the image. label_rect can be used to highlight the label (shown here in red), vintage_rect can be used to show where the vintage year is located (shown here in blue) and and variety_rect can be used to show where the variety is located (shown here in green):
The locations returned by WineEngine 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 WineEngine. In that case the locations returned will only refer to the cropped version of the image.
Note on handling vintage year values¶
If the API response specifies a vintage year for the query image then you should always use that year.
The response will also provide vintage years for the collection images that are matched. In typical usage, you can ignore the vintage year provided for collection images. Very often the query and collection images have different vintages, as our algorithms do not use vintage as a criteria for a successful match.
However, in some cases the API may not be able to detect a vintage year for the query image. In that case you may want to use the vintage year found for the collection image as a guide to the possible vintage of query the label. However this gives you no more than an indication of a possible vintage year for the query label (you know that wine was made in that year).
Request examples¶
Response examples¶
JSON¶
{
"status": "ok",
"method": "search",
"error": [],
"query_image": {
"filepath": "query_image.jpg",
"metadata": {
"vintage_year": 2013,
"vintage_rect": {
"left": 39.5,
"right": 46.17,
"top": 36.4,
"bottom": 39.1
}
"variety_type": "Chardonnay",
"variety_rect": {
"left": 26.21,
"right": 52.89,
"top": 53.43,
"bottom": 61.88
},
"label_rect": {
"left": 8.25,
"right": 64.3,
"top": 25.6,
"bottom": 70.4
}
}
},
"result": [
{
"filepath": "h&b_label.jpg",
"score": 34,
"match_percent": 49.15,
"query_overlap_percent": 49.35,
"target_overlap_percent": 80.82,
"overlay": "overlay/?query=query_image.jpg&target=h%26b_label.jpg&sc_2=0.625942&tr_2_x=162.408&tr_2_y=534.414&fd_2_z=1262.32&fd_2_x=299.411&fd_2_y=342.536&rot_1_y=-0.349066&rot_1_x=-0.523599&rot_1_z=0.0&rot_2_z=0.163794&rot_2_x=-0.599223&rot_2_y=-0.282812&fd_1_y=480.25&fd_1_x=216.0&fd_1_z=784.5",
"metadata": {
"vintage_year": "2013",
"vintage_rect": {
"left": 48.35,
"right": 59.3,
"top": 15.1,
"bottom": 19.2
},
"variety_type": "Chardonnay",
"variety_rect": {
"left": 35.64,
"right": 63.21,
"top": 43.85,
"bottom": 50.31
},
"label_rect": {
"left": 2.48,
"right": 92.3,
"top": 0,
"bottom": 68.51
}
}
}
]
}
XML¶
<?xml version="1.0" encoding="utf-8"?>
<data>
<status>ok</status>
<method>search</method>
<error/>
<query_image>
<filepath>query_image.jpg</filepath>
<metadata>
<vintage_year>2013</vintage_year>
<vintage_rect>
<left>39.5</left>
<right>46.17</right>
<top>36.4</top>
<bottom>39.1</bottom>
</vintage_rect>
<variety_type>Chardonnay</variety_type>
<variety_rect>
<left>26.21</left>
<right>52.89</right>
<top>53.43</top>
<bottom>61.88</bottom>
</variety_rect>
<label_rect>
<left>8.25</left>
<right>64.3</right>
<top>25.6</top>
<bottom>70.4</bottom>
</label_rect>
</metadata>
</query_image>
<result>
<item>
<filepath>h&b_label.jpg</filepath>
<score>34.0</score>
<match_percent>49.15</match_percent>
<query_overlap_percent>49.35</query_overlap_percent>
<target_overlap_percent>80.82</target_overlap_percent>
<overlay>overlay/?query=query_image.jpg&target=h%26b_label.jpg&sc_2=0.625942&tr_2_x=162.408&tr_2_y=534.414&fd_2_z=1262.32&fd_2_x=299.411&fd_2_y=342.536&rot_1_y=-0.349066&rot_1_x=-0.523599&rot_1_z=0.0&rot_2_z=0.163794&rot_2_x=-0.599223&rot_2_y=-0.282812&fd_1_y=480.25&fd_1_x=216.0&fd_1_z=784.5</overlay>
<metadata>
<vintage_year>2013</vintage_year>
<vintage_rect>
<left>48.35</left>
<right>59.3</right>
<top>15.1</top>
<bottom>19.2</bottom>
</vintage_rect>
<variety_type>Chardonnay</variety_type>
<variety_rect>
<left>35.64</left>
<right>63.21</right>
<top>43.85</top>
<bottom>50.31</bottom>
</variety_rect>
<label_rect>
<left>2.48</left>
<right>92.3</right>
<top>0</top>
<bottom>68.51</bottom>
</label_rect>
</metadata>
</item>
</result>
</data>