Searching¶
Searching for an image¶
Now that you have added some images in the first tutorial, you are ready to search your collection.
As with adding an image, you can search for an image by specifying the url
where that image can be found or by uploading an image file from your server.
In this tutorial we will search using a url. In all of the examples replace
<company> with your WineEngine account name. If you are using password-based
authentication you must also add your username and password
(i.e. https://username:password@wineengine...).
curl https://wineengine.tineye.com/<company>/rest/search/ \
-F "url=https://img.tineye.com/samples/tutorials/joca_hand.jpg"
The cURL command issues a POST request which sends a parameter, url, to your WineEngine API, telling the API to download the image and search for it in your collection.
If there are no errors the server should reply with:
{
"status": "ok",
"method": "search",
"error": [],
"query_image": {
"filepath": "joca_hand.jpg",
"metadata": {
"label_rect": {
"top": 39.22,
"right": 76.53,
"left": 16.17,
"bottom": 74.11
},
"vintage_year": 2015,
"vintage_rect": {
"top": 61.78,
"right": 47.14,
"left": 37.28,
"bottom": 64.22
},
"variety_type": "Pinot Gris",
"variety_rect": {
"top": 57.11,
"right": 54.64,
"left": 30.57,
"bottom": 59.56
}
}
},
"result": [
{
"filepath": "example2.jpg",
"score": 29.7,
"match_percent": 33.03,
"query_overlap_percent": 23,
"target_overlap_percent": 100,
"metadata": {
"label_rect": {
"top": 27,
"right": 92.17,
"bottom": 81.67,
"left": 8.5
},
"vintage_year": 2015,
"vintage_rect": {
"top": 66.67,
"right": 69.83,
"bottom": 70.78,
"left": 57.5
},
"variety_type": "Pinot Gris",
"variety_rect": {
"top": 57.89,
"right": 79.17,
"left": 47,
"bottom": 63
}
}
},
{
"filepath": "example1.jpg",
"score": 27.1,
"match_percent": 30.4,
"query_overlap_percent": 17.4,
"target_overlap_percent": 100,
"metadata": {
"label_rect": {
"top": 1.97,
"right": 99.33,
"bottom": 99.18,
"left": 1.17
},
"vintage_year": 2015,
"vintage_rect": {
"top": 73.11,
"right": 55.67,
"bottom": 79.67,
"left": 39.83
},
"variety_type": "Pinot Gris",
"variety_rect": {
"top": 56.56,
"right": 69.17,
"left": 27.17,
"bottom": 66.56
}
}
}
]
}
The scores give an idea of the relative quality of the matches, but note that a low score doesn’t necessarily mean a poor match. Scores are best used for ordering results, rather than eliminating them. The overlap_percent values give an idea of how much cropping was involved.
The complete description of the search request is available at POST search.
Here is what the example images used above look like. Note that they have been pre-scaled to the recommended size, 1000 pixels in the smallest dimension:
joca_hand.jpg
example1.jpg
example2.jpg
Now that you’ve tried searching, learn how to view your collection images and generate overlays in the next tutorial: Working with images.