Tech Note: Handling Touch Data in Touch Designer

Waltz provides multiple paths for your custom application to receive touch data from any interactive surface supported in Waltz, including interactive LED floors. TouchDesigner is a great solution for creating generative content, being designed for that exact task. For disguise media servers, including display of Notch content, see Handling Touch Data in disguise and Notch. For custom application projects, see Handling Touch Data in Custom Applications.

There are two different ways to handle touch data. The first, TUIO, already has a purpose-built DAT in TouchDesigner that can be utilized to process the interactive data. The second, OSC, can be processed by creating your own network of DATs and OPs, or by using our purpose-built TOX, which allows you to quickly get a DAT containing only active touches, from which you can begin implementing your application's logic.

Using TUIO to Handle Touch Data

TUIO is a protocol for communicating user interaction data like touches, object positions, and more over the network. TUIO is based on the OSC protocol, but defines the specific messages that are permitted. Waltz utilizes the 2dcur part of the TUIO specification to send information about touch data to remote machines as cursor events.

In TouchDesigner

Create a new TUIO In DAT, and configure the port to match that to which Waltz is sending TUIO data (or vice-versa by changing the port in Waltz to match that is TouchDesigner). Waltz sends 2dcur messages, and as such will provide a u, v, velocityX, and velocityY to TouchDesigner. You may need to enable the Velocity option in the Columns section of the parameters for the DAT in order to see the velocity data. For more information about the TUIO In DAT in TouchDesigner, refer to the applicable TouchDesigner documentation.

In Waltz

Use a TUIO 2D Cursor Output node, which takes a List<Touch> data, and provides those touches over the network as TUIO. The remote address should be configured to either point to specific machine you wish to receive TUIO, or a broadcast address for a group of machines to receive TUIO. The normalization dimensions should match the maximum range of touch data from the source of the touches. For LED floors, this will be the total pixel dimensions of the floor.

Using OSC to Handle Touch Data using the Waltz Touch In TOX

OSC is a general-purpose protocol for transmitting show data over the network. Waltz is able to provide touch data over OSC through a combination of its Touch Mapper node and its OSC Output node. The Touch Mapper node creates the structured data from touches that will then be sent by the OSC Output node, without the need to manually map each piece of data for transmission.

In TouchDesigner, a custom TOX is used to process this information so that the TouchDesigner artist is presented with a clean table of active touch information.

Download the Waltz Touch In TOX

In TouchDesigner

Download the Waltz Touch In TOX (linked above), and add it to your network. The custom TOX has the following parameters for you to configure…

Parameter	Type	Description	Default
OSC Port	Int	The port over which OSC data from Waltz is expected. This should match the remoteAddress port of the corresponding OSC Output node in Waltz.	7001
Number of Touches	Int	The maximum number of touches that will be received. This should match the fixedNumberToMap of the corresponding Touch Mapper node in Waltz. If these numbers do not match, you may not see all available touches, or you may see duplicates of available touches.	10
OSC Address Scope	String	The scope of an OSC address path that defines a touch from Waltz. The default is designed to be forgiving, but in some cases it may be necessary to provide a more specific scope, like /waltz/osc/touch* to prevent extra data from being received if more than just touches are expected. The scope should be such that it filters out extra parameters like count and heartbeat, hence the default value.	*/touch*
Reset	Momentary	Clears any state touch data. This is necessary if you decrease the number of touches, or if you are no longer receiving new touch data.

The TOX will act as a DAT with the following labeled columns…

Column	Description
sequentialId	A unique ID for this touch. Each touch gets a sequential, increasing, number. The first touch is always 1.
uuid	A unique ID for this touch, separate from the sequentialId. This number is a derived from the UUID Waltz creates for each touch, and is converted to an unsigned integer.
isAlive	Always equals 1 if the touch is believed to be active, otherwise this value is 0. Because this TOX only every shows active touches, this value will always be 1.
currentX	The current x position of the touch. This argument is either an integer representing absolute pixels, or a float between 0.0 and 1.0. This is dependent on whether normalizePosition in the corresponding Touch Mapper node is enabled.
currentY	The current y position of the touch. This argument is either an integer representing absolute pixels, or a float between 0.0 and 1.0. This is dependent on whether normalizePosition in the corresponding Touch Mapper node is enabled.
initialX	The initial x position of the touch. This argument is either an integer representing absolute pixels, or a float between 0.0 and 1.0. This is dependent on whether normalizePosition in the corresponding Touch Mapper node is enabled.
initialY	The initial y position of the touch. This argument is either an integer representing absolute pixels, or a float between 0.0 and 1.0. This is dependent on whether normalizePosition in the corresponding Touch Mapper node is enabled.
radius	The calculated radius of the touch, in pixels.
creationMillis	The time, in milliseconds, at which the touch was created.
lastUpdatedMillis	The time, in milliseconds, at which the touch was last updated to reflect a change in position, radius, or continued existence.
ageMillis	The ago of the touch, in milliseconds.

In Waltz

Use a Touch Mapper node, which accepts a List<Touch> and provides a Map of information ready to be sent over OSC with an OSC Output node. The remote address should be configured to either point to specific machine you wish to receive the OSC, or a broadcast address for a group of machines to receive the OSC. Keep in mind that both nodes contain settings that can affect the format of the OSC data being transmitted.

The Touch Mapper should be configured such that the fixedNumberToMap value matches the Number of Touches defined on the TOX in TouchDesigner. Additionally, you must enabled the mapFixedNumber, maskDeadTouches, and combineTouchArgumentsIntoList by setting their values to true in order for the Waltz Touch In TOX to be able to accept the touch data.