TopCodes: Tangible Object Placement Codes


The TopCode computer vision library is designed to quickly and easily identify and track tangible objects on a flat surface. Just tag any physical object with a TopCode (a circular black and white symbol) and the system will return:
  • An ID number
  • Location of the tag
  • Angular orientation of the tag
  • Diameter of the tag

The TopCode library will identify 99 unique codes and can accurately recognize codes as small as 25 x 25 pixels. The image processing algorithms work in a variety of lighting conditions without the need for human calibration. The core TopCode library is 100% Java (with a C++ port now available). An additional library is provided to grab high-resolution images from a webcam using Microsoft's DirectShow API. This library is written in C++ but contains native hooks to Java.


  • Free and open source
  • Fast and accurate
  • 100% Java
  • Will work in a variety of lighting conditions
  • Can recognize up to 99 unique codes in a single image.


  • The camera must be orthogonal to the interaction surface.
  • Requires Java programming knowledge


Quick Start Guide

To get started with the TopCode library:
  1. Download and install the Java JDK (

  2. Extract the TopCode library on your local machine.

  3. An easy way to get started is to use the TopCode debugger app. Start by opening a shell and changing to the directory where you installed the library. Then run this command:
    $ java -cp lib/topcodes.jar topcodes.DebugWindow
    This allows you to test the library on an image. If there are any JPEG images in your working directory, they will be loaded automatically. The basic key commands are:

    CTRL-o Open a JPEG file
    + Zoom in
    - Zoom out
    b See the image after thresholding
    t Show / hide topcode highlighting
    Page Up Load the next image in the directory
    Page Dn Load the previous image in the directory
    Clicking and dragging with the mouse will pan the image.

    All of the TopCode ID numbers will be printed on the command line each time an image is loaded.

  4. Another option is to run the webcam sample code. This is a sample application that integrates the webcam library with the TopCode scanner. (Note: this code will only work on windows machines). To run this sample, you will need a webcamera with VGA (640x480) resolution. A Logitech QuickCam is a good choice. Plug in your camera, and then use this command to launch the demo:
    $ java -cp lib/topcodes.jar WebCamSample

To Compile The Library

To compile the topcode library on your machine:
  1. If you want to be able to compile the library, download and install Apache Ant (

  2. To compile the library, open a shell and go do the directory where you extracted the library. Then run the ant build script:
    $ ant build
    After about 10 seconds, you should see a message that says BUILD SUCCESSFUL.

Other Links
Other computer vision libraries you might try:

  • ARToolKit from the HITLab at the University of Washington
  • reacTIVision from the Music Technology Group at Pompeu Fabra University in Barcelona
  • CanTag and TinyTag from the University of Cambridge in the U.K.

The TopCode library was developed at the Tufts University Human Computer Interaction Lab in Medford, Massachusetts. The library is based on TRIP from the University of Cambridge in the U.K. and on adaptive thresholding techniques developed by Pierre Wellner.

Comments & Feedback
Please send comments, suggestions, and bug fixes to Michael Horn (michael-horn <at> northwestern dot edu).