Skip to content
CraftAR Python Library
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin [MINOR] Changed default query image size (240px shorter edge). Feb 22, 2016
craftar Removes app deletion since the API doesn't support it and small versi… Mar 28, 2017
examples Update API endpoints to craftar.net domain Dec 11, 2014
.gitignore
AUTHORS
CHANGELOG.md Update requests and bump new version. Nov 9, 2018
LICENSE Catchoom Python Library 1.0 Feb 19, 2013
MANIFEST.in
PYPI Removes app deletion since the API doesn't support it and small versi… Mar 28, 2017
README.md
requirements.txt
setup.cfg
setup.py Update requests and bump new version. Nov 9, 2018

README.md

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:

The library also provides tools for performing batch operations:

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

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)
  1. 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)
  1. 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.

You can’t perform that action at this time.