User Tools

Site Tools


TUIO Protocol



TUIO is a simple yet versatile protocol designed specifically to meet the requirements of table-top tangible user interfaces. Inspired by the idea of interconnecting various existing table interfaces such as the reacTable, being developed in Barcelona and the tDesk from Bielefeld University, this protocol defines common properties of controller objects on the table surface as well as of finger and hand gestures performed by the user.

Currently this protocol has been implemented within a fiducial marker-based computer vision engine developed for the reacTable project. The Tuio protocol has been implemented using OpenSound Control and is therefore usable on any platform supporting this protocol.

(image courtesy of Xavier Sibecas)

The reacTable, powered by reacTIVision

While the reacTable doesn't use OSCulator, it is possible to use the video pattern recognition software reacTIVision with OSCulator very easily.

TUIO enabled software

Here is a non exhaustive list of softwares using the TUIO protocol:

  • OSCemote is a fine multi-touch surface controller software for the iPhone developped by Joshua Minor ;
  • reacTIVision: the reacTable computer vision framework with a complete TUIO implementation ;
  • Touchlib is a library for creating multi-touch interaction surfaces.

TUIO and OSCulator

TUIO is a very versatile protocol. Being flexible and rich in its expression, it is also a bit complicated to handle.

OSCulator has been designed to be easy and rather intuitive to use, but is not really compatible with TUIO without some modifications. Sending raw TUIO messages to OSCulator wouldn't be really useful.

This is why OSCulator includes an interpreter that rewrites and give an easy to learn structure to TUIO events.

Interpreted TUIO messages

The TUIO protocol keeps tracks of Cursors and Objects.

  • Cursor are used to track the position and speed of a pointer, a finger for example ;
  • Objects, are used to track the position, orientation and speed of fiducial markers.

Fiducial Markers example

reacTIVision Setup

There is not much to do than launch the reacTIVision program. This application send OSC message to port 3333 on the local host by default, this means that you will need to change the OSC Input Port in OSCulator to 3333.

Messages definition

As soon as OSCulator receives TUIO messages, it will display them in the main window1). Those messages always come in pair:

  • the message carrying position, orientation and speed informations, for example /tuio/2D/obj/1 ;
  • and the message carrying activity information, for example /tuio/2D/obj/1/activity. This messages tells if the object is visible or not. When visible, a float value of 1.0 is sent, on the contrary, the value is 0.0.

The positional messages have the following format:

/tuio/{2D,3D}/{cur,obj}/[id number]


/tuio/{2D,3D}/{cur,obj}/[id number]/activity

for corresponding activity messages.

Note: Positional and Activity messages always come in pair.


Activity message have only one argument, the activity, being 0 (not visible or not active) or 1 (visible or active).

Positional message have the following arguments:

  • For 2D cursors:
    1. x: x position
    2. y: y position
    3. vx: speed of x axis
    4. vy: speed of y axis
    5. a: motion acceleration
  • For 2D objects:
    1. x: x position
    2. y: y position
    3. rz: orientation (angle of rotation around z axis)2)
    4. vx: speed of x axis
    5. vy: speed of y axis
    6. vrz: speed of rotation
    7. a: motion acceleration
    8. arz: rotation acceleration

These are basically the same arguments as given by the TUIO protocol for set messages.

remember, the messages are interpreted, not displayed in the raw TUIO format
0 is 0 radians, and 1 is 2π radians
manual/tuio_protocol.txt · Last modified: 2009/06/09 12:26 by camille