This version (2018/02/01 17:09) is a draft.
Approvals: 0/1

Discover LTU Cloud API

In the LTU Cloud Quick Start guide, you had discovered how to add and search images by using the LTU Cloud 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.

The LTU Cloud 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 Cloud API's are mainly used for:

  • Visual Management to add your own content in the reference database by creating Visual with their related Images and Metadata.
  • Image Search to send new search image Queries to match Visual.
  • Project Management to organize visuals in projects, share content or optimize and speed up your searches.


Authentication is mandatory for ALL LTU Cloud requests. That means you should have created an account on our LTU Cloud platform. If needed, you can create a temporary test account from our website.

A good way to test quickly the add and search requests, is to open a terminal and to enter the following curl command:

  • to add a visual to your project call the projects/PROJECT_ID/visuals endpoint.

A title must be associated to the visual to easily identify it. Use the parameter title to associate a unique ID to your image. A name could be added too, but it is not mandatory.

   curl -i -X POST -u firstname.name@mycompany.com:PASSWORD https://cloud.ltutech.com/api/v1/projects/PROJECT_ID/visuals/ -F title='Chihiro' -F name='Chihiro Movie Poster'

Once the visual added in your project, you should receive a JSON confirmation answer.

HTTP/1.1 100 Continue
 
HTTP/1.1 201 CREATED
Server: nginx/1.8.0
Date: Fri, 30 Jun 2017 10:15:10 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Authenticate, Accept
Allow: GET, POST, HEAD, OPTIONS
 
{
  "match_count": 0, 
  "cover_id": null, 
  "name": "chihiro movie poster", 
  "title": "Chihiro", 
  "created_at": "2017-06-30T10:56:32.821Z", 
  "updated_at": "2017-06-30T10:56:32.821Z", 
  "_media": {}, 
  "_links": 
  {
    "images": "https://cloud.ltutech.com/api/v1/projects/visuals/6988525/images/", 
    "project": "https://cloud.ltutech.com/api/v1/projects/767/", 
    "self": "https://cloud.ltutech.com/api/v1/projects/visuals/6988525/", 
    "alternate": "https://cloud.ltutech.com/api/v1/projects/767/visuals/chihiro%20movie%20poster/", 
    "metadata": "https://cloud.ltutech.com/api/v1/projects/visuals/6988525/metadata/"
  }, 
  "user": "firstname.name@mycompany.com", 
  "images": [], 
  "project_id": 767, 
  "id": 6988525, 
  "metadata": []
 }

Also, the newly added visual is visible on the LTU Cloud portal. No image are attached to it yet.

  • to add an image to a visual use the projects/PROJECT_ID/visuals/VISUAL_ID/images endpoint.

You have to specify the id of the visual on which attach the image. You can know the id in the JSON answer during the visual creation.

  curl -i -X POST -u firstname.name@mycompany.com:PASSWORD https://cloud.ltutech.com/api/v1/projects/visuals/VISUAL_ID/images/ -F image=@/IMG_PATH/chihiro.jpg

Once the image added to the visual, you should receive an JSON confirmation answer.

HTTP/1.1 100 Continue
 
HTTP/1.1 201 CREATED
Server: nginx/1.8.0
Date: Fri, 30 Jun 2017 11:00:51 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Authenticate, Accept
Allow: GET, POST, HEAD, OPTIONS
 
{
  "image_md5": "8fa192a13890f4d91187bd9177108520", 
  "name": "Le_Voyage_de_Chihiro.jpeg", 
  "created_at": "2017-06-30T11:00:50.817Z", 
  "visual_id": 6988525, 
  "_media": 
  {
    "image": "https://cloud.ltutech.com/media/images/visual/1a/ef/6988525/6988525_8fa192a13890f4d9.jpeg", 
    "thumbnail": "https://cloud.ltutech.com/media/thumbnail-200x200/images/visual/1a/ef/6988525/6988525_8fa192a13890f4d917.jpeg"
  }, 
  "source": "user-generated", 
  "_links": 
  {
    "self": "https://cloud.ltutech.com/api/v1/projects/visuals/images/7354815/", 
    "visual": "https://cloud.ltutech.com/api/v1/projects/visuals/6988525/"
  }, 
  "user": "firstname.name@mycompany.com", 
  "id": 7354815
 }

Also, the newly added image is visible on the LTU Cloud portal and available for the search.

  • to seach references call the queries endpoint.
  curl -i -X POST -u firstname.name@mycompany.com:PASSWORD https://cloud.ltutech.com/api/v1/queries/ -F image=@/tmp/image.jpg

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

HTTP/1.1 100 Continue
 
HTTP/1.1 201 CREATED
Server: nginx/1.8.0
Date: Fri, 30 Jun 2017 11:48:03 GMT
Content-Type: application/json
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Authenticate, Accept
Allow: GET, POST, HEAD, OPTIONS
 
{
 "status": 
 {
   "code": 2,
   "is_error": false,
   "name": "DONE_ONE_MATCH"
 },
 "source_description": "",
 "matches": 
 [{
    "score": 0.82,
    "nb_matched_images": 1,
    "_links": { "self": "https://cloud.ltutech.com/api/v1/queries/matches/17520967/"},
    "id": 17520967,
    "matched_visual": 
    {
	"match_count": 3,
	"name": "chihiro movie poster",
	"matched_images": 
        [{
		"name": "Le_Voyage_de_Chihiro.jpeg",
		"_media":
                {
		    "image": "https://cloud.ltutech.com/media/images/visual/1a/ef/6988525/6988525_8fa192a13890f4d9.jpeg",
		    "thumbnail": "https://cloud.ltutech.com/media/thumbnail-200x200/images/visual/1a/ef/6988525/6988525_8fa192a13890f4d9.jpeg"
		},
		"image_id": 7354838,
		"score": 0.82,
		"_links": { "image": "https://cloud.ltutech.com/api/v1/projects/visuals/images/7354838/"},
		"result_info": 
                {
			"category": "LOCALMATCHING",
			"distance": 0.8203,
			"homography": 
                        {
				"source": "reference",
				"destination": "query",
				"coefficients": [1.216, 0.0121, -0.0836, 0.1952, 1.1133, 0.0837, 0.4762, 0.0626, 1.0]
			},
			"reference": 
                        {
				"originalDimensions": [876, 1194],
				"resizedDimensions": [375, 512],
				"matchingBox": 
                                {
					"points": [
							[0.28, 0.2969],
							[0.4933, 0.2969],
							[0.4933, 0.7207],
							[0.28, 0.7207]
						   ],
					"area": 0.0904
				}
			},
			"decision": "Match",
			"scores": 
                        {
				"boxPointsRatio": 1.0,
				"boxPointsRatioHomography": 0.9583,
				"boxCoveredSurface": 0.4583,
				"matchStrengthWithoutWeighting": 0.0449,
				"matchStrength": 0.1797
			},
			"query": 
                        {
				"originalDimensions": [226, 320],
				"resizedDimensions": [361, 512],
				"matchingBox": 
                                {
					"points":
                                        [
						[0.2261, 0.407],
						[0.4148, 0.4072],
						[0.4102, 0.7674],
						[0.2254, 0.7982]
					],
				        "area": 0.0701
			        }
		        }
	        }
        }],
 "created_at": "2017-06-30T10:56:32.821Z",
 "title": "Chihiro",
 "updated_at": "2017-06-30T11:43:33.243Z",
 "_links": 
 {
	"images": "https://cloud.ltutech.com/api/v1/projects/visuals/6988525/images/",
	"project": "https://cloud.ltutech.com/api/v1/projects/767/",
	"self": "https://cloud.ltutech.com/api/v1/projects/visuals/6988525/",
	"alternate": "https://cloud.ltutech.com/api/v1/projects/767/visuals/chihiro%20movie%20poster/",
	"metadata": "https://cloud.ltutech.com/api/v1/projects/visuals/6988525/metadata/"
     },
     "user": "firstname.name@mycompany.com",
     "project_id": 767,
     "id": 6988525,
     "metadata": []
  }
 }],
 "created_at": "2017-06-30T12:35:24.876Z",
 "_media": 
 {
	"image": "https://cloud.ltutech.com/media/images/query/2017/06/30/12/97082fe6-5d90-11e7-bf20.jpeg",
	"thumbnail": "https://cloud.ltutech.com/media/thumbnail-200x200/images/query/2017/06/30/12/97082fe6-5d90-11e7-bf20.jpeg"
 },
 "source": "",
 "_links": 
 {
	"matches": "https://cloud.ltutech.com/api/v1/queries/49345932/matches/",
	"self": "https://cloud.ltutech.com/api/v1/queries/49345932/"
 },
 "user": "firstname.name@mycompany.com",
 "id": 49345932,
 "projects": 
 [{
	"id": 767,
	"title": "Evaluation project for firstname.name@mycompany.com"
 }]
}


Now you know more about the LTU Cloud API, if you need to go deeper or to start your application, a python client is available: Python Client for LTU Cloud