Introduction

Reference images define a collection of your recognizable objects. To perform a recognition query to our API, you have to tell our API what your recognizable objects are by preparing and uploading the reference images to your collection.

Data quality

The quality of the reference images has a significant impact on 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. The reference images should show a 2D surface of the object. The API accepts reference pictures in JPEG format.

For more detailed, illustrated examples and explanations of reference images preparation, please refer to the guidelines:

The following table shows the reference image limitations for various recognition modes:

Reference image collection

This section briefly explains the basic operations you can make on your reference image collection. All these actions can be performed using the collection management panel or by calling the API methods.

Uploading files

Once your reference images are prepared according to the quality guidelines, you can add them to your image collection. The images are pre-processed asynchronously in the background, and the current state of that process is being represented by the status.

Please note that image does not get recognizable right after it is uploaded and pre-processed. You need to apply changes to include the image into the recognizable objects.

Adding files with an XML file

You can also upload your reference images using an XML file. This will remove all previously uploaded files and add the new ones linked in the XML file.

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

Please refer to our XML schema file and our exemplary XML file to help you create your XML files. Note that the XML file does not include your images but only links them, so your reference images must be accessible by public URLs if you wish to load them using an XML file.

Updating an image

You can alter the description of any image in your reference collection. These changes take effect immediately, and new description will be returned in your recognition results right after the adjustment is made — no changes applying is necessary.

Since the reference images require pre-processing which determines whether the data can be included into recognizable objects, you cannot change already uploaded image data — you have to upload the new data as a new image and delete the old one.

Deleting an image

You can schedule the deletion of an image present in your reference collection. The image deletion takes effect after the changes are applied.

Applying the changes

After you make changes to your reference collection, you should confirm them by applying the changes. This starts the procedure of the actual updating of your recognizable objects.

You can introduce several changes to your reference collection, but choose to apply them later. This allows you to decide when exactly your changes should take effect, which is especially useful for controlling e.g., your campaigns' launch time.

Image statuses

Every uploaded reference image obtains a status representing its current state and indicating whether it is successfully included in the recognizable object collection. The following table shows all the possible image statuses and explains their meaning: