Node: Touch Mapper

From Waltz
Revision as of 17:23, 24 July 2019 by Patrick Angle (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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.

Nodes
Devices ArtNet Input · ArtNet Output · Interactive LED Processor · NDI™ Input · NDI™ Output · OSC Input · OSC Output · Projector · SensorLink · TCP · TUIO Output · UDP Input · UDP Output · Watchout Media Server
Objects LED Tile Layout · List · Map · Random Number · Simulated Touch · Timer · Value · Wave
Operators Blend · Change · Clip · Cluster Tracker · DMX Multiverse Merge · Ease · Filter · Hold · JSON Mapper · JSON Stringify · Logic · Math · Proximity · Range · Rotate · Scale · Shear · Smooth · Touch Mapper · Translate
Scenes External Scene · Material Scene
Materials Graph · Touch Material
Scripting Script Function · Script
Comments Comment