Processing TUIO Client API
Copyright (c) 2005-2009 Martin Kaltenbrunner. This software is part of reacTIVision, an open source fiducial tracking and multi-touch framework based on computer vision. For further information on the TUIO protocol and framework, please visit TUIO.org
Releases and Source Repository
The current version 1.4 has been optimized to work with Processing 1.0, and comes with this documentation, two example sketches as well as its source code. You will find this release, as well as further TUIO client packages on the reacTIVision software page.
This package contains two demo sketches and a library which allows Processing to receive TUIO messages from any TUIO enabled tracker. The TuioDemo sketch graphically displays the object and cursor states on the screen. You can use this demo as a starting point for the development of you own Processing sketch based on the TUIO framework. Please refer to the source code of the example and the following section for further details on its usage.
Keep in mind to make your graphics scalable for the varying screen and window resolutions. A reasonable TUIO application will run in fullscreen mode, although the windowed mode might be useful for debugging purposes or working with the TUIO Simulator.
Copy the complete contents of the distribution to a folder named TUIO to the libraries folder of your Processing sketchbook. In order to use this library, you will need to provide the according import statement within the header of your Processing sketch:
Application Programming Interface:
First you need to create an instance of the TuioProcessing client, providing the instance of your sketch to the constructor using the this argument. The TuioProcessing client immediately starts listening to incoming TUIO messages and generates higher level events based on the object and cursor movements.
TuioProcessing tuioClient = new TuioProcessing(this);
Therefore your sketch needs to implement the following methods in order to be able to receive these TUIO events properly:
- addTuioObject(TuioObject tobj) this is called when an object becomes visible
- removeTuioObject(TuioObject tobj) an object was removed from the table
- updateTuioObject(TuioObject tobj) an object was moved on the table surface
- addTuioCursor(TuioCursor tcur) this is called when a new cursor is detected
- removeTuioCursor(TuioCursor tcur) a cursor was removed from the table
- updateTuioCursor(TuioCursor tcur) a cursor was moving on the table surface
- refresh(TuioTime bundleTime)
this method is called after each bundle,
use it to repaint your screen for example
Each TuioObject or TuioCursor is identified with a unique SessionID, which it maintains over its lifetime. Additionally each TuioObject carries a SymbolID that corresponds to its attached fiducial marker number. The CursorID of the TuioCursor is always a number in the range of all currently detected cursors. You can retrieve these ID numbers with the according getSessionID(), getSymbolID() or getCursorID() methods.
The TuioObject and TuioCursor references are updated automatically by the TuioProcessing client and are always referencing the same instance over the object's or cursor's lifetime. All the TuioObject and TuioCursor attributes are encapsulated, and can be accessed with methods such as getX(), getY() and getAngle(). There exist further methods for the retrieval of speed and acceleration values, please see the provided example sketches for a complete list. TuioObject and TuioCursor also have some additional convenience methods for the calculation of distances and angles between objects. The getPath() method returns a Vector of TuioPoint representing the movement path of the object. Please refer to the documentation of the TUIO Java reference implementations for further details on all the available methods.
Alternatively, the TuioProcessing class contains some methods for the polling of the current object and cursor states. There are methods which return either a list or individual TuioObject and TuioCursor objects.
- getTuioObjects() returns a Vector of all currently present TuioObjects
- getTuioCursors() returns a Vector of all currently present TuioCursors
- getTuioObject(long s_id) returns a TuioObject or NULL depending on its presence
- getTuioCursor(long s_id) returns a TuioCursor or NULL depending on its presence
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA02111-1307USA