This version (2017/08/21 14:44) is a draft.
Approvals: 0/1

Discover LTU Engine OnDemand API

In the 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 full JSON API documentation.

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 Administrative Interface presentation.

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 Administrative Interface presentation

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.

cd /image_folder
curl -F image_content=@image.jpeg \
'https://api.ltu-engine.com/v2/ltumodify/json/AddImage?application_key=xZVJpDWewJB5cxkqVpLGbWzNr5RP6je8&image_id=myimage'

Once the image added in your application, you should receive the following answer.

{"status": {"message": "Image added to the reference database.", "code": 0}}

Also, the newly added image is visible on the LTU Engine front office and available for the search.

  • to seach references call the SearchByUpload method from the image folder.
cd /image_folder
curl -sL -F "image_content=@image.jpeg" \
'https://api.ltu-engine.com/v2/ltuquery/json/SearchImageByUpload?application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI'

The API returns an answer to indicate if some references have been found.

{
 "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
}
  • to delete an image from its image id call the DeleteImage method.
curl -sL \
'https://api.ltu-engine.com/v2/ltumodify/json/DeleteImage?application_key=PXly9fRUfUt0oizKTcmpzFS8AAtqrTgI&image_id=myimage'

Once the image deleted you should be informed.

{"status": {"message": "Image deleted from the reference database.", "code": 0}}

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 :


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.

The Modify API is usually exposed on http://api.ltu-engine.com/v2/ltumodify/json

4.1. AddImage

This request is called to add an image in your reference database.

  • Request:
POST https://api.ltu-engine.com/v2/ltumodify/json/AddImage
  • 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 full description.

4.2. DeleteImage

This request is called to remove an image from you reference database.

  • Request type :GET
GET https://api.ltu-engine.com/v2/ltumodify/json/DeleteImage
  • 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 full description.

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 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
POST https://api.ltu-engine.com/v2/ltuquery/json/SearchImageByUpload
  • 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


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: Python Client for LTU engine
A complete API documentation is also available.