CraftAR Python Library

Description

The Craftar Service for Image Recognition is a service that allows you to build a wide range of Image Recognition applications and services.

With Craftar, you can create amazing apps that provide digital content for real-life objects like printed media, packaging among others. You can use our online web panel or APIs, to upload images to be recognized and set content to display upon recognition in your CraftAR-powered app.

This client library provides access to CraftAR APIs:

• [CraftAR Image Recognition API] (http://documentation.catchoom.com/documentation/api/recognition/) allows image recognition against one of your collections of reference images specified using the collection token.
• [CraftAR Management API] (http://documentation.catchoom.com/documentation/api/management/) allows upload and management of collections of reference images, and associated meta-data. All requests must be authenticated using your Management API key.

The library also provides tools for performing batch operations:

• craftar_search, for Image Recognition.
• craftar_upload, for batch upload of images.

Installation

If you already have Python and pip on your system you can install the library simply by running:

pip install craftar

In case you first need to install Python or pip, please follow specific instructions for your operating system.

Windows

On Windows we recommend using the library within Cygwin, which provides a Linux look and feel environment:

1. Download Cywin installer from the official page.
2. In the installer wizard, select all python packages, and libmpfr-devel (under libs category).
3. Open the Cygwin shell and execute the following commands:

easy_install pip
pip install craftar

Mac OS X

Python comes pre-installed on Mac OS X, so typically you only need to add pip:

easy_install pip
pip install craftar

Dependencies

• Requests
• Pillow

Quick Start

Follow these steps to create a collection with one item and perform an image recognition request against that collection. A collection is a set of items representing entities that you want to recognize. Examples of items are logos, physical objects, or a drawings, among others. You can do it directly from your python interpreter.

1. Get your management api_key. This is needed to authenticate your requests to the Management API.

   import craftar
   
   # use your own api_key!
   api_key = "35d5919334816e239bba08637e6aa457e8ca92c8"

2. Create a new collection.

   name = "My cool colection" # use your own collection name
   collection = craftar.create_collection(api_key, name)

3. Keep the token of that collection, you will need it later for the recognition:

   token_list = craftar.get_token_list(api_key, limit=1, offset=0,
                                       collection=collection["uuid"])
   token = token_list[0]["token"] # first token on the list

4. Create an empty item in your collection:

   name = "My cool item" # use your own item name
   url = "http://example.com" # and your own url
   custom = "This is my custom data" # and your own custom data
   item = craftar.create_item(api_key, collection["uuid"], name, url, custom)

5. Upload an image representing your item.

• Every item can be represented by one or more reference images. This is useful for items that have different faces, e.g. cereal boxes.

• Before performing a successful recognition, the corresponding reference image needs to be fully indexed by the server. Normally it takes less than one second after uploading.

  filename = "reference.jpg" # use your own image
  image = craftar.create_image(api_key, item["uuid"], filename)

6. Now you are ready to perform the image recognition request against your collection.

• You will also need the token you saved in step 3 and the image to be recognized.

  # remember that you set _token_ in step 3
  filename = "query.jpg" # use your own query image
  result_list = craftar.search(token, filename)

7. Done! You can print the result:

   print result_list

   • Each returned reference image has an associated score, indicating its relevancy to the query image.

Scripts

The scripts under /bin allow batch operations against the APIs:

• craftar_search sends one or several Image Recognition requests against the CraftAR Service. Specifically, it performs visual scans against the collection (specified by the token) using every image in the provided directory.
• craftar_upload uploads a set of reference images to the CraftAR Service. It iterates over the contents of the specified directory and uploads all the images (and, if provided, also their associated metadata) to a new or an existing collection.

Examples

In order to see reference implementations demonstrating the most common operations that can be performed with our APIs check the scripts under the examples folder:

• example_list_paginated_items: Lists all your items. If required, the listed items can be limited to a specific collection.
• example_management: Demonstrates listing, creation, updating and deletion of every type of object (i.e. collection, item, image, token).

For the reference implementation of the recognition operation see the script craftar_search script under /bin.

Reporting Issues

If you have suggestions, bugs or other issues specific to this library, file them here or contact us at support@catchoom.com.