Differences

This shows you the differences between two versions of the page.

Link to this comparison view

engine:7.8:discover-api [2017/08/21 14:42]
pdufour [5. Query API: Search Images]
engine:7.8:discover-api [2018/02/01 18:15]
Line 1: Line 1:
-====== Discover LTU Engine OnDemand API ====== 
-<​const>​ 
-full_version=7.8 
-</​const>​ 
- 
-In the [[engine/​7.8/​discover-admininterface|Administrative Interface presentation]],​ you had discovered how to add and search images by using the LTU Engine web interface.\\ 
-\\ 
-In this section, you will be explained how getting start with the main API's requests. All methods are detailled in the [[/​engine/​%%full_version%%/​api|full JSON API documentation]]. 
-\\ 
-<WRAP center round important>​ 
-Before starting, be sure that you PC has been authorized to connect to the LTU Engine API's. You PC should have been added in your IP whitelist. For more information regarding the IP authorization,​ you can consult the [[engine/​%%full_version%%/​discover-admininterface#​your_pc_ip|Administrative Interface presentation]]. 
-</​WRAP>​ 
- 
- 
-===== - Overview ===== 
- 
-The LTU Engine API's is highly adaptable and compatible with most data structures. Integration is possible with any API enabled software via HTTP and JSON. 
- 
-The LTU Engine API's are mainly used for 
-  ***Image Management** to add and delete images through the **MODIFY** API 
-  ***Image Search** to retrieve images through the **QUERY** API 
- 
-The **application_key** is a parameter mandatory for **ALL** LTU Engine requests. It is a unique identifier for your application. To know how to get your //​application key//, please consult the [[engine/​%%full_version%%/​discover-admininterface#​applications_dashboard|Administrative Interface presentation]] 
- 
-===== - QuickStart ===== 
- 
-A good way to test quickly the add, search and delete requests, is to open a terminal and to enter the following command: 
-  * __to add an image to your application__ call the //​AddImage//​ method from the image folder. 
-The id must be associated to the image to easily identify it. Use the parameter image_id to associate a unique ID to your image. 
-<file bash> 
-cd /​image_folder 
-curl -F image_content=@image.jpeg \ 
-'​https://​api.ltu-engine.com/​v2/​ltumodify/​json/​AddImage?​application_key=xZVJpDWewJB5cxkqVpLGbWzNr5RP6je8&​image_id=myimage'​ 
-</​file>​ 
-Once the image added in your application,​ you should receive the following answer. 
-<file bash> 
-{"​status":​ {"​message":​ "Image added to the reference database.",​ "​code":​ 0}} 
-</​file>​ 
-Also, the newly added image is visible on the LTU Engine front office and available for the search. 
-{{ :​engine:​%%full_version%%:​images_added.jpeg?​nolink |}} 
-  * __to seach references__ call the //​SearchByUpload//​ method from the image folder. 
-<file bash> 
-cd /​image_folder 
-curl -sL -F "​image_content=@image.jpeg"​ \ 
-'​https://​api.ltu-engine.com/​v2/​ltuquery/​json/​SearchImageByUpload?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI'​ 
-</​file>​ 
-The API returns an answer to indicate if some references have been found. 
-<file bash> 
-{ 
- "​images":​[ 
-    { 
-     "​keywords":​[],​ 
-     "​score":​0,​ 
-     "​id":"​myimage",​ 
-     "​result_info":"​ 
-     { 
-         "​category":​ "​LOCALMATCHING", ​ 
-         "​distance":​ 0.0,  
-         "​homography":​ {"​source":​ "​reference",​ "​destination": ​ 
-         "​query",​ "​coefficients":​ [1.0, 0.0, -0.0, 0.0, 1.0, -0.0, 0.0, 0.0, 1.0]}, ​ 
-         "​reference":​ {"​originalDimensions":​ [960, 640], "​resizedDimensions":​ [512, 341],  
-         "​matchingBox":​ {"​points":​ [[0.0742, 0.088], [0.9258, 0.088], [0.9258, 0.8856], [0.0742, 0.8856]], ​ 
-         "​area":​ 0.6793}}, ​ 
-         "​decision":​ "​Clone", ​ 
-         "​scores":​ { 
-                     "​matchStrengthWithoutWeighting":​ 0.9316, ​ 
-                     "​boxPointsRatioHomography":​ 1.0,  
-                     "​matchStrength":​ 1.0,  
-                     "​boxCoveredSurface":​ 1.0,  
-                     "​boxPointsRatio":​ 0.9708}, ​ 
-         "​query":​ {"​originalDimensions":​ [960, 640],  
-         "​resizedDimensions":​ [512, 341],  
-         "​matchingBox":​ {"​points":​ [[0.0742, 0.088], [0.9258, 0.088], [0.9258, 0.8856], [0.0742, 0.8856]], ​ 
-         "​area":​ 0.6793}}}"​ 
-    }], 
- "​status":​ 
-  { 
-   "​message":"​No error",​ 
-   "​code":​0 
-  }, 
- "​nb_results_found":​1 
-} 
-</​file>​ 
-  * __to delete an image__ from its //image id// call the //​DeleteImage//​ method. 
-<file bash> 
-curl -sL \ 
-'​https://​api.ltu-engine.com/​v2/​ltumodify/​json/​DeleteImage?​application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&​image_id=myimage'​ 
-</​file>​ 
-Once the image deleted you should be informed. 
-<file bash> 
-{"​status":​ {"​message":​ "Image deleted from the reference database.",​ "​code":​ 0}} 
-</​file>​ 
- 
-===== - API's - Two distinct categories: ​ MODIFY & QUERY ===== 
-All LTU Engine queries fall into one of two general API categories: ​ MODIFY or QUERY. 
-\\  
-\\ 
-The LTU Engine API's are accessible over the HTTP protocol as follows : 
-  ***MODIFY** ​ - https://​api.ltu-engine.com/​v2/​ltumodify/​json/​ 
-  ***QUERY** - https://​api.ltu-engine.com/​v2/​ltuquery/​json/​ 
-\\    
-LTU Engine requires a ''​GET''​ or a ''​POST''​ request as input, and returns an HTTP response with the application/​json mimetype, which contains the response serialized as a JSON string. 
- 
-===== - Modify API:  Add & Delete Images ===== 
-The Modify API is usually exposed on http://​api.ltu-engine.com/​v2/​ltumodify/​json 
-==== - AddImage ==== 
-This request is called to add an image in your reference database. ​ 
-  * **Request:​** 
-<file bash> 
-POST https://​api.ltu-engine.com/​v2/​ltumodify/​json/​AddImage 
-</​file>​ 
-  * **Required Parameters** : 
-    * application_key (string): the unique key of the application to query. 
-    * image_id (string): The unique identifier of the image. 
-    * image_content (string): the content of the image file i.e. the raw array of bytes in the image. 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-To get more information about the //​AddImage//​ method, you could consult its [[/​engine/​%%full_version%%/​api#​addimage| full description]]. 
- 
-==== - DeleteImage ==== 
-This request is called to remove an image from you reference database. 
- 
-  * **Request type :​**''​GET''​ 
-<file bash> 
-GET https://​api.ltu-engine.com/​v2/​ltumodify/​json/​DeleteImage 
-</​file>​ 
-  * **Required Parameters** : 
-    * application_key (string): the unique key of the application to query 
-    * image_id (string): The unique identifier of the image. 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-To get more information about the //​DeleteImage//​ method, you could consult its [[/​engine/​%%full_version%%/​api#​deleteimage| full description]]. 
-===== - Query API:  Search Images ===== 
- 
-The modify API is usually exposed on http://​api.ltu-engine.com/​v2/​ltuquery/​json 
- 
-References images can be search by: 
-  * uploading an image 
-  * providing the DNA 
-  * providing the id 
-  * using keywords 
- 
-In this this documentation,​ we will only present the main search //​SearchImageByUpload//​ method, consult the [[/​engine/​7.8/​api#​principal_api_ssearch_images | full documentation]] for other methods. 
- 
-This request is used to run an image search on an application,​ using an uploaded image as the query. 
-\\ 
-  * **Request type :** : ''​POST''​ 
-<file bash> 
-POST https://​api.ltu-engine.com/​v2/​ltuquery/​json/​SearchImageByUpload 
-</​file>​ 
-  * **Required Parameters :** 
-    * application_key (string): the unique key of the application to query 
-    * image_content (string): the content of the image file i.e. the raw array of bytes in the image. 
-  * **Response**:​ 
-    * status (object): 
-      * message (string): comprehensive message regarding the status of your query 
-      * code (integer): a specific status code, 0 means success 
-    * nb_results_found (integer): the **total** number of reference images that matched the query 
-    * images (list of object): 
-      * keywords (list of string): the keywords linked to the image 
-      * score (float): the confidence matching score - smaller is better 
-      * id (string): image_id with which the image has been added to your reference database 
-      * result_info (string): give more information about the result 
- 
-\\ 
-<WRAP center round info 100%> 
-Now you know more about the LTU Engine API, if you need to go deeper or to start your application,​ a python client is available: [[https://​github.com/​ltutech/​ltuengine-python-client|{{:​cloud:​opengraph-icon-200x200.png?​nolink&​50|Python Client for LTU engine }}]]  
-\\ 
-A complete API  documentation is also available. 
-</​WRAP>​