This site uses cookies.

We use the information stored by cookies and similar technologies for statistical purposes and to adjust our services to the individual needs of users. They can also be used by tools and scripts running on the website. You can change the cookie settings in your internet browser.

If you continue using our services without changing the cookie settings they will be stored in the memory of your computer or other device.

 

Documentation

Preparation of pictures

Reference pictures

Reference pictures are what defines collection of the User's recognizable objects. After they are uploaded to the Manage photos panel, one can index them, and therefore, allow recognition of the reference objects they represent.

The quality of reference pictures has a significant impact on the image recognition performance. A single reference image should represent exactly one object (and that object only) as precisely as possible. If presence of the background is unavoidable, a flat white background should be used.

Depending on the selected recognition mode, there are various limitations for the reference pictures:

Single:

- max file size: 2 MB
- min picture edge length: 480 pix

Multi:

- max file size: 2 MB
- min picture edge length: 480 pix

The reference pictures should show a 2D surface of the object. The API accepts reference pictures in JPEG format. Please refer to the guidelines for preparing reference pictures for more specific, illustrated examples and explanations.

Query pictures

Query pictures are the real world representations of the objects. Once such a picture arrives to the API, it gets analyzed and compared to the contents of the reference dataset, which allows returning recognition results.

When taking a query picture, one should try to fit the object (or objects) into the frame as well as possible, although the Technology tolerates a certain level of imperfection here. It is very important to avoid blurring, overexposure, darkness and strong light reflections. Using flash lamp is not recommended. The API accepts query pictures in JPEG format.

As in the case of reference pictures, the limitations for query pictures depend on the recognition mode:

Single:

- max file size: 2 MB
- min picture edge length: 100 pix
- min picture surface: 0.05 Mpix
- max picture surface: 0.5 Mpix

Multi:

- max file size: 5 MB
- min picture edge length: 100 pix
- min picture surface: 0.1 Mpix
- max picture surface: 6 Mpix

The query picture limitations regard the pictures themselves rather than the objects they represent - note that for some recognition modes query pictures may contain several objects. The most general rule that can be successfully applied for every recognition mode says that a single object in the query picture should not have any dimension shorter than 150 - 200 pixels. This means that the size of query picture can be adapted depending on the expected number of objects, for example, to reduce data transfer - uploading pictures in very high resolution is impractical and will slow down the recognition process due to transfer limitations.

Reference database management

Uploading, editing and deleting pictures

Manage photos panel enables uploading, editing and deleting reference pictures. It provides the full access to the account and reference database settings in order to make getting started and testing easier for the Users. Please note that all the actions on the account and the reference database can be accomplished as well using SOAP API methods.

Adding an image
In order to add a new picture just click the Upload pictures from disk button and select an appropriate image file (or multiple files at once) from the disk. The pictures are pre-processed asynchronously in the background and the current state of that process is being represented by the status.

Checking the limits
When adding new photos the account limits are taken into consideration. Your photo limit depends on the pricing package selected for the account, which you can check in your Account management panel. After exceeding the limit you can delete selected pictures in order to upload new ones in place of the previous ones, or increase your limit by choosing a higher pricing package.

Deleting an image
In order to delete a picture, click the delete icon () and confirm the choice.

Updating an image
You can change the ID or the file name by clicking the edit icon () and approving the changes by clicking on the save icon ().

Applying changes / Index building
In order to apply the changes to the database, click the button. This starts the procedure of indexing, ch allows carrying out searches in the reference database quickly and efficiently. After applying the changes, the correctly uploaded images that are visible to the algorithm will have the ok status.

Before the index becomes rebuilt, all the changes made to the reference database are invisible to the recognition algorithms. This enables making several changes to the reference pictures database and choosing the moment when they are supposed to take effect.
Important: Updating an image takes place right away, just after the save button () is pressed or the imageUpdate method is called.

Picture status

Every reference picture added to the reference database obtains a status representing the current state of the picture. The status may have one of the following values:

  • - uploading - picture is still in the upload queue, or it is being pre-processed at the moment,
  • - uploaded - the image has been already properly uploaded and pre-processed and is ready to be included in the index,
  • - processing - the image is being included into the index at the moment,
  • - ok - the picture has been indexed correctly and is available for recognition algorithms; this status is obtained after applying changes after the image is uploaded correctly,
  • - removed - picture has been deleted from the reference pictures list, but is still present in the index - it will disappear after applying the changes,
  • - error - failed to upload the file (e.g. due to bad image data encoding or network-related problem),
  • - invalid - the picture is uploaded and pre-processed correctly, but the object in the picture is not distinct enough; it cannot be identified by the algorithm and therefore it is rejected - it will not be included in the index.

When applying changes, the uploaded pictures obtain processing status and they become included into the index together with previously indexed ones (with ok status). When the application of changes is finished, they all receive the ok status. The remaining pictures (removed, error and invalid) can be present on the reference pictures list (they do not block index building), but they will not be recognizable.

Uploading pictures using an XML file

Uploading pictures can be accomplished using an XML file. You have to choose the Upload photos from XML button in the from Manage Photos section.

You will be warned about possible data loss, which is going to happen if some of the pictures were uploaded earlier using the manual method. You have to agree to proceed, so please make a copy of the images uploaded earlier and include them in your XML file, if necessary. Afterwards, you will be asked for the link to the hosted XML file. After the link to the XML file is provided, Recognize.im platform will start importing the data. You should wait until your XML is parsed and checked. After the importing is finished, the changes are going to be applied automatically.

For the importing to take place correctly, the data should be arranged in a specific order. Your XML must be valid according to our XML Schema. If you are not sure if it is valid, you can always check the exemplary XML file.

Please note that the XML uploader assumes that all the pictures linked within the XML file are correct and they meet all the requirements. The pictures for which the verification process will fail shall be skipped silently, with no error code or message returned.

Browsing the reference database

It is possible to view the contents of the reference picture database using the Manage Photos panel, where the list of pictures with icons, IDs, names and statuses is presented. Additionally, one can use the Download CSV button in the Manage photos panel in order to fetch a detailed list of reference pictures.

There are two SOAP API methods that allow obtaining the list of the reference pictures and checking their statuses: imageList and indexStatus.

API Details

Our API is divided into two separate parts. The first part is a lightweight REST-based API that allows sending image recognition requests. The second part is a SOAP-based API which can help you manage your reference database. We provide you with a ready-to-go WSDL file so you just need to generate a client code and start using the API method. Additionally, you can always check our Github repositories for sample applications.

REST API

REST connector

The REST connector requires the API key and Client ID for proper operation, as it is desinged to send only secured queries to a particular account. Every User obtains these credentials on registration - they can be found in the Account management panel.

The REST methods available for image recognition are described by the following pattern:
http://clapi.itraff.pl/VERSION/recognize/MODE/CLIENT_ID

  • - VERSION is the designation of version used. Currently you should use 'v2'. Version 'v1' of the API is obsolete and using it is not recommended.
  • - MODE is symbol for one of the recognition modes. Please refer to recognition modes description for more details.
  • - CLIENT_ID is your numeric identifier. You can copy it from the Account tab.

In order to send a recognition request, you need to send a HTTP request using the path specified in the form described above with:

  • - the header content-type being an image/jpeg,
  • - x-itraff-hash with abbreviation MD5 generated from the concatenated API key and the base-64 encoded image data,
  • - the base-64 encoded image data.

The response arrives in JSON format and it contains:

  • - status, value 0 means success, any other value denotes an error
  • - message, contains an error message (absent on success),
  • - objects, contains list of objects matched (if there are any).

A single item in the response, representing a matching object from the reference database, is described by:

  • - id
  • - name
  • - location

The location is given in the form of (x, y) coordinates of four bounding box corners. Please note that these points represent particular corners of the reference object (upper-left, upper-right, lower-right, lower-left), which enables finding out the actual orientation of the object in the query picture.

Please also note that you can find ready-made sample codes that implement the REST connectors described above in our Github repositories. You are free to use these codes partially or entirely in your own projects.

A ready and full sample application code for iPhone and Android with documentation can be downloaded in the Get Sample App tab (available for registered Users).

Recognition Modes

The API can operate in the following recognition modes:

The Single mode.
This mode assumes that the query image will include only one object. It looks up this object in the reference database and identifies all images that are considerably similar.
Depending on the REST path settings (MODE field), it might return only the best match (single), or all of them (single/all) - the best match and similar objects ordered by the level of certainty. This means that, if it is desired, the Single mode is able to match several objects into a single region of the query picture.
The Single mode operates on grayscale images. However color pictures can be used as well - they will be converted to grayscale in the background.

The Multi mode.
This mode assumes that the query images will include one or more objects. Each object gets looked up in the reference database and a single best match is selected for each object.
Please note that a single object might appear multiple times in a single query picture. Depending on the REST path settings (MODE field), the Multi mode might return only a single, best-matching instance of each object (multi), or all of them (multi/all). Unlike the Single mode, it returns only a single matching object (the best one) for a single region of the query picture.
The Multi mode operates on grayscale images. However, color pictures can be used as well - they will be converted to grayscale in the background.

Please keep in mind that you can use only one recognition mode at a time. To switch the current mode you should use the modeChange method or options available in the Manage photos panel. The recognition mode used in the REST path should match the one selected in the Account management panel.

Note that since the reference pictures pre-processing routines vary for different recognition modes, switching to another recognition mode can only take place when the reference database is empty.

Querying application

An application that sends queries to the API can be divided into three basic modules:

Step 1: Taking a picture

This can be done in any way, e.g. by using the default application for taking pictures or camera API. Images that are already present in the device storage memory can be used as well. It is very important to ensure that the query picture meets the requirements of the selected recognition mode.

Step 2: Sending request

After the picture is available, the application must communicate with the Recognize.im API in order to upload the picture. The details of communications are described here, or can be found in sample codes.

Step 3: Receiving the response.

After the query picture is processed, the API returns the response. The User is free to use the received IDs and locations of the recognized objects according to the specific needs of Her or His project.

Please note that a querying application does not have to be a mobile application - it can be a web service, server console application, web crawler or any other software or device connected to the Internet that is able to somehow obtain the pictures, send the queries and process the results.

SOAP API

The best and the quickest way to get started with SOAP API is to download one of the example codes and use the connectors implemented there.

We provide the WSDL file, but using it for code generation usually causes parser trouble on some specific data structures we use. Thus, the recommended way to get SOAP API connector is to use example codes mentioned before. The WSDL file however, remains available in order to provide some more details about SOAP API methods, if needed.

Here are the most important methods you need to know in order to use our API:

Authentication

We need to know that you is you so that no one else uses your account. In order to do this you need to authenticate with the use of the auth method. Your are authenticated within a session. Remember to turn on the session maintaining on the client side.

Method name: auth

Parameter Description
client_id Your unique client ID. You can find it in the Account tab after logging in at recognize.im.
key_clapi Your unique secret client key. You can find it in the Account tab after logging in at recognize.im.
ip IP address permitted for reading images from the API. If you want to use the same IP address as you use to make this request just pass null value.

Returns values (in a map object):

Value name Description
status Values:
0 - you have been successfully authenticated
1 - you haven't been authenticated
message human - readable message describing the problem with authentication (it is set only if the status value is different from 0)

Sample use:

				final String MY_CLIENT_ID = "111";
				final String MY_CLAPI_KEY = "1a2b3c4d5e6f";
				HashMap authResultMap = iTraffSoap.auth(MY_CLIENT_ID, MY_CLAPI_KEY, 
															null);

Sample answers:

Successful authentication:
{status=0}
Unsuccessful authentication:
{message=Authentication failed, status=1}

Adding an image

In order to add a new image to your database of reference pictures you need to call the imageInsert method. Before the image gets added, the correctness of the image data and the uniqueness of its ID are checked. If everything is fine, the picture is scheduled for insertion and obtains uploading status. Afterwards it is processed in the backround and receives one of the further statuses, depending on the pre-processing result.

Please note that the uploaded status does not mean that a newly added image is already recognizable - it has to be included into the index by calling the indexBuild method.

Method name: imageInsert

Parameter Description
id A unique identifier of the inserted image.
name A label you want to assign to the inserted image.
data The data of the inserted image. The image should be encoded with Base64. In order to encode your image you can use this Apache library.

Returns values (in a map object):

Value name Description
status Values:
0 - image has been successfully added, any other value means that the image has not been added.
message human - readable message describing the problem with adding the photo (it is set only if the status value is different from 0)

Sample use:

				String customImageId = "ID_123";
				String customImageName = "custom_name";
				// use your code to encode the image data to String with Base64
				String data = encodeToBase64(imageData);  
				iTraffSoap.imageInsert(customImageId, customImageName, data);

Sample answers:

Success:
{status=0}
Failure:
{message=Image exception : Image format not supported, status=200}

Applying changes / Index building

Once any changes are made to the reference database content, the index building must be executed in order to apply these changes. The execution time of index building depends on the total number of the reference pictures - it might take several hours if the database contains hundreds of thousands of images and therefore this method is asynchronous. The output of the indexBuild lets you know if the method was started properly, but does not report the final effect of the whole operation.

Please refer to image status descriptions for detailed explanation of what happens to each status when the application of changes is executed.

Important: Please note that the indexBuild and imageInsert methods are both asynronous. Thus, if the indexBuild is called right after a series of imageInsert calls, there is no guarantee that all added pictures will be indexed, since backround pre-processing of some of them might still be in progress at such moment. In order to make sure that the application of changes is going to include all the recently added pictures, prior to calling the indexBuild method you can check the indexStatus response - the 'uploading' field should equal 0.

You can set a method which should be called when indexBuild is finished - check the Setting callback method section. You can check the progress of the index building anytime using the indexStatus method.

Receiving an e-mail confirming completion of application of changes on the server means that the changes have been applied correctly.

Method name: indexBuild

Parameter Description
The method does not require any parameters.

Returns values (in a map object):

Value name Description
status Values:
0 - applying changes started correctly, any other value means that there was a problem with applying changes
message human - readable message describing the problem with applying changes (it is set only if the status value is different from 0)

Sample use:

				iTraffSoap.indexBuild();

Sample answers:

{status=0}

Setting callback method

There are some situations when we might need to call one of your methods. For example when we finish applying changes we may need to let you know that all your images are ready to be recognized.

Method name: callback

Parameter Description
callbackURL The URL to the method you want us to call.

Returns values (in a map object):

Value name Description
status Values:
0 - the URL to the callback was successfully set, any other value means that there was a problem with setting the callback method
message human - readable message describing the problem with setting the callback method (it is set only if the status value is different from 0)

Sample use:

		iTraffSoap.callback(new URI("http://example.com/your/method"));

Sample answers:

{status=0}

Removing images

If you do not need an image to be recognizable anymore you have to remove this image from the database. You can do this by calling the imageDelete method and providing the ID of the image you want to remove. You can also remove all of your images with one call of this method, providing the NULL value as the parameter.

The procedure of deletion of a single image or all images is executed instantly. The pictures obtain the removed status, but they are still present in the index and thus they can be returned in recognition results. For this reason, they will remain on the picture list until the changes are applied.

Method name: imageDelete

Parameter Description
ID ID of the image you would like to remove (this is the same ID you pass a an argument to the imageInsert method). Pass null value if you want to remove all of your images.

Returns values (in a map object):

Value name Description
status Values:
0 - image has been successfully removed, any other value means that the image has not been removed.
message human-readable message describing the problem with removing the photo (it is set only if the status value is different from 0)

Sample use:

				String customImageId = "ID_123";
				iTraffSoap.imageDelete(customImageId);

Sample answers:

Success:
{status=0}
Failure:
{message=Image not found, status=1}

Updating images

There may be some situations when you would like to change the name or ID of an image stored in the database. You can do this by calling the imageUpdate method.

Method name: imageUpdate

Parameter Description
ID ID of the image which data you would like to change (this is the same ID you pass a an argument to the imageInsert method).
data This is a map holding new data of the updated image. id key holds the new id of an image. name key holds the new name of an image.

Returns values (in a map object):

Value name Description
status Values:
0 - image has been successfully updated, any other value means that the image has not been updated.
message human - readable message describing the problem with updating the photo (it is set only if the status value is different from 0)

Sample use:

				String customImageId = "ID_123";
				String newCustomImageId = "ID_789";
				String newCustomName = "some_new_name";	
				HashMap<String, String> newData = new HashMap<String, String>();
				newData.put("id", newCustomImageId);
				newData.put("name", newCustomName);
				iTraffSoap.imageUpdate(customImageId, newData);

Sample answers:

Success:
{status=0}
Failure:
{message=Image ID_123 not found, status=1}

Getting a list of images

The imageList method allows fetching the list of reference pictures uploaded. Due to data transfer limitations, one can obtain only up to 50 items in a single method call. In order to get the entire list, one should enclose the method within a loop and increment the offset, which determines where the current partial list starts.

The list becomes ordered by the age of pictures (those recently added go before the ones added long ago).

Method name: imageList

Parameter Description
limit The number of items in the list (default = 20, max = 50).
offset The offset pointing to the index of picture with which the list is supposed to begin (default = 0).

Returns values (in a map object):

Value name Description
id The ID of the picture.
href The URL of the picture.
name The file name.
status The status of the picture.

Sample use:

				Int limit = 3;				//fetch three pictures..
				Int offset = 200;			//..starting from the 200th one
				iTraffSoap.imageList(limit, offset);
				iTraffSoap.imageList();		//use default limit and offset

Sample answers:

{
{id="image-200", href="://clapi.itraff.pl/image/200", name="200.jpg",
status="ok"}

{id="my image 201", href="://clapi.itraff.pl/image/201", name="201.jpg",
status="removed"}

{id="picture 202", href="://clapi.itraff.pl/image/202", name="202.jpg",
status="invalid"}

}

Sample use:

				Int limit = 50;		//max possible partial list length
				Int offset = 0;		//start at the beginning of the list
				List, PartialList;
				for (offset = 0; ; offset += 50) {
					PartialList = iTraffSoap.imageList(limit, offset);
					if (PartialList.empty())
						break;
					List.append(PartialList);
				}

Checking the index status

You may want to check the progress of application of changes or image adding and removing operations. In order to do that you need to call the indexStatus method.

The response received contains information about the progress of index building, the status of the index, and the counters of pictures sorted by their statuses. This is especially useful for determining whether previously ordered operations of image adding have been already completed, which allows determining whether the index building can be called safely.

Method name: indexStatus

Parameter Description
The method does not require any parameters

Returns values (in a map object):

Value name Description
status Determines whether the status check was executed correctly and whether its results are reliable.
message Human-readable message describing the problem with obtaining information on the prograss of application of changes. It is set only if the status denotes an error.
data Information about the progress of application of changes, the index status and image counters sorted by their statuses.
progress - the progress of application of changes, expressed as percentage,
status - human-readable status of application of changes,
uploading - counter of images curretly being uploaded,
uploaded - counter of correctly uploaded images,
processing - counter of images that are currently being included into the index,
removed - counter of correctly removed images,
ok - counter of recognizable images,
error - counter of erroneous images,
invalid - counter of invalid images,
needUpdate - counter of the images that require application of changes.

Sample use:

				iTraffSoap.indexStatus()

Sample answers:

{"status":"ok", "progress":100,
"uploading":0, "uploaded":0, "processing":0, "removed":0, "ok":9,
"error":0, "invalid":2, "needUpdate":0}

(changes applied, 9 indexed images, 2 invalid images, no images require application of changes)

{"status":"processing", "progress":80,
"uploading":0, "uploaded":0, "processing":7, "removed":0, "ok":4,
"error":0, "invalid":0, "needUpdate":0}

(changes are being applied (80%), 7 new images are being included into the index, 4 indexed images, no images require application of changes)

{"status":"ok","progress":100,
"uploading":2, "uploaded":3, "processing":0, "removed":0, "ok":12,
"error":0, "invalid":0, "needUpdate":5}

(changes applied, 12 indexed images, 3 uploaded images, 2 images are being uploaded, 5 images require application of changes)

Checking what your limits are

When using our API you are limited with regards to the number of images and number of scans (recognition operations). The limits depend on the type of account you have. In order to check how many more images you can add and how many scans you have left you can use the userLimits method.

Method name: userLimits

Parameter Description
The method does not require any parameters

Returns values (in a map object):

Value name Description
status Values:
0 - limits were successfully retrieved; any other value means that there was a problem with fetching the information about the limits
message human - readable message describing the problem with fetching the information about the limits (it is set only if the status value is different from 0)
data Map containing the information about the limits.
image - number of images you have in the database,
limit_image - the maximum number of images you can have in the database,
scan - number of scans already done,
limit_scan - the maximum number of scans you can do within your subscription plan,

Sample use:

				iTraffSoap.userLimits()

Sample answers:

{status=0, data={image=7, limit_scan=10000, scan=0, limit_image=1000}}

Changing the recognition mode

The API allows to take advantage of several recognition modes. In order to change the recognition mode, one should call the modeChange method:

Method name: modeChange

Parameter Description
mode New mode, could be one of {'Single', 'Multi'}

Returns values (in a map object):

Value name Description
status Values:
0 - mode has been successfully changes, any other value means that the mode has not been changed.
message human - readable message describing the problem with changing the IR Mode (it is set only if the status value is different from 0)

Sample use:

				iTraffSoap.modeChange('Single');

Sample answers:

Success:
{status=0}
Failure:
{message=Method not allowed, status=1}

Other methods

Other methods specified in the WSDL specification are described in the generated documentation at http://clapi.itraff.pl/wsdl.

FAQ

Q: I try to call API methods but in return I.m getting:
{message=Auth required, status=1}
A: It means that you were not authenticated when calling an API method. Remember to always call auth method first. Moreover, remember that you are authenticated for the time of the session, so if the session is not valid anymore you need to reauthenticate.

Q:What tools can I use to generate the code from the WSDL specification?
A: You can use the following tools:

Q:I haven't found an answer to my question. What should I do?
A: Just drop us a message using the contact form.

Account

This tab contains information about the used number of scans and photos and other limits. The API key and your customer ID can be found here as well. There is also an option to change the password for registered users at the Image Recognition API platform, and the option to delete your account. Users can change their payment data: PayPal account and invoice data. They can also view their history of payments and invoices.

Auto-upgrade feature

In your Account tab you will find the auto-upgrade checkbox. Please check this option if you want to automatically upgrade your account after exceeding the limit of image scans. Otherwise your account will be blocked and you will not be able to recognize images using Recognize.im API until the next payment.

What will happen if we cannot process a user payment?

1. The first unsuccessful payment:
- we send an email with the information to a user,
- we block adding new images to user database,
- we wait one week to perform the next payment attempt.

2. Second unsuccessful payment (one week later):
- we send an email with the information to a user,
- we block image recognition,
- we wait one week to perform the next payment attempt.

3. Third unsuccessful payment (one week later):
- we send an email with the information to a user,
- we suspend a user account,