Node: Touch Mapper

The Touch Mapper node supports converting a List of Touches into a Map of information, ready to be further processed or sent to a remote device using a OSC Output Node or similar output node. The Touch Mapper node has several specific advantages over using a normal Map or using a Map Node to create similar output, including built in state tracking, keeping touches in order, sending a fixed number of touches, combining touch arguments into a list for some receivers, and more.

Settings

	Expected Type	Details	Default
touches	List<Touch>	The Touch or List of Touches that should be turned into a map of information.
keyPrefix	String	The prefix to prepend to the beginning of each touch-related key in the resulting touchMap.	"touch"
keySufix	String	The suffix to append to the end of each touch-related key in the resulting touchMap.	""
normalizePosition	Boolean	When position normalization is enabled, all x and y coordinates of Touches are given in the range of 0.0 to 1.0, and are relative to the normalizePositionBounds.	true
normalizePositionBounds	Dimension	The dimensions in which to calculate the normalized position of Touches. Touches outside these bounds have positions less than 0.0 or greater than 1.0. This value is unused if normalizePosition is false.	Dimension(1920.0, 1080.0)
useEpochTime	Boolean	When enabled, times are provided in Epoch time modulo the maximum value of a 32-bit integer. When disabled, time is reported relative to the time at which the current show file was opened.	false
mapFixedNumber	Boolean	When enabled, a fixed number of Touches will appear in the touchMap. Any touches beyond the count defined by fixedNumberToMap will be ignored. This is useful if you have to hard-wire touches to objects in your workflow, and will only support an arbitrarily limited number of touches. This is common with disguise or Notch based workflows. This option must be enabled if you wish for a touch to maintain its numbered slot for its entire lifespan.	false
fixedNumberToMap	Number	The number of Touches that will appear in the touchMap is mapFixedNumber is true. If there are fewer touches available in the input touches than requested, empty touches marked as dead are provided in their stead.	10
maskDeadTouches	Boolean	When enabled, all available touches will be mapped, along with the necessary number of empty touches marked as dead to mask out the maximum number of touches ever included in the touchMap.	true
combineTouchArgumentsIntoList	Boolean	When enabled, all arguments for each touch are combined into a list under a single keyed entry in the touchMap instead of each argument being mapped to a separate key. This mode provides less context for the information of each touch, but when the touchMap is used as the input to an OSC Output Node each touch will be sent as a single message with multiple arguments instead of a message per argument.	false

Parameters

	Type	Details
touchMap	Map<Any>	Note: The parameter is read-only. The Map of touches, ready to be sent via OSC or otherwise processed.

Output Over OSC

Many aspects of the data being sent from Waltz are customizable and may differ slightly from show to show based on how the applicable nodes have been configured. For the most part, this section outlines the output when options are set to their default. Exceptions to that are noted within.

By default, an OSC message is sent as part of the OSC bundle for each touch that currently exists. Each message will have a unique OSC path, with a number on the end indicating which touch it is. If in a frame there are 8 touches active, these touches will be numbered 1 through 8. These numbers do not correlate to the sequentialId of the touch. A touch may have a different OSC path number every frame. Each of these messages will contain 11 arguments, defined as follows:

OSC Path: waltz/osc/touch1
#	Name	Type	Details
0	sequentialId	Integer	A unique ID for this touch. Each touch get a sequential, increasing, number. The first touch is always 1.
1	uuid	Integer	A unique ID for this touch, separate from the sequentialId. This number is a randomly generated unsigned integer.
2	isAlive	Integer	Always equals 1 if the touch is believed to be active, otherwise this value is 0. Dead touches only ever appear in a message if this node is configured with mapFixedNumber or maskDeadTouches enabled.
3	currentX	Float or Integer	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 is enabled.
4	currentY	Float or Integer	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 is enabled.
5	initialX	Float or Integer	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 is enabled.
6	initialY	Float or Integer	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 is enabled.
7	radius	Integer	The calculated radius of the touch, in pixels.
8	creationMillis	Integer	The time, in milliseconds, at which the touch was created. See the heartbeat message for the current time.
9	lastUpdatedMillis	Integer	The time, in milliseconds, at which the touch was last updated to reflect a change in position, radius, or continued existence. See the heartbeat message for the current time.
10	ageMillis	Integer	The age of the touch, in milliseconds.

Additionally, two other messages are sent, one with the current time and one with the number of touches to be expected in the current frame. These messages are formatted as follows:

OSC Path: waltz/osc/heartbeat
#	Name	Type	Details
0	heartbeat	Integer	The current time, in milliseconds. This number will either be relative to the opening of the current show file, or relative to Epoch time, depending on whether useEpochTime is enabled. Should the need arise, this number will loop around to 0 after reaching the maximum value for an integer, which would occur after 49 days of continuous operation. For long-term installations it is recommended that this situation be handled gracefully by the receiver of this data.

OSC Path: waltz/osc/count
#	Name	Type	Details
0	count	Integer	The number of touches being sent in the current frame. This number will be 0 if no touches are currently being sent.

Functions

There are no functions exposed by this node.

Example Usage

No examples provided.