Configuring input mapping

After the rendering of the application is configured correctly, the last step is to configure how touch input is mapped to the application. Configuring input mapping happens in config.txt.

In this file, we can configure one or more input sources and how they are mapped to the graphics coordinates we set up previously. Three different types of input sources are supported: NetBridge for MultiTaction displays, TUIO for any device supporting TUIO 1.1 protocol, or NativeTouch to support touch events from the operating system. You can combine multiple different input sources at the same time.

Hint

See video-wall-examples for some common configurations that you can use as a starting point.

Configuring NetBridge sources

To receive touch events from MultiTaction displays, use one NetBridge block per device:

NetBridge {
    host = "10.77.84.100"
    port = "5502"

    /* Input transformations */
    input-translate = "0 0"
    input-rotate = "0"
    input-scale = "1 1"
}

Each block defines the address and port of the MultiTaction display to connect to. Each device sends its coordinates in the FullHD range (0,0 to 1920,1080). To specify how the input is mapped to the graphics coordinates defined in screen.xml, use the input-translate, input-rotate and input-scale parameters.

NetBridge block parameters

host

: Address of the MultiTaction display (or other NetBridge source) to connect to for receiving input.

port

: Port to connect to (DEFAULT: 5502).

input-translate

: Offset in graphics coordinates to translate the received input (DEFAULT: \"0 0\").

input-rotate

: Rotation in degrees of the received input. The rotation is relative to the top-left corner (0, 0) of the input, so if you adjust rotation you most likely need to adjust input-translate as well to compensate (DEFAULT: \"0\").

input-scale

: Scaling of the received input in x and y dimensions (DEFAULT: \"1 1\").

NetBridge input transformations

Each NetBridge block allows you to specify translation, rotation, and scaling of received input. When working with landscape displays, you just set the input-translate parameter to match the location of the display in graphics coordinates.

With portrait displays it is more complex. Rotation is applied first, followed by translation. Rotation happens around the top-left corner. So if you perform a 90 degree rotation counter-clockwise (MT557D, MT556), you need to translate the rotated coordinates down by 1920:

Example portrait rotation for MT557D

For clockwise rotations (MT555), you need to translate right by 1080:

Example portrait rotation for MT555

Configuring NativeTouch sources

In order to support native touch events from the operating system, at least one NativeTouch block must exist in config.txt. The simplest way to do this is to just add an empty block to the file:

NativeTouch {}

This minimal configuration assumes touch devices to have been properly configured and calibrated on the operating system's desktop. No extra processing is done on the received input. This is the most typical scenario.

NativeTouch parameters

digitizer-id

: Platform-specific ID to identify the physical device (see input-mapping-multiple).

size

: Size of the output rectangle in desktop coordinates.

offset

: Location of the output rectangle in desktop coordinates.

rotation

: Clockwise rotation in degrees.

filter-strength

: Smoothing filter strength for the device touch points. Normally this can be zero (no filtering), but with certain devices with low resolution or noisy touch data this can be increased up to 1.0. Higher values will give smoother movement but will also add more latency.

map

: Apply one or more transformations to input coordinates by mapping rectangular areas (see input-mapping-map).

Global NativeTouch parameters

In addition to device-specific parameters you can also adjust the default filter-strength parameter:

NativeTouch {
    filter-strength = "0.5"
}

Multiple NativeTouch sources (Windows only)

If you have multiple touch devices connected and want to perform additional processing on the received coordinates, you can specify multiple NativeTouch blocks in config.txt and also define how their input is transformed before feeding it to the application.

Note

Multiple NativeTouch blocks are only supported on Windows.

Easiest way to do this is to start Canvus with an empty NativeTouch block in config.txt and then proceed to touch each touch screen in order. When Canvus receives the first event from an unconfigured touch device, it prints a sample configuration for that device in the log, for instance:

NativeTouch: New touch digitizer ES551028217 found with max 12 contact points, cfg:

NativeTouch {
    digitizer-id = "HID\VID_1EF1&PID_0057&MI_00&COL03\7&1B2DCA1D&0&0002"
    size = "3840 2160"
    offset = "0 0"
}

After touching all displays, replace the empty NativeTouch block in config.txt with the generated NativeTouch blocks from the log file and adjust the size and offset -parameters to match the digitizer desktop coordinates. For instance, two 4K screens next to each other both have size = \"3840 2160\", but the screen on the left has offset = \"0 0\" and the one on the right has offset = \"3840 2160\".

Complex input transformations

If you need to perform complex transformations for input, it can be done using map sections. Each map section takes all input inside a specific rectangle and transforms the input so it maps to a different rectangle. You can use multiple map sections to transform more complex transformations.

This can be useful with certain hardware combinations where IR frames and Nvidia Mosaic are used at the same time.

NativeTouch {
    map {
        input-offset = "0 0"
        input-size = "960 1080"
        output-offset = "0 0"
        output-size = "3840 2160"
        output-rotation = 0
    }
    map {
        input-offset = "960 0"
        input-size = "960 1080"
        output-offset = "3840 0"
        output-size = "1920 1080"
        output-rotation = 0
    }
}

Map section parameters

input-offset

: Offset of the input rectangle in desktop coordinates.

input-size

: Size of the input rectangle in desktop coordinates.

output-offset

: Offset of the output coordinates in desktop coordinates.

output-size

: Size of the output rectangle in desktop coordinates.

output-rotation

: Rotation applied to output coordinates in degrees.

Configuring TUIO sources

To receive input from a TUIO touch device, one or more TUIOTracker blocks can be configured:

TUIOTracker {
    /* Accept connections from all hosts */
    host = "0.0.0.0"
    /* Local UDP port to listen */
    port = "3333"

    /* TUIO sends the data in relative coordinates, all coordinates are between 0 and 1.
        This specifies the resolution the input data must be scaled to.
        By default this is detected from the active screen.xml config. */
    /*input-resolution = "1920 1080"*/

    input-translate = "0 0"
    input-rotate = "0"
    input-scale = "1 1"
}

With TUIO, the touch device will send UDP packets to a specified port (default 3333). All coordinates in TUIO protocol are normalized between 0 and 1. You can perform additional processing on the received normalized coordinates to map them to the graphics coordinates defined in screen.xml.

If you want to receive input from multiple different TUIO devices, you can configure multiple TUIOTracker blocks, each listening on a different port. For example, ports 3333, 3334, 3335, etc. Each TUIOTracker on a different port can then define its own mapping of the input coordinates.