CraftAR Python Library
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:
pip install craftar
In case you first need to install Python or pip, please follow specific instructions for your operating system.
On Windows we recommend using the library within Cygwin, which provides a Linux look and feel environment:
- Download Cywin installer from the official page.
- In the installer wizard, select all python packages, and libmpfr-devel (under libs category).
- 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
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.
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"
Create a new collection.
name = "My cool colection" # use your own collection name collection = craftar.create_collection(api_key, name)
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["token"] # first token on the list
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)
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)
- 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)
Done! You can print the result:
- Each returned reference image has an associated score, indicating its relevancy to the query image.
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.
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).