LTU-Engine Server - Seeker API 4

LTU Technologies

Legal Notice

LTU-Engine Server™ is Copyright © 1999-2011 by LTU Technologies.

Revision History
Revision $Revision: 1.24 $$Date: 2011-11-03 16:14:23 $

Abstract

This document is a reference for the integration of LTU-Engine Server. It explains the access protocol, gives an overview of the common parameters used during the queries and finally details all the queries accepted by LTU-Engine Server. The queries are separated into entity administration and search queries.


1. Introduction
1. Goals
2. Applicable documents
3. Acronyms
2. Integrating LTU Technologies services
1. General considerations about integration
2. General considerations about formats
3. HTTP sessions
4. The Entity
4.1. Searching entities
4.2. Search performance enhancement
4.3. The Related Entities
5. Query specification explanation
6. Binary
6.1. Reserved entity attribute for storage on a file system
6.2. XML output
6.2.1. bin-format-ref format
6.2.2. bin-format-raw format
7. Common parameters in LTU engine server
8. Error response
3. LTU engine server Seeker Queries
1. Entity Management Queries
1.1. The add entity query
1.1.1. Query specification
1.1.2. Response specification
1.1.3. Possible errors
1.2. The add entity with binary query
1.2.1. Query specification
1.2.2. Response specification
1.2.3. Possible errors
1.3. The delete entity query
1.3.1. Query specification
1.3.2. Response specification
1.3.3. Possible errors
1.4. The delete entities query
1.4.1. Query specification
1.4.2. Response specification
1.4.3. Possible errors
1.5. The update entity query
1.5.1. Query specification
1.5.2. Response specification
1.5.3. Possible errors
2. Image Management Queries
2.1. The add image query
2.1.1. Query specification
2.1.2. Response specification
2.1.3. Possible errors
2.2. The add DNA query
2.2.1. Query specification
2.2.2. Response specification
2.2.3. Possible errors
2.3. The update keyword query
2.3.1. Query specification
2.3.2. Response specification
2.3.3. Possible errors
2.4. The add kimages tags query
2.4.1. Query specification
2.4.2. Response specification
2.4.3. Possible errors
2.5. The delete kimages tags query
2.5.1. Query specification
2.5.2. Response specification
2.5.3. Possible errors
2.6. The update kimages tags query
2.6.1. Query specification
2.6.2. Response specification
2.6.3. Possible errors
3. Search Queries
3.1. The get entity info query
3.1.1. Query specification
3.1.2. Response specification
3.1.3. Possible errors
3.1.4. Specific case of getting information from entity ltu_kimage
3.2. The get entities query
3.2.1. Query specification
3.2.2. Response specification
3.2.3. Possible errors
3.3. The shuffle entity query
3.3.1. Query specification
3.3.2. Response specification
3.3.3. Possible errors
3.4. The search entity query
3.4.1. Query specification
3.4.2. Response specification
3.4.3. Possible errors
3.5. The browse entity result query
3.5.1. Query specification
3.5.2. Response specification
3.6. The search image query
3.6.1. Query specification
3.6.2. Response specification
3.6.3. Possible errors
3.7. The search DNA query
3.7.1. Query specification
3.7.2. Response specification
3.7.3. Possible errors
3.8. The search keyword query
3.8.1. Query specification
3.8.2. Response specification
3.8.3. Possible errors
3.9. The bounce image query
3.9.1. Query specification
3.9.2. Response specification
3.9.3. Possible errors
4. Color Queries
4.1. The get palette query
4.1.1. Query specification
4.1.2. Response specification
4.1.3. Possible errors
4.2. The search color query
4.2.1. Query specification
4.2.2. Response specification
4.2.3. Possible errors
4.3. The get image color query
4.3.1. Query specification
4.3.2. Response specification
4.3.3. Possible errors
5. System Management Queries
5.1. The get repository info query
5.1.1. Query specification
5.1.2. Response specification
5.1.3. Possible errors
5.2. The load repository configuration query
5.2.1. Query specification
5.2.2. Response specification
5.2.3. Possible errors
5.3. The load repository query
5.3.1. Query specification
5.3.2. Response specification
5.3.3. Possible errors
5.4. The unload repository query
5.4.1. Query specification
5.4.2. Response specification
5.4.3. Possible errors
6. Other Queries
6.1. The compare images query
6.1.1. Query specification
6.1.2. Response specification
6.1.3. Possible errors
6.2. The get image query
6.2.1. Query specification
6.2.2. Response specification
6.2.3. Possible errors
6.3. The get binary query
6.3.1. Query specification
6.3.2. Response specification
6.3.3. Possible errors

Chapter 1. Introduction

This introduction summarizes the goals of this document, the applicable and reference documents used in this document.

1. Goals

This document is a reference for the integration of the LTU engine server API. It is useful whether you want to directly access the server via HTTP requests or to use the SDK already developed.

After a brief overview of the concepts in LTU engine server, all the queries are detailed.

2. Applicable documents

LTU-Engine Server Installation / Administration Guide [AG]

3. Acronyms

API: Application Programmable Interface

ASP: Application Service Provider

HTTP: Hyper Text Transfer Protocol

SDK: Software Development Kit

URL: universal resource locator

URI: universal resource identifier

Chapter 2. Integrating LTU Technologies services

1. General considerations about integration

This document is designed to provide sufficient information for the partners to design the integration of LTU APIs in their systems. This document also provides detailed APIs for all the HTTP requests to LTU servers, and thus makes it possible for the partners to implement the integration whether by using an LTU SDK or by developing their own.

The LTU server works as a web service provider facilitating the integration with other middle tier servers. Hardware considerations are detailed in the document [AG].

2. General considerations about formats

Input data is always transmitted to LTU servers using HTTP GET or POST methods. POST queries can be encoded in "multipart/form-data" in case a file (an image or a signature) is uploaded to the LTU server, and in "application/x-www-form-urlencoded" otherwise.

The output data is formatted in XML and encoded in UTF-8.

3. HTTP sessions

Some use cases in LTU engine server require being part of a session. When such a use case is started, LTU engine server will create a new session and communicate to and from the client using the session identifier. The same session can be kept longer than the use case requires it, which allows lower resource consumption on the server side.

The only use case where a session is mandatory is after a search, when the client wants to browse through the results.

To inform the client that a query has started a session the server returns a session identifier in its response. When the client wants to stay in the same session it has to pass the session identifier along with the query.

Lets see how the session identifier is passed to and from the server:

When a first query is sent to the server, a session is created. In the XML answer, the server specify the identifier of the session (value of the tag <session_id>).

Example:

This XML response of a searchimage query containing a session identifier:

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/searchimage">
<session_id>7ADCD25877BFA4C5030B8D3FD974ABB0</session_id>
<result_count>541</result_count>
<ltu_kimage><kimage_id>120</kimage_id>
</ltu_kimage>

To reuse this session, its identifier has to be passed to the server as a path parameter in the HTTP query like this (the path parameter has to be appended to the URI either for a GET or POST request):

http://server.ltutech.net/image-seeker/browseentityresult;
jsessionid=7ADCD25877BFA4C5030B8D3FD974ABB0?repository_id=0&starting_rank=5&nb_results=5

This query requests the following results from the previous searchimage query; this is why the same session has to be used.

It is not necessary to use the same session during the entire connection time. In this case do not rewrite the URI with the path parameter and make sure the client does not use cookies (which could be used by the server for session tracking also but is not the recommended way).

4. The Entity

The LTU engine Server backend is a system that handles digital assets. The assets are represented by what we call entities, which define the assets and their relationships, much like a relational database. An entity is defined by a name and its attributes. Its attributes can be numbers, characters, dates or link to other entities.

Only one entity is predefined in the system, which is the ltu_kimage entity, representing a searchable image. The others entities can reference the ltu_kimage entity. The default system installation comes with the following entities:

The entities are grouped in repositories. Repositories are independent and no search can be performed across multiple repositories.

4.1. Searching entities

In all the searches (whether ltu_kimage entities are involved or not) a search condition can be used. The search condition is similar to a where clause in an SQL query. It contains attribute's value checks combined with logical operations.

The search condition has the following structure:

entityName.attributeName test_operator value [logical_operator sub_expression]
test_operator can be: =, !=, <, >, <=, >=
logical_operator can be: and, or
value can be a literal value or an attribute name.

For example to perform a search of the records where the photographer phone number starts with 4 or 5 and belonging to the FACE category, the search condition would be:

search condition = (photographer.phone like '4%' or photographer.phone like '5%') 
and category='FACE' and record.photographer_name = photographer.name and record.category_name = category.name

To limit a visual search to the records where the photographer phone number starts with 4 or 5 and belonging to the FACE category, the search condition would be:

search condition = (photographer.phone like '4%' or photographer.phone like '5%') 
and category = 'FACE' and record.photographer_name = photographer.name and record.category_name = category.name 
and record.photo=ltu_kimage.ltu_kimage_id

Notice the use of the wildcard '%' which replaces any number of characters. To replace only one character use '_' instead.

4.2. Search performance enhancement

Since each textual information is represented as a relational SQL database table, to increase response time for searches, SQL indexes have to be used. On each field of the text info tables, an index have to be created, allowing the database to perform pre-computation on this fields. Note that, if a text info search is performed with the wildcards % or _ as first character, the indexes will not be used.

4.3. The Related Entities

It is strongly encouraged to use the Related Entities parameters to enhance the performances of any front-end application using this API. The aim of those parameters is to retrieve, in only one query, one or many objects with all their related data.

For example, in the data model example above, if you want to get all photographers and display for each one all his record, there are two ways:

  • Many queries

    • The front-end application makes a first getentities query to retrieve all photographers.

    • After parsing the result, the photographers' names allow to build a search query on 'record' where the search condition is 'record.photographer_name="ph_name"', and this for each photographer.

  • One query using related entities

    • The getenties query is done using the related entities parameters: the first parameters are still the same (get all photographers), but the related entity 'record' and the associated fake search condition 'record.photographer_name="originattributevalue" is passed to the query. The origin_attribute value specifies that the query must be filled with photographer.name. The backend will do all the work: get all the photographers, get all the found values for photographer.name, and run one query to get all the associated records. The returned XML returns then a list of photographer entities, themselves containing related_entities records.

The parameters groups must be formed by at least the related_entity_name, the related_entity_search_condition, and the related_entity_origin_attribute. To create a group, index those parameters by "_index". Optionally, you can specify the number of results as well as the expected attributes.

At last, note that the related entities API works with both normal entities and images: you can get related images inside a simple getenties query, as well as retrieve related entities from a search/bounce image query.

In practice

As we just explain it, the Related Entities can be used in the data model example above to get all photographers and for each photographer all his records with a single query.

We just have to send a "getentities" query with the following parameters:

Table 2.1. Parameters

NameValue
repository_id1
entity_namephotographer
starting_rank0
related_entity_name_1record
related_entity_search_condition_1record.photographer_name='originattributevalue'
related_entity_origin_attribute_1photographer.name

And we will receive this kind of response:

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/getentities">
 <result_count>2</result_count>
 <entity name="photographer">
  <attribute name="name">Greene</attribute>
  <attribute name="first_name">Milton</attribute>
  <attribute name="phone">789456123</attribute>
  <related_entities entity_name="record" search_condition="record.photographer_name='originattributevalue'" result_count="2">
    <related_entity name="record">
      <attribute name="image_name">image_1</attribute>
      <attribute name="file_name">20071106_0004.jpg</attribute>
      <attribute name="creation_date">2010/06/25</attribute>
      <attribute name="description"/>
      <attribute name="category_name"/>
      <attribute name="photographer_name">Greene</attribute>
      <attribute name="photo">image_1</attribute>
    </related_entity>
    <related_entity name="record">
      <attribute name="image_name">image_2</attribute>
      <attribute name="file_name">20071106_0005.jpg</attribute>
      <attribute name="creation_date">2010/06/25</attribute>
      <attribute name="description"/>
      <attribute name="category_name"/>
      <attribute name="photographer_name">Greene</attribute>
      <attribute name="photo">image_2</attribute>
    </related_entity>
  </related_entities>
 </entity>
 <entity name="photographer">
  <attribute name="name">Wall</attribute>
  <attribute name="first_name">Jeff</attribute>
  <attribute name="phone">123456789</attribute>
  <related_entities entity_name="record" search_condition="record.photographer_name='originattributevalue'" result_count="0">
  </related_entities>
 </entity>
</ltu_query>

In the same way, we can get all the ltu_kimages and for each ltu_kimage all its linked records by using a "getentities" query with the following parameters:

Table 2.2. Parameters

NameValue
repository_id1
entity_nameltu_kimage
starting_rank0
related_entity_name_1record
related_entity_search_condition_1record.photo='originattributevalue'
related_entity_origin_attribute_1ltu_kimage.ltu_kimage_id

5. Query specification explanation

The API is summarized in the "Query specification" section like this:

Table 2.3. HTTP Header

MethodGET or POST
URIThe relative path appended to the LTU server URL (composed of the service name and the query name)
Encoding typemultipart/form-data when uploading an image
HostThe LTU server address
PortThe LTU server port

Table 2.4. Path Parameter

jsessionid: defines whether the query requires a path parameter or not.

Table 2.5. Parameters

NameTypeExample Value
nametext 
[optional]text 
[from_0_to_many]*text 
from_1_to_many*text 
image_filefileBinary stream of image data

Table 2.6. [Parameters Group]*

NameTypeExample Value
Param_1  
Param_2  
[Param_3]*  

Legend of the name column:

  • [name]: this parameter is optional.

  • [name]*: this parameter can be present zero or more times

  • name*: this parameter can be present one or more times

    Parameters Group: Define whether the whole group of parameter delimited by the double border is optional/required/zero or more. Inside a group of parameters, the rules are redefined for each parameter independently of the main parameters of the query (see Related Entities API).

6. Binary

6.1. Reserved entity attribute for storage on a file system

To ease the storage of binary data on a file system, a special attribute of the entities is managed into LTU engine server. This attribute should:

  • be a text attribute

  • contain the pattern ltu_bin_ref.

For instance, to store a video file into an entity, the text attribute could be named video_ltu_bin_ref. When you want to fill this attribute, LTU engine server will automatically store the video content on the file system.

6.2. XML output

A binary attribute of an entity could be returned into XML in different formats. Currently, two formats are available:

  • bin-format-ref

  • bin-format-raw

6.2.1. bin-format-ref format

The bin-format-ref returns a URI that is relative to the server and could be used to ask this server the binary content.

6.2.2. bin-format-raw format

The binary content is written into the XML and encoded as base64.

The default binary format is always bin-format-ref.

7. Common parameters in LTU engine server

Each query is accompanied with some parameters interpreted by the server. Here is a list of the common parameters:

  • repository_id: is the identifier of the repository. A repository is a set of searchable images and any associated entities. It is not possible to search across multiple repositories. This parameter is mandatory for all the queries.

  • segment: informs the engine whether a segmentation pre-processing should be applied to the image before its DNA is computed. The possible values can be yes or no. If it is set to no then no segmentation will be applied. If the value is set to yes then the default DNA's segmentation will be applied (it then depends on the definition of the DNA). This parameter is optional; when not present the default value set in the repository is used.

  • color_weight: this parameter influences the importance of the color or the shape of the submitted image during the similarity search. The value can be from 0 included to 100 included, 0 being the lowest importance for the color. This parameter is optional; when not present the default value set in the repository is used.

  • expected_attribute: is the name of the entity attribute that will be retrieved. This parameter has to be the full attribute name that is "entity_name.attribute_name" except for the ltu_kimage entity. This parameter is optional; when not present all the attribute values are returned. If the entity name is "ltu_kimage" and "expected attribute" is not present only the attribute value "ltu_kimage_id" is returned.

For the "ltu_kimage" entity the attribute names are:

Table 2.7. ltu_kimage entity

ltu_kimage_idThe identifier of the ltu_kimage
ltu_kimage_renditionThe information concerning the renditions. The rendition information contains the rendition id, the md5
ltu_kimage_dnaThe information concerning the DNA
ltu_kimage_keywordThe keywords
ltu_kimage_tagsThe tags
ltu_kimage_scoreThe score of a visual search (the information is only present after a searchimage, searchkeyword or a bounceimage)
ltu_kimage_propertiesImage related information: format, dimensions, file size, ...
ltu_kimage_standard_exifExif data
ltu_kimage_iptcIptc data
ltu_kimage_maker_exifMaker notes
ltu_kimage_thumbnailThe thumbnail

  • starting_rank: determine the rank of the first result returned in the query. This parameter is useful when browsing through a result set. It has to be greater or equal to 0.

  • nb_results: determine the number of entities that are returned in the query (when several can be returned). It has to be greater or equal to 1. This parameter is optional; when not present the default value set in the repository is used.

  • attr_name_N and attr_value_N: designate the name of an entity's attribute and its value. As this pair of parameters can be present several times an index concatenated at the end of the parameters name allow to regroup a pair. The index starts at 1 with no brake in the sequence. attr_name_1 is associated with attr_value_1 and so on.

  • search_condition: is an SQL formatted string defining the search condition. The string is formatted like that: tableName.columnName operator value logical_operator tableName.columnName operator value... For example photographer.phone like '4%' and record.image_name = 'Img' and record.photographer_name=photographer.name. As you can see if the condition concerns several entities the corresponding joints have to be created.

  • use_keyword: when set to yes, the keywords of the bounced image (during a bounceimage query) are used. This parameter is optional; when not present the default value is yes.

8. Error response

In case of an error the following type of message is returned:

<?xml version="1.0" encoding="utf-8"?>
<ltu_error uri="/4_0/getrepositoryinfo/" type="client">
 <code>6002</code>
 <description>The repository id: 41 is unknown.</description>
</ltu_error>

Chapter 3. LTU engine server Seeker Queries

1. Entity Management Queries

1.1. The add entity query

This query creates a new entity. The new entity becomes searchable immediately after it has been added.

1.1.1. Query specification

Table 3.1. HTTP Header

MethodPOST
URI/iseeker/4_0/addentity

Table 3.2. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
entity_nametextCustom entity name
[entity_id]textAny
[attr_name_N]*textCustom entity attribute name
[attr_value_N]*textValue of the attribute N

1.1.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/addentity">
 <entity name="photographer">
  <attribute name="phone">123456789</attribute>
  <attribute name="name">Malkovich</attribute>
  <attribute name="first_name">John</attribute>
  <attribute name="address"></attribute>
 </entity>
</ltu_query>

1.1.3. Possible errors

Table 3.3. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5009The entity name is unknown.
5007The entity identifier is already used by another entity.
5011The attributes do not refer to any existing entity attributes.

1.2. The add entity with binary query

This query creates a new entity with binary data. The new entity becomes searchable immediately after it has been added.

1.2.1. Query specification

Table 3.4. HTTP Header

MethodPOST
URI/iseeker/4_0/addentitywithbinary
Encoding typemultipart/form-data

Table 3.5. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
entity_nametextCustom entity name
entity_idtextAny
[attr_name_N]*textCustom entity attribute name
[attr_value_N]*textValue of the attribute N
[attr_name]fileBinary stream of the file
[binary_format]textBin-format-raw or bin-format-ref

Note: attr_name is the name of the attribute of the entity that will contain the binary.

1.2.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/addentitywithbinary">
 <entity name="photographer">
  <attribute name="phone">123456789</attribute>
  <attribute name="name">Malkovich</attribute>
  <attribute name="first_name">John</attribute>
  <attribute name="address"></attribute>
  <attribute name="photo">DFGBERGVEKJEVRGKLRGERGKERGRGFDBDBFDFDE</attribute>
 </entity>
</ltu_query>

1.2.3. Possible errors

Table 3.6. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5009The entity name is unknown.
5007The entity identifier is already used by another entity.
5011The attributes do not refer to any existing entity attributes.

1.3. The delete entity query

This query removes an entity from the system. The entity can only be removed if it is not referenced by any other entity. The entity name designates any of the entities including the ltu_kimage entity.

1.3.1. Query specification

Table 3.7. HTTP Header

MethodGET
URI/iseeker/4_0/deleteentity

Table 3.8. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
entity_nametextCustom entity name or ltu_kimage
entity_idtextAny

1.3.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/deleteentity">
</ltu_query>

1.3.3. Possible errors

Table 3.9. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5009The entity name is unknown.
5006The entity identifier does not refer to any existing entity in the system.
5010The entity is referenced by another entity and cannot be removed.

1.4. The delete entities query

This query removes all entities corresponding to a SQL search. For example, for removing all entities of "Case No 1", the search condition would be record.case_id = 'Case No 1'.

1.4.1. Query specification

Table 3.10. HTTP header

MethodGET
URI/iseeker/4_0/deleteentities

Table 3.11. Parameters

NameTypePossible values
repository_idnumber0 to 99999
entity_nametextCustom entity name or ltu_kimage
search_conditiontextSQL where clause

1.4.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/deleteentities">
</ltu_query>

1.4.3. Possible errors

Table 3.12. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5009The entity name is unknown.
5006The entity identifier does not refer to any existing entity in the system.
5010The entity is referenced by another entity and cannot be removed.
5011The attributes in the search condition do not refer to any existing entity attributes.

1.5. The update entity query

This query modifies the attribute values of the specified entity (except the ltu_kimage entity and the binary attributes which cannot be updated with this query). When no attributes are passed in the query they are all set to null (all except the identifier), if a constraint is set so that an attribute cannot be null an error will occur.

1.5.1. Query specification

Table 3.13. HTTP Header

MethodPOST
URI/iseeker/4_0/updateentity

Table 3.14. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
entity_nametextCustom entity name or ltu_kimage
entity_idtextAny
[attr_name_N]*textCustom entity attribute name
[attr_value_N]*textValue of the attribute N

1.5.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/updateentity">
</ltu_query>

1.5.3. Possible errors

Table 3.15. Error codes

CodeReason
5002Cannot update the ltu_kimage entity.
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5009The entity name is unknown.
5006The entity identifier does not refer to any existing entity in the system.
5011The attributes do not refer to any existing entity attributes or an attribute has been set to null and this was not possible.

2. Image Management Queries

2.1. The add image query

This query creates a new ltu_kimage entity that is composed of the DNA of the uploaded image, some keywords and two renditions of the uploaded image. The first rendition of the uploaded image (identifier 0) is the uploaded image; the second rendition (identifier 1) is a thumbnail.

The unique identifier of the ltu_kimage entity can either be automatically generated or passed in the query. If you decide to handle the ltu_kimage identifier it is not possible to step back and let the server generate it automatically.

It is possible to add twice the same image as long as their identifier is unique (an image is identical to another one if they have the same MD5).

The new ltu_kimage becomes searchable immediately after it has been added.

The parameters "prefilter" and "segment" are used to specify whether the image must be prefilter and segment before being indexed.

The "expected_attributes" parameter permits to exactly set which attributes will be included in the XML response. Allowed values for this parameter are described in section 2.7. Additionally it is possible to add the value "ltu_kimage_thumbnail"; in this case, the rendition 1 has a "data" content with the thumbnail encoded in base64.

2.1.1. Query specification

Table 3.16. HTTP Header

MethodPOST
URI/iseeker/4_0/addimage
Encoding typemultipart/form-data

Table 3.17. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
[entity_id]number100 digits long alpha-numeric value
image_filenamefilebinary stream of the image
[segment]textyes / no
[prefilter]textyes / no
[keyword]*textAnything
[tag]*textAnything
[expected_attribute]*textExpected attributes in the XML response

2.1.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/addimage">
 <ltu_kimage>
  <kimage_id>201</kimage_id>
  <rendition>
   <id>0</id>
   <md5>#eaf0d512dafa898cd5a2aabe656fb6db</md5>
  </rendition>
  <rendition>
   <id>1</id>
   <md5>#28c82641e266ea8a2f64b895bb1a0036</md5>
   <data> (base64 encoded thumbnail) </data>
  </rendition>
  <dna>
   <name>medium color photo 06/05/2002</name>
   <segmentation_type>101</segmentation_type>
   <process_type>101</process_type>
   <resize>192</resize>
  </dna>
  <keyword>
   <value>trees</value>
   <value>yellow</value>
   <value>tree</value>
  </keyword>
  <tag>
   <value>tagId1</value>
   <value>tagId2</value>
   <value>tagId3</value>
  </tag>
  <metainfo>
   <attribute type="standard_exif" name="hex0056">NIKON</attribute>
   <attribute type="standard_exif" name="hex0001">PowerShot A80</attribute>
   <attribute type="iptc" name="hex0255">A Tree</attribute>
   <attribute type="iptc" name="hex0255">A Tree</attribute>
   <attribute type="maker_exif" name="ISO">200</attribute>
  </metainfo>
  <properties>
   <attribute name="format">JPEG</attribute>
   <attribute name="width">25</attribute>
   <attribute name="height">450</attribute>
   <attribute name="length">500000</attribute>
   <attribute type="properties" name="comment">This is the inside comment of an image</attribute>
  </properties>
</ltu_kimage>
</ltu_query>

2.1.3. Possible errors

Table 3.18. Error codes

CodeReason
5004A mandatory parameter is missing.
5003No file is present in the query.
6002The repository identifier is unknown.
5007The identifier is already used.
5011The attributes do not refer to any existing entity attributes.
5012The uploaded image is too big.
5013The uploaded image format is not supported.
5014The uploaded image is corrupted.
5018The uploaded image file is empty.
5019The query POST message is too big.
7013DNA computing error

2.2. The add DNA query

This query creates a new "ltu_kimage" entity which is composed of the DNA and information about the original image (its md5) stored under the rendition 0.

The unique identifier of the "ltu_kimage" entity can either be automatically generated or passed in the query. If you decide to handle the "ltu_kimage" identifier it is not possible to step back and let Image-Filter generate it automatically.

It is possible to add twice the same image.

The new "ltu_kimage" becomes searchable immediately after it has been added.

The DNA information ("dna_type", "dna_segmentation", "dna_preprocess" and "dna_resize") associated to the DNA data is stored in Image-Filter along with the signature information. To determine witch values you should use, see the documentation on DNA.

2.2.1. Query specification

Table 3.19. HTTP Header

MethodPOST
URI/iseeker/4_0/adddna
Encoding typemultipart/form-data

Table 3.20. Parameters

NameTypePossible Values
repository_idnumberNumber 0 to 99999
[entity_id]number100 digits long alpha-numeric value
DNAfileBinary stream of the DNA
dna_typenumberDNA type
dna_segmentationnumberDNA segmentation type
dna_preprocessnumberDNA preprocess type
dna_resizenumberDNA resize size
md5text32 digits md5

2.2.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/adddna">
 <ltu_kimage>
  <kimage_id>201</kimage_id>
  <rendition>
   <id>0</id>
   <md5>#eaf0d512dafa898cd5a2aabe656fb6db</md5>
  </rendition>
  <dna>
   <name>Matching 06/05/2003</name>
   <segmentation_type>100</segmentation_type>
   <process_type>101</process_type>
   <resize>64</resize>
  </dna>
 </ltu_kimage>
</ltu_query>

2.2.3. Possible errors

Table 3.21. Error codes

CodeReason
5004A mandatory parameter is missing.
5003No file is present in the query.
5007The identifier is already used.
5018The uploaded file size is null.
5019The query POST message is too big.
6002The repository identifier is unknown.

2.3. The update keyword query

This query modifies the keywords associated with an ltu_kimage entity. The keywords passed with this query replace the current keywords. When no keyword is provided, all keywords are removed.

2.3.1. Query specification

Table 3.22. HTTP Header

MethodGET
URI/iseeker/4_0/updatekeyword

Table 3.23. Parameters

NameTypePossible values
repository_idnumber0 to 99999
image_idnumberGreater or equals to 0
[keyword]*textAny

2.3.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/updatekeyword">
</ltu_query>

2.3.3. Possible errors

Table 3.24. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5006The ltu_kimage identifier does not refer to any existing entity in the system.

2.4. The add kimages tags query

This query adds a list of tags to the tags linked to ltu_kimage entities corresponding to a SQL search or to a list of kimage ids. At least one of the kimages_ids or search_condition parameters has to be provided.

The tags passed with this query are added to the current tags list. If a tag is already linked to a ltu_kimage, nothing is done.

The provided tags must be ids of existing tags (the corresponding ltu_tag entities have to be created before).

2.4.1. Query specification

Table 3.25. HTTP Header

MethodGET
URI/iseeker/4_0/updatekimagestags

Table 3.26. Parameters

NameTypePossible values
repository_idnumber0 to 99999
[kimages_ids]*numberAny
search_condition*textSQL where clause
[tags]*textAny

2.4.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/addkimagestags">
</ltu_query>

2.4.3. Possible errors

Table 3.27. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5006The ltu_kimage identifier does not refer to any existing entity in the system.

2.5. The delete kimages tags query

This query removes a list of tags from the tags linked to ltu_kimage entities corresponding to a SQL search or to a list of kimage ids. At least one of the kimages_ids or search_condition parameters has to be provided.

The tags passed with this query are removed from the current tags list for each kimage. If a tag is not linked to a ltu_kimage, nothing is done.

2.5.1. Query specification

Table 3.28. HTTP Header

MethodGET
URI/iseeker/4_0/updatekimagestags

Table 3.29. Parameters

NameTypePossible values
repository_idnumber0 to 99999
[kimages_ids]*numberAny
search_condition*textSQL where clause
[tags]*textAny

2.5.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/deletekimagestags">
</ltu_query>

2.5.3. Possible errors

Table 3.30. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5006The ltu_kimage identifier does not refer to any existing entity in the system.

2.6. The update kimages tags query

This query modifies the tags linked to ltu_kimage entities corresponding to a SQL search or to a list of kimage ids. At least one of the kimages_ids or search_condition parameters has to be provided.

The tags passed with this query replace the current tags. When no tag is provided, all tags are removed.

The provided tags must be ids of existing tags (the corresponding ltu_tag entities have to be created before).

2.6.1. Query specification

Table 3.31. HTTP Header

MethodGET
URI/iseeker/4_0/updatekimagestags

Table 3.32. Parameters

NameTypePossible values
repository_idnumber0 to 99999
[kimages_ids]*numberAny
search_condition*textSQL where clause
[tags]*textAny

2.6.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/updatekimagestags">
</ltu_query>

2.6.3. Possible errors

Table 3.33. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5006The ltu_kimage identifier does not refer to any existing entity in the system.

3. Search Queries

3.1. The get entity info query

This query is used to retrieve the entity attribute values. The entity name designates any of the entities including the ltu_kimage. It is possible to specify the expected attributes that will be retrieved.

3.1.1. Query specification

Table 3.34. HTTP Header

MethodGET
URI/iseeker/4_0/getentityinfo

Table 3.35. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
entity_nametextCustom entity name or ltu_kimage
entity_idtextAny
[binary_format]textBin-format-raw or bin-format-ref
[expected_attribute]*textCustom entity attribute name or ltu_kimage specific attribute name

Table 3.36. [Related Entity Parameters]*

related_entity_name_KtextThe name of the related entity on which to search
related_entity_search_condition_KtextA search condition linking the main entity of the query and the related entity. It must contain a originattributevalue string that will be replaced by the values of the origin_attribute of the main entities found.
related_entity_origin_attribute_Ktext"Entity_name.attribute_name" : attribute of original entity which value will be inserted in the sub-query in place of originattributevalue.
[related_entity_nb_results_K]numberNumber of results expected for the sub-query.
[related_entity_expected_attribute_K]*textThe name of the attribute(s) of the related entity that we want to get.

3.1.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/getentityinfo">
 <entity name="photographer">
  <attribute name="phone">123456789</attribute>
  <attribute name="name">Malkovich</attribute>
  <attribute name="first_name">John</attribute>
  <attribute name="address"></attribute>
  <related_entities entity_name="record" search_condition="..." result_count="2">
    <related_entity name="record">
      <attribute name="id">12</attribute>
    </related_entity>
    <related_entity name="record">
      <attribute name="id">354</attribute>
    </related_entity>
  </related_entities>
 </entity>
</ltu_query>

3.1.3. Possible errors

Table 3.37. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5009The entity name is unknown.
5006The entity identifier does not refer to any existing entity in the system.
5011The expected attributes do not refer to any existing entity attributes.
5031Related entity name unknown.
5032Related entity DB error.
5033Mandatory parameter for related entity is missing.

3.1.4. Specific case of getting information from entity ltu_kimage

ltu_kimage is a system entity - that means it can not be modified to match the specific needs of a client, nor does it change from one data model to another.

To understand how to get some textual information about the images (md5, rendition, etc.), the user needs to understand how the tables are built and linked together.

In the database, the ltu_kimage table contains links to two tables called ltu_image, one containing the original image, one containing the thumbnail. The table ltu_image is also a system table.

The ltu_image table contains all fields storing textual data about the image, including MD5, if it is encrypted or not, and the image binary itself. In summary, the ltu_kimage table always contains 3 fields:

  • the primary key, the ltu_kimage_id

  • a link to the ltu_image containing info about the original image, that is the field ltu_kimage_id0 (corresponding to rendition 0)

  • a link to the ltu_image containing info about the corresponding thumbnail, that is the field ltu_kimage_id1 (corresponding to rendition 1)

The ltu_image table contains the fields MD5, and image_binary for example.

The DNA is generally stored on disk, in a directory indicated in the repXXX_ltu_rep_conf.

From the back-end point of view though, the ltu_kimage table and the two associated ltu_image tables look like one table only.

As a consequence, to get parameters from the ltu_image, the API can be used as if there was only one ltu_kimage table, containing all parameters from the original image and its thumbnail. This imaginary table would have the following parameters:

Table 3.38. ltu_kimage entity

ltu_kimage_idThe identifier of the ltu_kimage
ltu_kimage_renditionThe information concerning the renditions. The rendition information contains the rendition id, the md5
ltu_kimage_dnaThe information concerning the DNA
ltu_kimage_keywordThe keywords
ltu_kimage_tagsThe tags
ltu_kimage_scoreThe score of a visual search (the information is only present after a searchimage, searchkeyword or a bounceimage)
ltu_kimage_propertiesImage related information: format, dimensions, file size, ...
ltu_kimage_metainfo_exifEXIF data
ltu_kimage_metainfo_iptcIPTC data
ltu_kimage_metainfo_makernoteMaker notes


For example, the user tries to get the md5 of the image and thumbnail attached to the kimage 101, the following request should be sent:

request "get entity info", parameters: : repository_id:XXX entity name: ltu_kimage entity_id: 101 (random). attr name: ltu_kimage_rendition

Note

Only "ltu_kimage_id" is returned if the parameter "expected attribute" is not present .

3.2. The get entities query

This query returns the entities of the specified repository. The entity name designates any of the entities including the ltu_kimage entity. It is possible to specify the expected attributes that will be retrieved. The entities are sorted by the value of their identifier.

3.2.1. Query specification

Table 3.39. HTTP Header

MethodGET
URI/iseeker/4_0/getentities

Table 3.40. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
entity_nametextCustom entity name or ltu_kimage
starting_ranknumberGreater or equals to 0
[nb_results]numberGreater or equals to 1
[binary_format]textBin-format-raw or bin-format-ref
[expected_attribute]*textCustom entity attribute name or ltu_kimage specific attribute name
[order_name_N]*textOne or more attribute, prefixed by the entity name, on which to order
[order_value_N]*textDirection of the ordering [asc|desc]. If none provided, asc if the default. Only one can be provided for all attributes. One can be provided for each attribute.

Table 3.41. [Related Entity Parameters]*

related_entity_name_KtextThe name of the related entity on which to search.
related_entity_search_condition_KtextA search condition linking the main entity of the query and the related entity. It must contain a originattributevalue string that will be replaced by the values of the origin_attribute of the main entities found.
related_entity_origin_attribute_Ktext"Entity_name.attribute_name" : attribute of original entity which value will be inserted in the sub-query in place of originattributevalue.
[related_entity_nb_results_K]numberNumber of results expected for the sub-query.
[related_entity_expected_attribute_K]*textThe name of the attribute(s) of the related entity that we want to get.

3.2.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/getentities">
 <result_count>2</result_count>
 <entity name="photographer">
  <attribute name="phone">789456123</attribute>
  <attribute name="name">Greene</attribute>
  <attribute name="first_name">Milton</attribute>
  <attribute name="address"></attribute>
  <related_entities entity_name="record" search_condition="..." result_count="2">
    <related_entity name="record">
      <attribute name="id">12</attribute>
    </related_entity>
    <related_entity name="record">
      <attribute name="id">354</attribute>
    </related_entity>
  </related_entities>
  <related_entities entity_name="ltu_kimage" 
                                          search_condition="..." result_count="1">
    <related_ltu_kimage>
  ... usual ltu_kimage XML elements ...
    </related_ltu_kimage>
  </related_entities>
 </entity>
 <entity name="photographer">
  <attribute name="phone">123456789</attribute>
  <attribute name="name">Wall</attribute>
  <attribute name="first_name">Jeff</attribute>
  <attribute name="address"></attribute>
  <related_entities entity_name="record" search_condition="..." result_count="0">
  </related_entities>
  <related_entities entity_name="ltu_kimage"
                                     search_condition="..." result_count="0">
  </related_entities>
 </entity>
</ltu_query>

Note

If the entity name is "ltu_kimage" and the parameter "expected attribute" is not present Only "ltu_kimage_id" is returned.

3.2.3. Possible errors

Table 3.42. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5009The entity name is unknown.
5002The starting rank or number of results is not set correctly.
5011The expected attributes do not refer to any existing entity attributes.
5030The values for order are not valid.
5031Related entity name unknown.
5032Related entity DB error.
5033Mandatory parameter for related entity is missing.

3.3. The shuffle entity query

This query returns a set of entities randomly selected in a specified repository. Including a search condition in the query can narrow the set of entities down.

3.3.1. Query specification

Table 3.43. HTTP Header

MethodPOST
URI/iseeker/4_0/shuffleentity

Table 3.44. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
entity_nametextcustom entity name or ltu_kimage
[search_condition]textSQL where clause
[binary_format]textBin-format-ref or bin-format-raw
[expected_attribute]*textcustom entity attribute name or ltu_kimage specific attribute name
[nb_results]numbergreater or equals to 1

Table 3.45. [Related Entity Parameters]*

related_entity_name_KtextThe name of the related entity on which to search.
related_entity_search_condition_KtextA search condition linking the main entity of the query and the related entity. It must contain a originattributevalue string that will be replaced by the values of the origin_attribute of the main entities found.
related_entity_origin_attribute_Ktext"Entity_name.attribute_name" : attribute of original entity which value will be inserted in the sub-query in place of originattributevalue.
[related_entity_nb_results_K]numberNumber of results expected for the sub-query.
[related_entity_expected_attribute_K]*textThe name of the attribute(s) of the related entity that we want to get.

3.3.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/shuffleentity">
 <result_count>2</result_count>
 <entity name="photographer">
  <attribute name="phone">789456123</attribute>
  <attribute name="name">Greene</attribute>
  <attribute name="first_name">Milton</attribute>
  <attribute name="address"> </attribute>
  <related_entities entity_name="record" search_condition="..." result_count="1">
    <related_entity name="record">
      <attribute name="id">12</attribute>
    </related_entity>
  </related_entities>
 </entity>
 <entity name="photographer">
  <attribute name="phone">123456789</attribute>
  <attribute name="name">Wall</attribute>
  <attribute name="first_name">Jeff</attribute>
  <attribute name="address"> </attribute>
  <related_entities entity_name="record" search_condition="..." result_count="0">
  </related_entities>
 </entity>
</ltu_query>

Note

If the entity name is "ltu_kimage" and the parameter "expected attribute" is not present Only "ltu_kimage_id" is returned.

3.3.3. Possible errors

Table 3.46. Error codes

CodeReason
5004a mandatory parameter is missing.
6002the repository identifier is unknown.
5002the number of results is not set correctly.
5011the expected attributes do not refer to any existing entity attributes.
5031Related entity name unknown.
5032Related entity DB error.
5033Mandatory parameter for related entity is missing.

3.4. The search entity query

This query returns the entities corresponding to the specified search condition. The search condition can concern several entities, in which case the joints must be part of the condition. The resulting entities are sorted by their identifier.

The results can be browsed with thebrowseentityresult query to obtain the results you did not receive with this call (or even re-obtain the same results without rerunning the query).

Example of a search query:

repository_id: 0

entity_name: ltu_kimage

search_condition: ltu_image.md5 like '#26f045%' and ltu_image.ltu_image_id=ltu_kimage.ltu_image_id0

This search will return all the ltu_kimage which have an md5 starting with #26f045.

3.4.1. Query specification

Table 3.47. HTTP Header

MethodPOST
URI/iseeker/4_0/searchentity

Table 3.48. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
entity_nametextCustom entity name or ltu_kimage
search_conditiontextSQL where clause
[nb_results]numberGreater or equals to 1
[binary_format]textBin-format-raw or bin-format-ref
[expected_attribute]*textCustom entity attribute name or ltu_kimage specific attribute name
[order_name_N]*textOne or more attribute, prefixed by the entity name, on which to order
[order_value_N]*textDirection of the ordering [asc|desc]. If none provided, asc if the default. Only one can be provided for all attributes. One can be provided for each attribute.

Table 3.49. [Related Entity Parameters]*

related_entity_name_KtextThe name of the related entity on which to search.
related_entity_search_condition_KtextA search condition linking the main entity of the query and the related entity. It must contain a originattributevalue string that will be replaced by the values of the origin_attribute of the main entities found.
related_entity_origin_attribute_Ktext"Entity_name.attribute_name" : attribute of original entity which value will be inserted in the sub-query in place of originattributevalue.
[related_entity_nb_results_K]numberNumber of results expected for the sub-query.
[related_entity_expected_attribute_K]*textThe name of the attribute(s) of the related entity that we want to get.

3.4.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/searchentity">
 <session_id>7ADCD25877BFA4C5030B8D3FD974ABB0</session_id>
 <result_count>24</result_count>
 <entity name="photographer">
  <attribute name="phone">789456123</attribute>
  <attribute name="name">Greene</attribute>
  <attribute name="first_name">Milton</attribute>
  <attribute name="address"></attribute>
  <related_entities entity_name="record" search_condition="..." result_count="2">
    <related_entity name="record">
      <attribute name="id">12</attribute>
    </related_entity>
    <related_entity name="record">
      <attribute name="id">354</attribute>
    </related_entity>
  </related_entities>
 </entity>
 <entity name="photographer">
  <attribute name="phone">123456789</attribute>
  <attribute name="name">Wall</attribute>
  <attribute name="first_name">Jeff</attribute>
  <attribute name="address"></attribute>
  <related_entities entity_name="record" search_condition="..." result_count="0">
  </related_entities>
 </entity>
</ltu_query>

Note

If the entity name is "ltu_kimage" and the parameter "expected attribute" is not present Only "ltu_kimage_id" is returned.

3.4.3. Possible errors

Table 3.50. Error codes

5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5009The entity name is unknown.
5002The number of results is not set correctly.
5011The attributes (expected or in the search condition) do not refer to any existing entity attributes.
5030The values for order are not valid.
5031Related entity name unknown.
5032Related entity DB error.
5033Mandatory parameter for related entity is missing.

3.5. The browse entity result query

This query allows navigating through the resulting set of entities after the searchentity, search image, search keyword, bounceimage queries, to obtain the rest of the results. The query returns the same attributes as the one requested during the first query of the session.

3.5.1. Query specification

Table 3.51. HTTP Header

MethodGET
URI/iseeker/4_0/browseentityresult

Table 3.52. Path Parameter

jsessionid

Table 3.53. Parameters

NameTypePossible Values
starting_ranknumbergreater or equals to 0.
[nb_results]numbergreater or equals to 1.

3.5.2. Response specification

The response has the same structure as the previous query.

3.6. The search image query

This query generates the DNA of the uploaded image and compares it and the provided keywords if any to the ltu_kimage entities of the specified repository. All the ltu_kimage entities are sorted by visual and keywords similarities. Including a search condition in the query can narrow the set of ltu_kimage entities down.

The results can be browsed with the browseentityresult query.

3.6.1. Query specification

Table 3.54. HTTP Header

MethodPOST
URI/iseeker/4_0/searchimage
Encoding typemultipart/form-data

Table 3.55. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
image_filenamefileBinary stream of the image
[segment]textyes / no
[prefilter]textyes / no
[color_weight]number0 to 100
[keyword]*textAny
[search_condition]textSQL where clause
[expected_attribute]*textltu_kimage specific attribute name
[nb_results]numberGreater or equals to 1

Table 3.56. [Related Entity Parameters]*

related_entity_name_KtextThe name of the related entity on which to search.
related_entity_search_condition_KtextA search condition linking the main entity of the query and the related entity. It must contain a originattributevalue string that will be replaced by the values of the origin_attribute of the main entities found.
related_entity_origin_attribute_Ktext"Entity_name.attribute_name" : attribute of original entity which value will be inserted in the sub-query in place of originattributevalue.
[related_entity_nb_results_K]numberNumber of results expected for the sub-query.
[related_entity_expected_attribute_K]*textThe name of the attribute(s) of the related entity that we want to get.

3.6.2. Response specification

Note

If the parameter "expected attribute" is not present Only "ltu_kimage_id" and "ltu_kimage_score" are returned.

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/searchimage">
 <session_id>7ADCD25877BFA4C5030B8D3FD974ABB0</session_id>
 <result_count>2</result_count>
 <ltu_kimage>
  <kimage_id>201</kimage_id>
  <score>0.45</score>
 </ltu_kimage>
 <ltu_kimage>
  <kimage_id>451</kimage_id>
  <score>0.46</score>
 </ltu_kimage>
</ltu_query>

3.6.3. Possible errors

Table 3.57. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5002The segment, color weight or number of results is not set correctly.
5011The attributes (expected or in the search condition) do not refer to any existing entity attributes.
5012The uploaded image is too big.
5013The uploaded image format is not supported.
5014The uploaded image is corrupted.
5018The uploaded file size is null.
5019The query POST message is too big.
6002The repository identifier is unknown.
5031Related entity name unknown.
5032Related entity DB error.
5033Mandatory parameter for related entity is missing.

3.7. The search DNA query

This query compares the uploaded DNA to the "ltu_kimage" entities of the specified repository. All the "ltu_kimage" entities are sorted by visual similarities. Including a search condition in the query can narrow the set of "ltu_kimage" entities down.

The results can be browsed with the browseentityresult query.

3.7.1. Query specification

Table 3.58. HTTP Header

MethodPOST
URI/iseeker/4_0/searchdna
Encoding typemultipart/form-data

Table 3.59. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
DNAfileBinary stream of the DNA
dna_typenumberDNA type
[search_condition]textSQL where clause
[expected_attribute]*textltu_kimage specific attribute name
[nb_results]numberGreater or equals to 1

Table 3.60. [Related Entity Parameters]*

related_entity_name_KtextThe name of the related entity on which to search.
related_entity_search_condition_KtextA search condition linking the main entity of the query and the related entity. It must contain a originattributevalue string that will be replaced by the values of the origin_attribute of the main entities found.
related_entity_origin_attribute_Ktext"Entity_name.attribute_name" : attribute of original entity which value will be inserted in the sub-query in place of originattributevalue.
[related_entity_nb_results_K]numberNumber of results expected for the sub-query.
[related_entity_expected_attribute_K]*textThe name of the attribute(s) of the related entity that we want to get.

3.7.2. Response specification

Note

If the parameter "expected attribute" is not present Only "ltu_kimage_id" and "ltu_kimage_score" are returned.

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/searchdna">
 <session_id>7ADCD25877BFA4C5030B8D3FD974ABB0</session_id>
 <result_count>2</result_count>
 <ltu_kimage>
  <kimage_id>201</kimage_id>
  <score>0.2</score>
 </ltu_kimage>
 <ltu_kimage>
  <kimage_id>451</kimage_id>
  <score>0.28</score>
 </ltu_kimage>
</ltu_query>

3.7.3. Possible errors

Table 3.61. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5002The segment, color weight or number of results is not set correctly.
5011The attributes (expected or in the search condition) do not refer to any existing entity attributes.
5018The uploaded file size is null.
5019The query POST message is too big.
5031Related entity name unknown.
5032Related entity DB error.
5033Mandatory parameter for related entity is missing.

3.8. The search keyword query

This query performs a search on the ltu_kimage entity's keywords. All the ltu_kimage entities are sorted by keywords similarities. Including a search condition in the query can narrow the set of ltu_kimage entities down.

The results can be browsed with the browseentityresult query.

The scores associated with the results can be interprated like this:

  1. 4.0 means 0 keyword matched

  2. 3.0 means ]0 , 25%] of keywords matched

  3. 2.0 means ]50% , 75%] of keywords matched

  4. 1.0 means ]50% , 75%] of keywords matched

  5. 0.0 means ]75% , 100%] of keywords matched

3.8.1. Query specification

Table 3.62. HTTP Header

MethodPOST
URI/iseeker/4_0/searchkeyword

Table 3.63. Parameters

NameTypePossible Values
repository_idtext0 to 99999
keyword*textany
[search_condition]textSQL where clause
[expected_attribute]*textltu_kimage specific attribute name
[nb_results]numbergreater or equals to 1

Table 3.64. [Related Entity Parameters]*

related_entity_name_KtextThe name of the related entity on which to search.
related_entity_search_condition_KtextA search condition linking the main entity of the query and the related entity. It must contain a originattributevalue string that will be replaced by the values of the origin_attribute of the main entities found.
related_entity_origin_attribute_Ktext"Entity_name.attribute_name" : attribute of original entity which value will be inserted in the sub-query in place of originattributevalue.
[related_entity_nb_results_K]numberNumber of results expected for the sub-query.
[related_entity_expected_attribute_K]*textThe name of the attribute(s) of the related entity that we want to get.

3.8.2. Response specification

Note

If the parameter "expected attribute" is not present Only "ltu_kimage_id" and "ltu_kimage_score" are returned.

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/searchkeyword">
 <session_id>7ADCD25877BFA4C5030B8D3FD974ABB0</session_id>
 <result_count>24</result_count>
 <ltu_kimage>
  <kimage_id>201</kimage_id>
  <score>0</score>
 </ltu_kimage>
 <ltu_kimage>
  <kimage_id>451</kimage_id>
  <score>0</score>
 </ltu_kimage>
</ltu_query>

3.8.3. Possible errors

Table 3.65. Error codes

CodeReason
5004a mandatory parameter is missing.
6002the repository identifier is unknown.
5002the number of results is not set correctly.
5011the attributes (expected or in the search condition) do not refer to any existing entity attributes.
5031Related entity name unknown.
5032Related entity DB .
5033Mandatory parameter for related entity is missing.

3.9. The bounce image query

This query retrieves ltu_kimage entities similar to the specified ltu_kimage entity. It is possible to perform a pure visual search by setting use_keyword to no. It is possible to override the keywords of the specified ltu_kimage entity by using the keyword parameter, in this case use_keyword has to be set to yes. Including a search condition in the query can narrow the set of ltu_kimage entities down.

The results can be browsed with the browseentityresult query.

3.9.1. Query specification

Table 3.66. HTTP Header

MethodPOST
URI/iseeker/4_0/bounceimage

Table 3.67. Parameters

NameTypePossible Values
repository_idtext0 to 99999
image_idtext0 to 9999999999
[color_weight]number0 to 100
[use_keyword]textyes / no
keyword]*textany
[search_condition]textSQL where clause
[expected_attribute]*textltu_kimage specific attribute name
[nb_results]numbergreater or equals to 1

Table 3.68. [Related Entity Parameters]*

related_entity_name_KtextThe name of the related entity on which to search.
related_entity_search_condition_KtextA search condition linking the main entity of the query and the related entity. It must contain a originattributevalue string that will be replaced by the values of the origin_attribute of the main entities found.
related_entity_origin_attribute_Ktext"Entity_name.attribute_name" : attribute of original entity which value will be inserted in the sub-query in place of originattributevalue.
[related_entity_nb_results_K]numberNumber of results expected for the sub-query.
[related_entity_expected_attribute_K]*textThe name of the attribute(s) of the related entity that we want to get.

3.9.2. Response specification

Note

If the parameter "expected attribute" is not present Only "ltu_kimage_id" and "ltu_kimage_score" are returned.

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/bounceimage">
 <session_id>7ADCD25877BFA4C5030B8D3FD974ABB0</session_id>
 <result_count>2</result_count>
 <ltu_kimage>
  <kimage_id>201</kimage_id>
  <score>0.2</score>
 </ltu_kimage>
 <ltu_kimage>
  <kimage_id>451</kimage_id>
  <score>0.27</score>
 </ltu_kimage>
</ltu_query>

Note

The keyword field is available in all repositories when you install the keyword suggestion plug-in. The repository has to be configured for it. Keywords are not to be confused with the "tag" field.

The "keyword" is a semantic word, and the image can belong to it or not (binary) - example: military image or not, external/inside image, etc. An image can not have at the same time "military" keyword, and the "not military" keyword associated.

The "tag" field installed by default on all database models from the repositories. But there is no "binary" effect about tags, an image can have many tags, without them being contradictory.

3.9.3. Possible errors

Table 3.69. Error codes

5004a mandatory parameter is missing.
6002the repository identifier is unknown.
5006the ltu_kimage entity id is unknown.
5002the color weight or number of results is not set correctly.
5011the attributes (expected or in the search condition) do not refer to any existing entity attributes.
5031Related entity name unknown.
5032Related entity DB error.
5033Mandatory parameter for related entity is missing.

4. Color Queries

These queries are only available if the repository signature is a color signature.

4.1. The get palette query

This query allows to get the list of colors detected in the specified repository or in a subset of it. Including colors, keywords or a search condition in the query can narrow down the set of images used to fill the returned colors list.

This enables the suggestion of colors associated with a given colors if the selection criteria used is a color.

4.1.1. Query specification

Table 3.70. HTTP Header

MethodGET
URI/iseeker/4_0/getpalette

Table 3.71. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
[color_hex_value]*textA list of hexadecimal RGB colors
[keyword]*textAny
[search_condition]textSQL where clause
[nb_results]numberNumber of colors needed. (the closest power of 2 will be used)

4.1.2. Response specification

<ltu_query service="iseeker" query="/4_0/getpalette">
 <palette>
  <color>
   <hex_value>#655F48</hex_value>
   <image_count>112</image_count>
  </color>
  <color>
   <hex_value>#5F48A8</hex_value>
   <image_count>67</image_count>
   </color>
  <color>
   <hex_value>#48A8AC</hex_value>
   <image_count>15</image_count>
  </color>
  <color>
   <hex_value>#A8ACAA</hex_value>
   <image_count>12</image_count>
  </color>
 </palette>
</ltu_query>

4.1.3. Possible errors

Table 3.72. Error codes

CodeReason
5004a mandatory parameter is missing.
6002the repository identifier is unknown.
5011A attribute in the search condition do not refer to any existing entity attributes.

4.2. The search color query

This query returns the ordered list of kimages of the specified repository which contain the provided colors. All the ltu_kimage entities are sorted by color similarities. Including keywords or a search condition in the query can narrow the set of ltu_kimage entities down.

The results can be browsed with the browseentityresult query.

4.2.1. Query specification

Table 3.73. HTTP Header

MethodPOST
URI/iseeker/4_0/searchcolor

Table 3.74. Colors Parameters*

colors_color_hex_value_KtextThe hexadecimal value of the RGB color to search (e.g., #0000FF for blue).
colors_color_weight_Ktext

The minimal percent of color expected. The sum of all the color_weight must be under 100%.

Only the colors with a weight higher than 10% are used to filter the kimages returned.

All the colors are taken into account to compute the color similarity score.


Table 3.75. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
[keyword]*textAny
[search_condition]textSQL where clause
[expected_attribute]*textltu_kimage specific attribute name
[nb_results]numberGreater or equals to 1

Table 3.76. [Related Entity Parameters]*

related_entity_name_KtextThe name of the related entity on which to search.
related_entity_search_condition_KtextA search condition linking the main entity of the query and the related entity. It must contain a originattributevalue string that will be replaced by the values of the origin_attribute of the main entities found.
related_entity_origin_attribute_Ktext"Entity_name.attribute_name" : attribute of original entity which value will be inserted in the sub-query in place of originattributevalue.
[related_entity_nb_results_K]numberNumber of results expected for the sub-query.
[related_entity_expected_attribute_K]*textThe name of the attribute(s) of the related entity that we want to get.

4.2.2. Response specification

Note

If the parameter "expected attribute" is not present Only "ltu_kimage_id" and "ltu_kimage_score" are returned.

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/searchcolor">
 <session_id>7ADCD25877BFA4C5030B8D3FD974ABB0</session_id>
 <result_count>2</result_count>
 <ltu_kimage>
  <kimage_id>127</kimage_id>
  <score>9.1104</score>
 </ltu_kimage>
 <ltu_kimage>
  <kimage_id>131</kimage_id>
  <score>14.2754</score>
 </ltu_kimage>
</ltu_query>

4.2.3. Possible errors

Table 3.77. Error codes

CodeReason
5004A mandatory parameter is missing.
6002The repository identifier is unknown.
5002A color weight or an input hexadecimal color is not set correctly. The sum of the provided color_weight is higher than 100%.
5011The attributes (expected or in the search condition) do not refer to any existing entity attributes.
5019The query POST message is too big.
6002The repository identifier is unknown.
5031Related entity name unknown.
5032Related entity DB error.
5033Mandatory parameter for related entity is missing.
7018Invalid repository configuration (the DNA is not a colors DNA)

4.3. The get image color query

This query returns the colors of a given image. The input image can be outside (using image_filename) or already in an LTU repository (using image_id) application.

4.3.1. Query specification

Table 3.78. HTTP Header

MethodPOST
URI/iseeker/4_0/getimagecolor
Encoding typemultipart/form-data

Table 3.79. Parameters

NameTypePossible Values
repository_idnumber0 to 99999, the repository id is required
[image_filename]fileBinary stream of the image
[image_id]textUnique Image identifier in engine server repository (application)

4.3.2. Response specification

Note

This query returns the list of colors detected in the input images. For each color the percent of presence in the input image is although provided in the "color_weight" tag.

<ltu_query service="iseeker" query="/4_0/getimagecolor">
 <palette>
  <color>
   <hex_value>#655F48</hex_value>
   <color_weight>49</color_weight>
  </color>
  <color>
   <hex_value>#5F48A8</hex_value>
   <color_weight>27</color_weight>
   </color>
  <color>
   <hex_value>#48A8AC</hex_value>
   <color_weight>13</color_weight>
  </color>
  <color>
   <hex_value>#A8ACAA</hex_value>
   <color_weight>11</color_weight>
  </color>
 </palette>
</ltu_query>

4.3.3. Possible errors

Table 3.80. Error codes

CodeReason
5004A mandatory parameter is missing.
5006image_id identifier is unknown.
5012The uploaded image is too big.
5013The uploaded image format is not supported.
5014The uploaded image is corrupted.
5018The uploaded file size is null.
5019The query POST message is too big.
5024Exactly one input image must be provided
6002The repository identifier is unknown.
6005The repository is not activated
7018The repository does not use a color signature

5. System Management Queries

5.1. The get repository info query

This query allows the partner to see detailed information about the specified repository.

5.1.1. Query specification

Table 3.81. HTTP Header

MethodGET
URI/iseeker/4_0/getrepositoryinfo

Table 3.82. Parameters

NameTypePossible Values
repository_idnumber0 to 99999

5.1.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/getrepositoryinfo">
 <repository>
  <repository_id>0</repository_id>
  <image_count>64887</image_count>
  <binary_home_dir>/var/ltu/rep0/binary/</binary_home_dir>
  <signature_home_dir>/var/ltu/rep0/signatures/</signature_home_dir>
  <signature_storage_location>com.ltu.imageapp.entity.StorageFile 
</signature_storage_location>
  <image_home_dir>/var/ltu/rep0/images/</image_home_dir>
  <image_storage_location>com.ltu.imageapp.entity.StorageFile 
</image_storage_location>
  <segment_image>true</segment_image>
  <stem_keywords>false</stem_keywords>
  <nb_results>20</nb_results>
  <nb_results_cached>100</nb_results_cached>
  <color_weight>50</color_weight>
  <dna_name>medium color photo 06/05/2002</dna_name>
  <quantize>true</quantize>
  <store_original_image>true</store_original_image>
  <store_thumbnail_image>true</store_thumbnail_image>
  <retrieval_threshold>1.5</retrieval_threshold>
 </repository>
</ltu_query>

5.1.3. Possible errors

Table 3.83. Error codes

CodeReason
5004a mandatory parameter is missing.
6002the repository identifier is unknown.

5.2. The load repository configuration query

This query allows loading a repository configuration in the system. This query is used to reload the configuration once a repository is already loaded in the system. The configuration is loaded from the table repXXX_ltu_rep_conf. This is particularly useful when updating threshold parameters.

5.2.1. Query specification

Table 3.84. HTTP Header

MethodGET
URI/iseeker/4_0/loadrepositoryconfiguration

Table 3.85. Parameters

NameTypePossible Values
repository_idnumber0 to 99999

5.2.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/loadrepositoryconfiguration"/>

5.2.3. Possible errors

Table 3.86. Error codes

CodeReason
5004a mandatory parameter is missing.
6002the repository identifier is unknown.

5.3. The load repository query

This query allows loading a repository in the system.

If the query returns no error, the repository will be marked as "to be loaded" in the system. If the system hang or is restarted, the repository will be loaded.

Calling this request and receiving no error DOES NOT guarantee that the repository will be loaded. To monitor the load, see server log file.

5.3.1. Query specification

Table 3.87. HTTP Header

MethodGET
URI/iseeker/4_0/loadrepository

Table 3.88. Parameters

NameTypePossible Values
repository_idnumber0 to 99999

5.3.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/loadrepository"/>

5.3.3. Possible errors

Table 3.89. Error codes

CodeReason
5004a mandatory parameter is missing.
6002the repository identifier is unknown.

5.4. The unload repository query

This query allows unloading a repository in the system.

If the query returns no error, the repository will be marked as "not to loaded" in the system. If the system hang or is restarted, the repository will not be loaded.

Calling this request and receiving no error DOES NOT guarantee that the repository will be unloaded. To monitor the repository unload, see server log file.

5.4.1. Query specification

Table 3.90. HTTP Header

MethodGET
URI/iseeker/4_0/unloadrepository

Table 3.91. Parameters

NameTypePossible Values
repository_idnumber0 to 99999

5.4.2. Response specification

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/unloadrepository"/>

5.4.3. Possible errors

Table 3.92. Error codes

CodeReason
5004a mandatory parameter is missing.
6002the repository identifier is unknown.

6. Other Queries

6.1. The compare images query

This query compares two images and returns a difference score and upto 3 separate image(s) on request. The two compared images can be outside (using image_filename) or already in an LTU repository (image_id) application.

The image(s) returned is specified by setting the expected_attribute value(s):

ltu_kimage_error_map (default) and/or ltu_kimage_overlap (a new image consisting of an overlapped view of the two compared image)s and/or ltu_kimage_spotted_error (a new image consisting of a side by side comparison with boxes surrounding the different sections) allowing up to three images to be returned with the one query.

The returned image(s) are 64 base encoded and encupsulated in XML tags "rendition".

6.1.1. Query specification

Table 3.93. HTTP Header

MethodPOST
URI/iseeker/4_0/compareimages
Encoding typemultipart/form-data

Table 3.94. Parameters

NameTypePossible Values
[repository_id]number0 to 99999, the repository id is required to use image_id1 or image_id2 parameter
image_filename1fileBinary stream of the image
image_id1textUnique Image identifier in engine server repository (application)
image_filename2fileBinary stream of the image
image_id2textUnique Image identifier in engine server repository (application)
[expected_attribute]*textExpected return

6.1.2. Response specification

Note

The score values are from 0.0 to 1.0 and 100. 100 means the images are so completely different that they cannot be compared.

<?xml version="1.0" encoding="utf-8"?>
<ltu_query service="iseeker" query="/4_0/searchimage">
 <ltu_kimage>
  <rendition>
   <id>error_map</id>
   <md5>#213146958ace6aac8f2068551aa84b01</md5>
   <data>
(base64 encoded returned image)
   </data>
  </rendition>
  <rendition>
   <id>overlap</id>
   <md5>#22a55416534ef6d50c6c6741dd6914ec</md5>
   <data>
(base64 encoded returned image)
   </data>
  </rendition>
  <rendition>
   <id>spotted_error</id>
   <md5>#f7c728f981bd20990b0a9c62b3a59058</md5>
   <data>
(base64 encoded returned image)
   </data>
  </rendition>
  <score>0.21</score>
 </ltu_kimage>
</ltu_query>

6.1.3. Possible errors

Table 3.95. Error codes

CodeReason
5004A mandatory parameter is missing.
5006One of the image_id1 or image_id2 identifier is unknown.
5012The uploaded image is too big.
5013The uploaded image format is not supported.
5014The uploaded image is corrupted.
5018The uploaded file size is null.
5019The query POST message is too big.
5024Exactly 2 input images must be provided
6002The repository identifier is unknown.
6005The repository is not activated

6.2. The get image query

This query returns the binary data on the specified image. The rendition identifier is used to retrieve the original image (rendition id equals to 0) or the thumbnail of the original image (rendition id equals to 1).

6.2.1. Query specification

Table 3.96. HTTP Header

MethodGET
URI/iseeker/4_0/getimage

Table 3.97. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
image_idnumber0 to 9999999999
rendition_idnumber0 or 1

6.2.2. Response specification

The response is the binary stream of the image.

6.2.3. Possible errors

Table 3.98. Error codes

CodeReason
5004a mandatory parameter is missing.
6002the repository identifier is unknown.
5008the ltu_kimage identifier is unknown.
50011the rendition identifier is unknown.

6.3. The get binary query

This query returns the binary data of the specified binary attribute for the specified entity. It is a very specific request that only allows to get the binary objects (a thumbnail, a image, etc.) from an external image. An external image is a table containing the image queries of an autoscan. Every time an autoscan is ran, all query images are stored in the external image table, until the reports generated by autoscan is deleted. The request get_binary can be used to get some binary objects related to one of these external images.

Example: repository_id:XXX
         entity name: ltu_external_image
         entity_id: 100 (number of the external image in the autocan reports from repository XXX)
         attr name: thumbnail_ltu_bin_auto

The attribute name thumbnail_ltu_bin_auto indicates that you wish to get the thumbnail attached to this external image. The fact that it says "auto" at the end indicates that it will automatically detect if the thumbnail is stored on disk or in the database. If the thumbnail is stored on disk, the attribute will be converted into thumbnail_ltu_bin_ref. If the thumbnail is stored in the database, the attribure will be converted into thumbnail_ltu_bin_raw.

6.3.1. Query specification

Table 3.99. HTTP Header

MethodGET
URI/iseeker/getbinary

Table 3.100. Parameters

NameTypePossible Values
repository_idnumber0 to 99999
entity_idnumber0 to 9999999999
entity_nametextThe name of the entity
attr_nametextThe name of the attribute

6.3.2. Response specification

The response is the binary stream of the binary data. The content type will inform on the supposed content of this binary.

6.3.3. Possible errors

Table 3.101. Error codes

CodeReason
5004a mandatory parameter is missing.
6002the repository identifier is unknown.
5006the entity_id identifier is unknown.