====== TUIO Protocol ======

===== Definition =====


//(from [[http://www.tuio.org/]])//

<blockquote>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 [[http://www.iua.upf.edu/mtg/reacTable/|reacTable]], being developed in Barcelona and the tDesk from [[http://www.techfak.uni-bielefeld.de/ags/ni|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 [[http://www.opensoundcontrol.org/|OpenSound Control]] and is therefore usable on any platform supporting this protocol.
</blockquote>

(image courtesy of [[http://reactable.iua.upf.edu/|Xavier Sibecas]])

{{ :manual:cover.jpg |The reacTable, powered by reacTIVision}}

While the reacTable doesn't use OSCulator, it is possible to use the video pattern recognition software [[http://reactable.iua.upf.edu/?software|reacTIVision]] with OSCulator very easily.


===== TUIO enabled software =====

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

  * [[http://lux.vu/blog/oscemote/|OSCemote]] is a fine multi-touch surface controller software for the iPhone developped by Joshua Minor ;
  * [[http://reactable.iua.upf.edu/?software|reacTIVision]]: the reacTable computer vision framework with a complete TUIO implementation ;
  * [[http://www.nuigroup.com/touchlib/|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.

{{ :manual:reactivision02.png |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 window((remember, the messages are interpreted, not displayed in the raw TUIO format)).  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]

and

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

for corresponding activity messages.

Note: Positional and Activity messages always come in pair.


==== Arguments ====

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:
    - x: x position
    - y: y position
    - vx: speed of x axis
    - vy: speed of y axis
    - a: motion acceleration
  * For 2D objects:
    - x: x position
    - y: y position
    - rz: orientation (angle of rotation around z axis)((''0'' is 0 radians, and ''1'' is 2π radians))
    - vx: speed of x axis
    - vy: speed of y axis
    - vrz: speed of rotation
    - a: motion acceleration
    - arz: rotation acceleration

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