T3D version 1.0
November 2013

I made a very simple format named t3d (for touch-3d) for Soundplane messages in Open Sound Control format. Open Sound Control (OSC) is an open, transport-independent, message-based protocol developed for communication among computers, sound synthesizers, and other multimedia devices. See opensoundcontrol.org for more info.

A source of t3d data transmits t3d frames over OSC. 

Each t3d frame consists of an OSC containing a frame message followed by 0 or more touch messages.

OSC Bundle (time)
	/t3d/frm 
	/t3d/tch 
	/t3d/tch 
	/t3d/tch 
	(...)
End OSC Bundle

--

bundle:

The bundle contains a 64-bit timestamp in microseconds as decsribed in the OSC specification. All touch data within the bundle is defined to have occurred at this time. This information can optionally be used to reduce jitter in a t3d stream.

--

frame message:
/t3d/frm (int)frameID (int)deviceID

The frame message describes the incoming frame. In the current Soundplane application, frames are sent at a user-controllable data rate, with the exception that when new touches are detected, a new frame message is sent as soon as possible. The data rate is typically from 100-500Hz.

frameID is a counter that increments for each frame of data sent by the Soundplane. Because an extra frame is sent when a touch is detected, it may increment at a varying rate.

deviceID contains a 16-bit instrument model ID followed by a 16 bit serial number.

--

touch:
t3d/tch[n] (float)x, (float)y, (float)z, (float)note

The touch message describes a single touch currently active. If no touches are active, there will be no touch messages sent in between the frame and alive messages.

n is an integer suffix on the "t3d/tch" string itself. It is the touch number from 1-16.
x is the absolute x location from 0.-1.
y is the absolute y location from 0.-1.
z is the z (force) value from 0.-1.
note is a floating point value. The Soundplane software has a utility to map from areas on the surface to zones, which may play notes. Soundplane assumes that clients will have ways for the player to select a note to frequency map, or scale. To provide only an equal-tempered A440 scale a fixed mapping can be used where frequency = 440.0 * 2^((note-69.0)/12.) .

--

NOTE: over a UDP connection it is possible that packet loss may cause touches to become stuck on. In past versions of t3d software this was handled with a special "alv" message. However in practice stuck touches have not been a problem, and so the extra data does not seem necessary. Since an active touch will send a continuous stream of data, a sound application can look for touches that have stopped sending data for a given time, say 250 ms, and turn them off if necessary.