fiducial_exampleThe TUIO library is able to receive and parse data following the TUIO protocol by the Music Technology Group, ‘which was specially designed for transmitting the state of tangible objects and multi-touch control on a table surface.’


download (8.1KB)
Version: 0.1 (initial release)
Licensed under the MIT License
Author: Jannis Leidel


Sample fiducial (Nr. 10)


In order to use this library you need to have the cross-plattform reacTIVision application that does the heavy lifting of tracking the tangible objects, so-called fiducials. It transmits the received data (e.g. positional information) as OSC messages via an UDP socket to your client software which uses this library.


Basic use

To use this library in general you should follow these steps:

1. Get a camera or webcam, like iSight, Quickcam, etc., install its drivers if necessary, try it with the reacTIVision software. Print the fiducials to attach them to objects.

2. Look at the examples to get started.

3. Build the tangible interface, table, stage, vehicle, game, whatever.

4. Combine it with Blender, Pygame or Nodebox

5. Use the source, Luke.

The Tracking class

The Tracking class should be used to initialize a socket connection for receiving the OSC messages from reacTIVision. It handles all incoming data and calls the appropriate functions, depending on the type of message.

When started it loads every possible profile from the profiles submodule and initializes a callback manager from the OSC module.

A simple example can be found in the examples directory in

1. Import it:

tuio = ximport("tuio")

2. Setup the tracking program:

def setup():
    global tracking
    tracking = tuio.Tracking()

3. Setup the main loop and draw all recognized object and rotate them accordingly:

def draw():
    global tracking
    for obj in tracking.objects():
        x = obj.xpos * WIDTH
        y = obj.ypos * HEIGHT
        rect(x, y, 20, 20)
        text(obj, x, y)

a) You need to update the tracking information on each loop manually.

b) Access the tracked objects by using one of the helper function that return a list of these objects.

c) Stop the tracking manually on every exception to prevent socket errors

4. Stop the tracking when Nodebox stops the program.

def stop():
    global tracking

While holding two fiducials in front of the camera the visual output of this script was, for example:


The described script can also be found in the distribution of pyTUIO.

The objects submodule

The objects submodule contains a series of classes that represent types of tangible objects. They all are subclasses of the also included objects.TuioObject. The following object types are defined at the moment:

Tuio2DCursor - An abstract cursor object, e.g. a finger. This object has limited information and is only sent by reacTIVision if the smallest possible fiducial marker was found: a point. In combination with a tangible table this can also be achieved by using fingers on the table surface.

It has the following attributes:

Tuio2DObject - An abstract object representing a fiducial. This object has detailed information about its state and is sent by reacTIVision if a fiducial was recognized.

It has the following attributes:

The TUIO protocol provides even more possible object types, depending on the purpose of the intactive surface, e.g.:

But these profiles are left to be implemented by the user. Just have a look in and and subclass the base classes there.

The profiles submodule

The profiles submodule contains a number of abstract descriptions of what should happen if a certain object type is used. Depending on the desirable tangible object attributes you can customize the profiles for your own need.

For example, if you want to receive the data for a 2D tracking object you need to use the according profile, because it knows how to handle the dataset of this type of object.

Every profile subclasses from a TuioProfile base class that has the following required methods whose names originate from the name of the raw OSC message:

Other methods and attributes are:

The OSC submodule

This submodule does most of the heavy lifting of decoding the OSC messages used in the TUIO protocol and provides a convenient CallbackManager. It was written by Daniel Holth and Clinton McChesney.

Learn more about OSC at

What happens next?

This library should be the start of lecturing about tangible interfaces in combination with the ease of use of the Python programming language.

Feel free to contact the Author Jannis Leidel to get to know more about tangible user interfaces, integration into Pygame and future features.

You can of course use the issue tracking service of the pyTUIO Google Code project site to ask for new features, report bugs or become a project member.