Includes Aiptek, Hanwang, N-trig, Wacom, Waltop, & WizardPen (Ace Cad, KYE Systems, UC-LOGIC) Tablets

Last updated: September 19, 2012

Preliminaries

1) You must have X server 1.8 or up (Julia/Maverick has 1.9).

Sources

"xsetwacom: Support MapToOutput for TwinView" by Jason Gerecke

"xsetwacom: add "MapToOutput" parameters" by Peter Hutterer

"dix: add 3x3 transformation matrix xinput property for multi-head handling" by Peter Korsgaard

xf86-input-wacom from part II of the Wacom Bamboo Pen and Touch tablet HOW TO or section 2 of the Linux Wacom HOW TO.

"man xrandr"

"Transformation matrix"

"Matrix multiplication"

Miscellaneous Notes

First Wacom testers to report success were dsavi & mugginz.

First WizardPen (Genius MousePen 8x6/UC-LOGIC) testers to report success were elnaureth & 1script.

Summary

This HOW TO is divided into three sections. The first is the xsetwacom MapToOutput Method for tablets on the Wacom drivers. MapToOutput has been extended to apply to the Nvidia proprietary driver, i.e. TwinView starting with the xf86-input-wacom-0.12.0 release. The second is the Coordinate Transformation Matrix Method which works for all tablets. The third deals with getting either method to work through a reboot. Tablet PC rotation with CTM is in appendix 1.

Note: There is a X Server bug that prevents CTM from working correctly with xf86-input-evdev. If you apply a CTM to a input tool that uses xf86-input-evdev the associated cursor jumps around. Spurious lines are drawn in Gimp, Inkscape, etc. This is fixed in X Server 1.13.0. See Bugzilla Bug 49347. It's not clear which X Server version this bug first appeared in although it appears to affect at least the 1.11, 1.12 (Maya/Precise), and probably the 1.10 series.

I. xsetwacom MapToOutput Method - for Tablets using the xf86-input-wacom driver: Hanwang, N-trig, Wacom, & Waltop

The nice thing about MapToOutput is it does all of the matrix calculations for you automatically.

1) You must have xf86-input-wacom 0.10.9 (0.10.8+ after the 8-11-10 commit "xsetwacom: add "MapToOutput" parameters."; the default in Maverick is 0.10-8 ) if you have a 32-bit install. Otherwise if you have a 64-bit install you must have xf86-input-wacom 0.10.10+ (after the 1-11-11 commit "xsetwacom: fix 64-bit issues with MapToOutput").

First determine the "device name" of what you want bound on a specific screen. Your choices will be the stylus, eraser, or cursor (Wacom tablet mouse). In a terminal enter:

- Code: Select all
`xinput --list`

The output should contain the "device names" you are after. For example for the stylus it might be:

"Wacom BambooFun 2FG 6x8 Pen stylus"

Quotes added because you'll need them.

The new method relies on a new xsetwacom command in the form:

xsetwacom set <device name> MapToOutput VGA1

Enter in a terminal:

- Code: Select all
`xrandr`

and select the name of the monitor, among the monitors you see in the output, that you would like the device on. Substitute that monitor name for VGA1 in the command. Using your "device name" (in quotes) from 'xinput list' you can now use the xsetwacom command:

- Code: Select all
`xsetwacom set "device name" MapToOutput VGA1`

2) TwinView (NVidia proprietary driver binary). Support was added with the "xsetwacom: Support MapToOutput for TwinView" commit on 6-23-11 (in the 0.11.99+ tree) and is available in the xf86-input-wacom-0.12.0 release tar.

Choose the monitor you want the input tool on using "HEAD-0", "HEAD-1", etc., e.g.:

- Code: Select all
`xsetwacom set "device name" MapToOutput HEAD-0`

or

xsetwacom set "device name" MapToOutput HEAD-1

Note: the above MapToOutput commands only apply to the current xrandr configuration, they will need to be re-applied with a restart (or rotation). So you'll have to set up the xsetwacom MapToOutput command(s) in a startup script. See below.

II. Coordinate Transformation Matrix Method - for all Tablets

While the following may seem a little daunting if you look at the examples you'll find it is not that hard. The code does the matrix multiplication for you. You are determining the matrix values by solving fractions involving your monitors' dimensions.

First determine the "Device name" of what you want bound on a specific screen. Your choices will be the stylus, eraser, or cursor (Wacom tablet mouse). In a terminal enter:

- Code: Select all
`xinput --list`

Using the "Device name" (in quotes) enter in a terminal:

- Code: Select all
`xinput list-props "Device Name"`

For example:

- Code: Select all
`xinput list-props "Wacom BambooFun 2FG 6x8 Pen stylus"`

This will give an output that contains your current 'Coordinate Transformation Matrix' for the device as the X server sees it:

- Code: Select all
`Coordinate Transformation Matrix (123): 1.000000, 0.000000, 0.000000, 0.000000, 1.000000, 0.000000, 0.000000, 0.000000, 1.000000`

Now let's do a quick overview of the math involved. Notice that while it is an Identity matrix:

- Code: Select all
`[ 1 0 0 ]`

[ 0 1 0 ]

[ 0 0 1 ]

which has the effect of multiplying by 1, or in other words no transformation, the addition of a third vector value (beyond X & Y) makes it an affine transformation with homogeneous coordinates. We need to determine the transform matrix appropriate to the monitor you want to place the device on.

What we will do with the transform is translate the currently assigned pixel coordinate vector X,Y of your tablet device to a new pixel coordinate vector X',Y'.

The numbers in the X server "Coordinate Transformation Matrix" are a 3x3 matrix read out row by row. Using an affine transformation means translation can be expressed with matrix multiplication. The equation we are looking at is in the form of:

- Code: Select all
`[ x' ] [ c0 c1 c2 ] [ x ]`

[ y' ] = [ c3 c4 c5 ] * [ y ]

[ 1 ] [ c6 c7 c8 ] [ w ]

The third vector value w (the row) 0 0 1, with c8 or w always equal to 1, is what makes it affine.

The associated linear equations would be:

- Code: Select all
`x' = (c0x + c1y + c2) / w'`

y' = (c3x + c4y + c5) / w'

w' = (c6x + c7y + c8) = 1

So c0 and c4 corresponds to the scaling on the X and Y axes, c2 and c5 corresponds to the translation (X & Y offsets) on those axes, and c6, c7, and c8 are always 0, 0 and 1.

Rumtscho describes how to calculate the general case in [url="http://ubuntuforums.org/showpost.php?p=10330180&postcount=8"]post #8[/url].

I. Dual Monitors

a) Two monitors with the same resolution: is the simplest case.

Say both monitors are 1280x1024. You first set up the linear transform (matrix) like so.

- Code: Select all
`left: right:`

[ 1280/(1280+1280) 0 0 ] [ 1280/(1280+1280) 0 1280/(1280+1280)]

[ 0 1024/1024 0 ] [ 0 1024/1024 0 ]

[ 0 0 1 ] [ 0 0 1 ]

Using fractions amounts to scaling from 0-1 so you end up with the following.

- Code: Select all
`left: right:`

[ 0.5 0 0 ] [ 0.5 0 0.5 ]

[ 0 1 0 ] [ 0 1 0 ]

[ 0 0 1 ] [ 0 0 1 ]

With the c2 = 0.5 on the right matrix being the x offset.

Now that you've determined the transform use the appropriate xinput command for the monitor you want your device on:

Left monitor:

- Code: Select all
`xinput set-prop "Device name" --type=float "Coordinate Transformation Matrix" 0.5 0 0 0 1 0 0 0 1`

Right monitor:

- Code: Select all
`xinput set-prop "Device name" --type=float "Coordinate Transformation Matrix" 0.5 0 0.5 0 1 0 0 0 1`

b) Two monitors with different resolutions: example by Rumtscho

* image courtesy of Rumtscho

Setting up the linear transform (matrix).

- Code: Select all
`left: right:`

[ 1280/(1280+2560) 0 0 ] [ 2560/(1280+2560) 0 1280/(1280+2560)]

[ 0 1024/1440 0 ] [ 0 1440/1440 0 ]

[ 0 0 1 ] [ 0 0 1 ]

Since for Rumtscho 'xinput --list' returned the stylus "Device name" as "Wacom BambooFun 2FG 6x8 Pen stylus" the appropriate xinput commands for device placement on the monitors are:

Left monitor:

- Code: Select all
`xinput set-prop "Wacom BambooFun 2FG 6x8 Pen stylus" --type=float "Coordinate Transformation Matrix" 0.333333 0 0 0 .711111 0 0 0 1`

Right monitor:

- Code: Select all
`xinput set-prop "Wacom BambooFun 2FG 6x8 Pen stylus" --type=float "Coordinate Transformation Matrix" 0.666666 0 0.333333 0 1 0 0 0 1`

c) Two monitors with one rotated: example courtesy of lejono

Left monitor 1600x1200 & right monitor (tablet pc) 1280x800. Tablet pc in laptop mode.

- Code: Select all
`left: right:`

[ 1600/(1600+1280) 0 0 ] [ 1280/(1600+1280) 0 1600/(1600+1280)]

[ 0 1200/1200 0 ] [ 0 800/1200 0 ]

[ 0 0 1 ] [ 0 0 1 ]

Left monitor:

- Code: Select all
`xinput set-prop "Serial Wacom Tablet stylus" --type=float "Coordinate Transformation Matrix" 0.555555 0 0 0 1 0 0 0 1`

Right monitor:

- Code: Select all
`xinput set-prop "Serial Wacom Tablet stylus" --type=float "Coordinate Transformation Matrix" 0.444444 0 0.555555 0 0.666666 0 0 0 1`

* lejono established 6 decimal accuracy; matrices changed to reflect that

Now if we rotate to tablet mode we are adding a rotational transformation. Let's use rotation by an angle A counter-clockwise about the origin. The functional form would be x' = xcosA − ysinA and y' = xsinA + ycosA but we want to make it affine so we can use multiplication. And we need to add it to the current matrix. So written in matrix form, it becomes something like:

- Code: Select all
`[ x' ] [ cosA*c0 -sinA*c1 c2 ] [ x ]`

[ y' ] = [ sinA*c3 cosA*c4 c5 ] * [ y ]

[ 1 ] [ c6 c7 c8 ] [ w ]

representing the equations:

- Code: Select all
`x' = (cosA*c0x + -sinA*c1y + c2) / w'`

y' = (sinA*c3x + cosA*c4y + c5) / w'

w' = (c6x + c7y + c8) = 1

If we rotate the tablet 180 degrees to inverted, since cos(180) = -1 and sin(180) = 0 you end up with:

- Code: Select all
`right:`

[ -1280/(1600+1280) 0 1280/1280 ]

[ 0 -800/1200 800/1200 ]

[ 0 0 1 ]

[ -0.444444 0 1 ]

[ 0 -0.666666 0.666666 ]

[ 0 0 1 ]

Right monitor rotated to inverted:

- Code: Select all
`xinput set-prop "Serial Wacom Tablet stylus" --type=float "Coordinate Transformation Matrix" -0.444444 0 1 0 -0.666666 0.666666 0 0 1`

Now what happens if we rotate the tablet pc to portrait mode? Note X & Y swap, becoming 800x1280. Since cos(270) = 0 and sin(270) = -1 you end up with this matrix.

- Code: Select all
`right:`

[ 0 800/(1600+800) 1600/(1600+800) ]

[ -1280/1280 0 1280/1280 ]

[ 0 0 1 ]

[ 0 0.333333 0.666666 ]

[ -1 0 1 ]

[ 0 0 1 ]

Right monitor rotated to portrait:

- Code: Select all
`xinput set-prop "Serial Wacom Tablet stylus" --type=float "Coordinate Transformation Matrix" 0 0.333333 0.666666 -1 0 1 0 0 1`

II. Three Monitors - simple case

Three monitors with the same resolution. You set up the linear transform and since we're scaling from 0-1 if all three monitors have the same resolution you'd end up with:

- Code: Select all
`left center right`

[ 1280/(3*1280) 0 0 ] [ 1280/(3*1280) 0 1280/(3*1280) ] [ 1280/(3*1280) 0 (2*1280)/(3*1280) ]

[ 0 1024/1024 0 ] [ 0 1024/1024 0 ] [ 0 1024/1024 0 ]

[ 0 0 1 ] [ 0 0 1 ] [ 0 0 1 ]

left: center: right:

[ 0.3333 0 0 ] [ 0.3333 0 0.3333 ] [ 0.3333 0 0.6666 ]

[ 0 1 0 ] [ 0 1 0 ] [ 0 1 0 ]

[ 0 0 1 ] [ 0 0 1 ] [ 0 0 1 ]

* tested by mugginz, he used 3 decimal accuracy

* Rumtscho was able to use 4 decimal accuracy; matrices changed to reflect that

So now the xinput commands to set the device to the desired monitor are:

Left monitor:

- Code: Select all
`xinput set-prop "Device name" --type=float "Coordinate Transformation Matrix" 0.333333 0 0 0 1 0 0 0 1`

Center monitor:

- Code: Select all
`xinput set-prop "Device name" --type=float "Coordinate Transformation Matrix" 0.333333 0 0.333333 0 1 0 0 0 1`

Right monitor:

- Code: Select all
`xinput set-prop "Device name" --type=float "Coordinate Transformation Matrix" 0.333333 0 0.666666 0 1 0 0 0 1`

Note: The xinput command does not last through a restart. See below.

III. To Have the Settings Last Through a Reboot

You have to apply the xinput or xsetwacom command with each restart. You should be able to add it to your xsetwacom start up script, if you have one. Otherwise run it from a convenient start up script. Sample start up scripts are attached to posts 1 & 2 of the Wacom Bamboo Pen and Touch tablet HOW TO thread. Add the appropriate command for each device (stylus, eraser, and cursor) to its section.

To set it up to auto-start, download a sample file or make your own, and rename it .xsetwacom.sh (or whatever you want) and place it in your home directory. Remember it will be a hidden file. To enable the xsetwacom commands in the .xsetwacom.sh file to apply to Xserver through a reboot you enter in a terminal:

- Code: Select all
`chmod +x ~/.xsetwacom.sh`

or you could right click on the file and in Properties, in the Permission tab, check Execute as program. Then go to System->Preferences->Startup Applications and click on add and for the command write "sh /home/yourusername/.xsetwacom.sh" (without the quotes). You can also change your settings on the fly using the xsetwacom parameters in a terminal. They only apply during the current session.

Once the script is executable you can double click on it to apply it's settings or reboot to check the auto-start set up.

Note: In the sample scripts both "device name" and ID # are used. Be sure to check for yours using 'xinput --list' (without the quotes) in a terminal and use them. When you use a xorg.conf the "device names" will be stylus, eraser, touch, and pad. If you are hot plugging your tablet or other devices be sure to use "device name" as the ID # can change.

Appendix 1 - Tablet PC Rotation with CTM

Rather than axis inversion and swap for evdev rotation the CTM method can be used instead.

The CTM for none/normal or no rotation is the identity matrix:

- Code: Select all
`[ 1 0 0 ]`

[ 0 1 0 ]

[ 0 0 1 ]

and the command to implement it:

xinput set-prop "device name" "Coordinate Transformation Matrix" 1, 0, 0, 0, 1, 0, 0, 0, 1

The CTM for ccw/left rotation is:

- Code: Select all
`[ 0 -1 1 ]`

[ 1 0 0 ]

[ 0 0 1 ]

and the command to implement it:

xinput set-prop "device name" "Coordinate Transformation Matrix" 0, -1, 1, 1, 0, 0, 0, 0, 1

The CTM for half/inverted rotation is:

- Code: Select all
`[-1 0 1 ]`

[ 0 -1 1 ]

[ 0 0 1 ]

and the command to implement it:

xinput set-prop "device name" "Coordinate Transformation Matrix" -1, 0, 1, 0, -1, 1, 0, 0, 1

The CTM for cw/right rotation is:

- Code: Select all
`[ 0 1 0 ]`

[-1 0 1 ]

[ 0 0 1 ]

and the command to implement it:

xinput set-prop "device name" "Coordinate Transformation Matrix" 0, 1, 0, -1, 0, 1, 0, 0, 1

Use your "device name" from xinput list of course.