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.

 

How to use

Managing photos

Uploading, editing and deleting photos

Management Panel allows for uploading, editing and deleting photos. To add a new picture just click the Upload photos from disk and select the appropriate image file (or multiple files at once) from the disk The file should be saved in JPG format (*. jpg,*. jpeg ), its size cannot exceed 2MB, and the optimal resolution is 640x480 pixels. Learn more about preparing photo and operation of the system .

When adding new photos the limit is taken into consideration. Your photo limit depends on the version of an account which you can check in Account tab. After exceeding the limit you can delete the selected photos to upload new ones in place of the previous ones. To delete a photo, click the delete icon () and confirm the choice. You can change ID or file name, by clicking the edit icon () and approving the changes by clicking on the save icon ().

To save the changes to the database, click the button . After applying changes, correctly uploaded images, visible to the algorithm, will have noted status ok. Learn more about the photos. statuses of the photos and building the index by further reading: Photo statuses and Applying changes in the database.

Uploading photos using XML file

Users can upload photos using XML file. You have to choose the Upload from XML from Manage Photos section. Then you will be warned about possible data loss, which will happen, if some of the photos were uploaded earlier with manual method. You have to agree to proceed, so please, make a copy of the earlier uploaded images and include them in your XML file, if necessary. Then you will be asked for link to the hosted XML file. When the link to the XML file is indicated, Recognize.IM platform will start to import the data.

For correct import, 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. Next you should wait until your XML is parsed and checked. After the import, changes will be automatically applied.

Photo statuses

Explanation of all photo statuses:

  • - ok - the photo is in the database and is available for photo recognition algorithm; this status is gained after applying changes when files were uploaded correctly,
  • - uploaded - the image is properly uploaded and ready to be added to the database; to add a photo to the database you must click the .Apply. button,
  • - uploading, processing . file is being uploaded or processed,
  • - error - incorrectly uploaded file, status may occur due to a failure of the server,
  • - incorrect - photo is not distinctive enough; image cannot be identified by the algorithm,
  • - deleted - file which was deleted from the database; you must apply changes to upload a new photo in place of the deleted one

Applying changes in the database

The changes are applied correctly if you received an e-mail confirming completion of applied changes on the server. Additionally, you can download a CSV file with a list of image ids from the database.

Applying changes is important for the proper operation of your application. Only photos which have been properly added to the database will be recognized by the algorithm.

API Details

Our API is divided into two separate parts. The first part is a lightweight REST-based API which allows you for sending image recognition requests. The second part is a SOAP-based API which can help you with managing your photos. 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. Also you can always check our Github repositories for sample applications.

REST API

For proper operation you need an API key and Client ID, which you can copy from the tab Get Sample App or Account.

REST methods available for image recognition are described by given pattern:
http://recognize.im/VERSION/recognize/MODE/CLIENT_ID

  • - VERSION is denotation of used version. Currently you should use 'v2'. Using of API v1 is deprecated.
  • - MODE is symbol for one of Recognition Modes. In default API returns only single result. To fetch all results simply append /all to MODE designation.
  • - CLIENT_ID is your numeric identifier. You can copy it from Account tab.

To use API you need to sent the HTTP request at the above addresses with:

  • - the header content-type as an image/jpeg,
  • - x-itraff-hash with abbreviation MD5 generated from the glued: API key and the image,
  • - the picture in the message.

In response, you get a JSON object containing the fields:

  • - status, value 0 means success, any other value is treated as an error
  • - message, contains an error message (absent on success),
  • - objects, contains JSON representation of matched objects.

Single result object is described by:

  • - id
  • - name
  • - location of bounding box arround matched object as coordinates of vertices (4 points).

Ready, full, sample application code for iPhone and Android with documentation can be downloaded in tab Get Sample App

Image Recognition Modes

There are two recognition modes: Single and Multi. Both can match several reference images to a single query picture, but their meaning is different.
In Single we expect that the query image will contain only one object - the object that you want to recognize. We look up this object in your database and identify all images that are considerably similar. Based on your decision we might return only the best match (single), or all of them (single/all).
Multi is significantly different in this respect. Here we expect that query images will contain one or many different objects. Each object is looked up in your database and a single best match is selected for each object. All resulting matches are returned (multi). Multi can be switched to multi-instance mode (multi/all), which results in searching for more than one occurrence of each object in a single query image.

You need to remember that you can use only one mode at a time. To switch mode you should call modeChange.

Android sample application

Application can be divided into three modules:

Step 1: Taking a picture

This can be solved in any way, e.g. by calling the default application for taking pictures. However it is important that the picture meets the requirements of this application. To recognize single object your picture needs to be larger than 100px in width and 100px in height. Picture area must be larger than 0.05Mpx and should not exceed 0.31Mpx (e.g. 640x480). In addition image file size must not exceed 0.5MB. When recognizing multiple objects in one query, each object should be larger than 240x240 pixels and the whole picture area should be between 0.1Mpx and 5Mpx and not larger than 3.5MB. These are sufficient resolutions to be properly recognized by the algorithm. Uploading pictures of very high resolution is uneconomical and will slow down recognition process due to transfer limitations.

Step 2: Communication with API (pl.itraff.TestApi)

To improve the communication, a library which connects to the API was created.

Example of use in the MainActivity class.

Handler responsible for receiving and processing responses.

	private Handler itraffApiHandler = new Handler() {
 		// Setting_callback_method from api
 		@Override
 		public void handleMessage(Message msg) {
 			Bundle data = msg.getData();
 			if (data != null) {
 				Integer status = data.getInt(ItraffApi.STATUS, -1);
 				String response = data.getString(ItraffApi.RESPONSE);
 
 				if (status == 0) { // status ok
 					// TODO response contains json with your data
 				} else if (status == -1) { 
					// application error (for example timeout)
 					// TODO show application error
 				} else { // error from api
 					// TODO get "message" from response json - 
					// it contains api error
 				}
 			}
 		}
 	};

Calling API

	ItraffApi api = new ItraffApi(CLIENT_API_ID, CLIENT_API_KEY, 
									TAG, false);
	api.sendPhoto(pictureData, itraffApiHandler);

Parameters

	CLIENT_API_ID       // API User ID
	CLIENT_API_KEY      // API user key
	tag                 // tag used in the log library (Log.v(TAG, ""))
	true/false          // enabling or disabling logging API

	pictureData         // byte[] array containing image
	itraffApiHandler    // Handler receiving the response, 
						// the code above

Step 3: Receiving and using the response.

The response is in JSON format. Method of receiving was presented in handler.

Ready, full, sample application code for iPhone and Android with documentation can be downloaded in tab Get Sample App.

SOAP API

Here you can find the WSDL file. Based on this file you can generate the code to execute API methods. For example in order to generate code in Java you could use Eclipse Web Tools Platform . There are many other tools you could use.

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 another picture to your pictures list you need to call insertImage method. Remember, however, that the image won't be recognizable straight after its insertion - you need to call indexBuild method so that all recently added pictures starts to be recognizable.

Method name: insertImage

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

You need to call indexBuild method in order to apply all your recent (from the previous call of this method) changes, including adding new images and deleting images. This method may take a lot of time in some cases (it depends on the number of images you have in our database), therefore this method is asynchronous. Output of the indexBuild lets you know if the method was started properly. You can set a method which should be called when indexBuild is finished - check Setting callback method section. Anytime you can check what is the progress of applying the changes. In order to do this check getting the progress of applying the changes.

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 don't need an image to be recognizable anymore you have to remove this image from the database. You can do this by calling imageDelete method passing the ID of the image you want to remove. You can also remove all of your images with one call of this method. In order to achieve this you need to pass null value as a parameter.
Remember, however, that (similarly to the situation when you insert new image) you need to apply changes before the image is no longer visible for our algorithm.

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 the progress of applying the changes

You may be curious what is the progress of applying your changes. In order to do this you need to call indexStatus method.

Method name: indexStatus

Parameter Description
The method does not require any parameters

Returns values (in a map object):

Value name Description
status Values:
0 - getting the progress of applying changes was executed without any problems; any other value means that there was a problem with the getting the progress of applying the changes.
message human - readable message describing the problem with getting the progress of applying the changes. (it is set only if the status value is different from 0)
data Map containing the information about the progress of applying the changes. progress key holds the information about the progress of applying changes value equals to 100 means that the process of applying the changes is finished,
status - human-readable status of applying changes,
uploading - how many new images are being uploaded ,
needUpdate - how many images have been changed and need to be updated.

Sample use:

				iTraffSoap.indexStatus()

Sample answers:

{status=0, data={progress=87.5, status=processing, uploading=1, needUpdate=3}}
{status=0, data={progress=100, status=ok, uploading=0, needUpdate=0}}

Checking what your limits are

When using our API you are limited with regards 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 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 IR Mode

To recognize another type of objects you should change IR Mode. More about IR Modes you can read here.

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,