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.
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:
Recognition mode | Max file size | Min edge length |
---|---|---|
Single | 2 MiB | 480 pix |
Multi | 2 MiB | 480 pix |
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.
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.
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.
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.
You can schedule the deletion of an image present in your reference collection. The image deletion takes effect after the changes are applied.
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.
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:
Status | Description | Recognizable | Suggested action |
---|---|---|---|
uploading | In the upload queue or in pre-processing. | No. | Wait for pre-processing to end. |
uploaded | After successful pre-processing. Ready to be included to the recognizable objects. | Not yet. | Apply changes. |
processing | In process of being included in the recognizable objects. | Not yet. | Waiting for changes applying to end. |
ok | Included in the recognizable objects. | Yes. | |
removed | Scheduled to be excluded from the recognizable objects on the next changes applying. | Yes, still present in the recognizable objects. | Apply changes to exclude it from the recognizable objects. |
invalid | Rejected in pre-processing — the object is not distinct enough to be recognized. | No. | Remove, review the contents and quality of the image, and try to re-upload. |
error | Failed to upload due to damaged data or a technical problem. | No. | Remove, make sure the image data is faultless, and try to re-upload. |