Calibration and User Interface

Revision 1.17 - 20^th May 2008

The need for calibration is unique to absolute pointer devices, such as a touch screen or white board. Unlike mouse or keyboard applications where the cursor is part of the image, a touch screen is a physical overlay or layer with an independent coordinate system. Only by knowing the position of the image can the touch screen coordinates be converted into image coordinates, hence the need to align the two different co-ordinate systems.

Besides the differences in touch screens and controllers, calibration also compensates for the variation in video image among displays. The image is affected by horizontal and vertical adjustments on the monitor and by the physical mounting of the touchscreen.

Additional calibration complications include image blooming, where bright-colored images expand, and the "pin cushion" effect, which causes the corners of the display to be stretched. Poor display linearity can cause similarly-sized boxes to be larger at the edges of the screen than they are in the middle, or vice-versa. The displayed image can also be tilted. Even changing video modes can affect the screen size. If images are projected onto a white board from the side, top or bottom of the board then the image will not always be perfectly rectangular, this is known as keystone image.

Perfect calibration cannot be achieved in all circumstances. For example, the user can encounter parallax problems with a change in position, or because the present user is not the same stature as the person who calibrated the screen. Even the most sophisticated calibration techniques can only partially overcome such variations. To cater for the controller and video variations UPDD uses a number of calibration techniques to ensure best results for any given combination and this document covers all aspects of UPDD calibration issues.

As discussed, calibration is required to align the pointer device co-ordinate system with the video co-ordinate system. When using an absolute pointer device the mouse cursor should normally position itself under the stylus when it is in contact with the pointer device. If this is not the case then calibration will be required. The UPDD driver also supports Toolbars, which also require calibrating, and this is covered in full in a separate Toolbar document. This document covers the new calibration feature in UPDD Version 4.

Under UPDD the calibration program used to perform manual calibration is called TBcalib. Other ways of achieving calibration are discussed in the notes section of this document.

Given that TBcalib is a common component across all platforms and is utilised in all environments we have also exposed in this program common UPDD User Interface calls as a simple method for changing some of the UPDD settings that would normally be changed from applications using the UPDD API interface.

Defining Calibration

For Windows, Mac OS X and Linux, manual calibration settings can be configured in the UPDD Console, Calibration dialog:

This dialog defines the number of calibration points, the calibration timeout and the margin percentage. These settings are defined for each defined device and calibration style.

UPDD Devices

Each UPDD configured pointer device will be listed in the UPDD Console. Each device is given a ‘name’ and the current device is listed in the console program. Each device is associated with a Desktop segment which indicates the area of the desktop handled by the pointer device.

In this example the devices has been named ‘Elo, Smartset 2500 IntelliTouch - Right ‘ to indicate to the user it is associated with the right hand monitor in a multi-monitor configuration and has been associated with desktop segment ‘Monitor 2’.

Each device is also allocated a unique internal device handle which is held in the UPDD configuration file and available via the UPDD API to applications that interface directly with the devices.

Invoking Calibration

Manual calibration can be invoked in various ways:

· Calibrate option in the UPDD Console

This will calibrate the currently selected device and calibration style.

Request calibration	of the currently selected device	and style

· Directly calling the calibration program manually

Windows options

Desktop short cut

May exist under Mac OS X and Linux on the desktop after install. On Mac OS X a shortcut is also placed in the utilities folder. Depending on the Linux Desktop Manager in use this is not always setup automatically by the install procedure. Should be seen if using KDE.

These methods of invoking the UPDD Calibrate program (which does not pass any control parameters) invokes calibration for the current device and its calibration styles and toolbars (unless they are defined relative to the main video calibration). Control parameters that can be passed to the UPDD calibration program to perform other calibration options are discussed below:

Manually calling TBcalib program (only method available in OS where UPDD Console not available)

The calibration program is located in the UPDD application folder and can be invoked manually as shown:

OS	Command line via a terminal window or shortcut
Windows	C:\Program Files\UPDD\tbcalib.exe
Linux	/tbupddlx/upddcalib (Linux script to invoke the tbcalib application)
Mac OS X	/tbupddmx/tbcalib.app/Contents/MacOS/tbcalib

Passing TBcalib parameters if/as required.

· Program control via the UPDD calibration API calls

In the unlikely event that TBcalib cannot be called from a program to perform calibration, calibration procedures can be embedded in user written applications using UPDD API calls. Refer to the UPDD SDK or email the technical support team at technical@touch-base.com for additional information.

Calibration Procedure

Once invoked the calibration screen is displayed requesting that each calibration point be selected in turn.

The number of points shown and the position of the points are defined by the calibration settings in the UPDD Console, Calibration dialog. If the margin% setting is less than 5% arrows will be shown for points along the edges of the screen rather than crosses. If calibration is aborted or times out the driver discards the updated calibration data and reverts back to the previous data.

Important notes:

If the pointer is moving (especially during calibration) but the calibration touches are ignored it is likely that a different driver is in control of the device, not UPDD.

If the calibration screen is not drawn full screen or is distorted or offset in anyway then it is likely that the graphics system does not supported the method employed to force full screen drawing. In this case a different approach is needed as described in the Calibration Notes, Calibration Style entry below.

If using EEPROM calibration on devices where the calibration pattern is dictated by the firmware in the controller, the firmware may return a failed status to the calibration program if the touches on the calibration crosses are calculated to have not been in the correct relative position. E.g the 3M SCxxx 3 point EEprom calibration is based on a triangle and trigonometry is used by the firmware to calculate quite accurately where the 2^nd and 3^rd touches should be occurring. Recalibrate if a failed status is seen until calibration is accepted.

Calibration Notes

Calibration is a fundamentally important feature for pointer devices as successful usage is reliant on correct desktop alignment. UPDD implements some important features to ensure the calibration procedure produces the best possible results.

Where the following notes refer to calibration settings as held in the system the following applies;

UPDD version	Operating system	Location
UPDD 3.x.x and 4.0.x	Windows	registry at HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TBUPDD
UPDD 3.x.x and 4.0.x	Linux and Mac OS X	tbupdd.reg
UPDD 4.1.x	All OS	tbupdd.ini

The following issues should be considered when setting up UPDD’s calibration features:

· Calibration methods
Installing UPDD for the first time will require that the device is in some way calibrated and a number of options exist as discussed below:

Manual Calibration. The user executes the calibration program and touches a series of displayed points on the screen. For embedded environments data recorded in this way may be lost when the device is reset (if the UPDD settings are is not held in persistent memory) unless the data is stored in the touch controller’s EEPROM. An OEM using manual calibration, where the calibration data is lost over a reboot, needs to decide on a strategy for initiating the manual calibration. E.g. executing the calibration program at start-up, or placing an icon on the desktop.

1^st Touch calibration. Builds of the software can be supplied with a setting such that the first touch on the touch device after install will invoke manual calibration – this is currently a Windows only option.

Auto-calibration. If a calibration has not been performed the driver will try and scale the received co-ordinate with the desktop area. The calibration calculation is based on the maximum theoretical range of values (from the number of bits in the touch data packet) assuming that the available touch area is exactly the same size as the visible desktop area. This relies on the correct range of data bits being defined in the UPDD controller definition and that the orientation of the touch screen matches the UPDD invert X and Y settings.

Pre-calibration. Builds of the software can be supplied with pre-defined calibration data. The calibration data is determined for a device – or class of device - and stored in the initial UPDD settings file and installed as part of the install procedure.

Hardware – Some controllers, once calibrated using a controller specific hardware calibration, will output scaled co-ordinates. UPDD invokes this type of calibration for some controllers – see EEprom document for more information.

EEprom – Calibration is stored in controller eeprom and retrieved by running TBcalib eeprom at system startup. UPDD stores calibration data for some controllers - see EEprom document for more information.

· Calibration Style
Each UPDD device can have any number of calibration styles. In most cases a device will have a single style. However, some pointer devices can legitimately have more than one style, with each mode being calibrated separately. For example, a whiteboard can be used for drawing to the extreme corners and would be calibrated to the corners to ensure the whiteboard was fully calibrated. However, a desktop could be projected onto the whiteboard such that it did not fully cover the entire whiteboard area and therefore would need a different calibration to be accurate when used in projected mode. In this scenario, two calibration styles could be defined, say Whiteboard and Projected, and calibrated separately, thus avoiding recalibration every time usage of the board is switched.

Some video resolutions will effect the position of the video display and may need to have their own calibration data. This is catered for in the Track video resolution function in the UPDD Extensions.

A special calibration style has been reserved for situations whereby a system cannot handle the methods used the calibration program to force full screen with unpredictable results. In this situation define a style called Custom2Point whereby calibration does not attempt full screen mode (and therefore cannot draw accurate calibration points) but instead requests that the top left and bottom right corners of the calibration area be used as the calibration reference points. No other calibration patterns are catered for.

· Cursor movement
No cursor movement will take place if a stylus selects any area outside the main calibrated area or within a calibrated toolbar. This is now configurable. By default, no cursor movement takes place except in the main calibrated area but this can be configured otherwise if required.

· Calibration data storage
Calibration settings and the actual calibration data is held within the system or on the touch controller’s EEPROM (where available and supported). When stored in the system, and depending on the OS and the UPDD version in use, it is either held in the registry under Windows or a UPDD settings file.

EEPROM

Some controllers can store the data on the onboard EEPROM and if this is available a EEPROM check box will be shown on the calibration dialog. Your specific usage of the calibration data will determine what setting to select. Using EEPROM calibration may restrict the calibration points to specific locations as dictated by the controller’s EEPROM calibration procedure.

If EEPROM is used:

UPDD 3.x or 4.0 the UPDD registry entry or registry file setting
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TBUPDD\Parameters\{guid}\{Device Number}\EEPROM Calibration will be set to 1.
or

UPDD 4.1.x the [UPDD\parameters\{Device Number}\EEprom Calibration] entry in the UPDD settings will be set to 1.

EEPROM usage and considerations are explained in full in the separate EEPROM document

System

If EEPROM is not supported or not enabled then the calibration data it is either held:

UPDD 3.x or 4.0 the UPDD registry entry or registry file setting
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TBUPDD \Parameters\{guid}\{device number}

UPDD 4.1.x [updd\parameters\{device number}]

The specific values used are: -

Number Of Calibration Points

RefX0, RefX1, RefY0, RefY1 *

CalX0, CalX1, CalY0, CalY1*

InvertX, InvertY, SwapXY

*If “Number Of Calibration Points” is greater than 2 then there will be correspondingly more of these values.

· Absolute pointer devices
Calibration is only required for absolute pointer devices. Relative pointer devices such as mice and touch pads do not require calibration.

· Calibration Bounce
A calibration point is processed when stylus contact is removed (pen up) and the next calibration point is displayed. If a stylus ‘bounces’ on a calibration point, thus producing two pen up’s, then the next calibration point will be satisfied by the erroneous second pen up requiring the calibration process to be restarted – which can be annoying if calibrating with many calibration points. This is known as ‘Calibration bounce’. To avoid this problem UPDD implements a setting called ‘Min Cal Delta’. This value indicates the number of co-ordinates that must differ between the calibration points for the next point to be accepted. If this value is set to zero this feature is effectively disabled.

UPDD 3.x or 4.0 the UPDD registry entry or registry file setting
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TBUPDD\Parameters\{guid}\{Device Number}\Min Cal Delta.
UPDD 4.1.x [updd\parameters\{device number}\ Min Cal Delta]

· Check Calibration
At the end of the calibration process the new calibration data is stored and used immediately. If the calibration procedure produces poor calibration, possibly due to calibration bounce or inaccurate calibration point selection, then recalibration will be needed. However, if the calibrated device is the only pointer device in use then it may not be possible to invoke the calibration procedure due to poor calibration! A catch 22 situation! To avoid this problem a ‘Check Calibration’ option can be enabled in the calibration dialog, such that the ‘Confirm’ button shown at the end of calibration must be selected for the new calibration to be used. Failure to select the confirm button within a certain time will result in the new calibration data being discarded.

UPDD 3.x or 4.0 the UPDD registry entry or registry file setting
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TBUPDD\Parameters\{guid}\Check Calibration
UPDD 4.1.x [updd\parameters\Check Calibration]

· Calibration Beeps
The Calibration Beeps option (if available) will generate a sound when the calibration point has been selected. Useful if calibration is being done remotely from the system or desktop.

UPDD 3.x or 4.0 the UPDD registry entry or registry file setting
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TBUPDD\Parameters\{guid}\Calibration Beeps.
UPDD 4.1.x [updd\parameters\Calibration Beeps]

Under Linux the calibration beeps require a soundcard as we have not been able to access the internal pc speaker in Linux. The playback is performed using a sound utility called “sox” which seems to be installed by most mainstream Linux distributions. We play a sound file called beep.wav to emulate the sound is of a “click”.

· Pointer Device Orientation
UPDD expects pointer devices to be orientated such that the 0,0 (origin) co-ordinate is being generated from a known point on the device. If the device is incorrectly fitted, say in the case of a touch screen attached to a monitor, and it has been fitted ‘upside-down’ then the cursor will move in the opposite direction to that expected. If the number of calibration points is 4 or more then the calibration procedure will automatically calculate the orientation. Using 2 or 3 point patterns will require that the pointer device is fitted correctly with the origin co-ordinate being generated from the expected position. It is for this reason that we recommend a 4 point or more calibration pattern is used.

· Calibration Algorithms
UPDD employs three calibration algorithms;

A standard algorithm that works well for devices with good linear characteristics. This algorithm is used with all calibration patterns except 4, 9 and 25 points.
An advanced algorithm that works best on devices with poor linear characteristics. The advanced algorithm is used when the device is calibrated with 4 (except 20% in – see below), 9 or 25 point calibration patterns. This algorithm is more dependant on the accuracy with which the calibration is done so it is very important to calibrate with a stylus that can select the exact centre of the calibration cross or tip of the calibration arrow (in 0% in calibration).
4 point XY coefficient algorithm. This algorithm, introduced with UPDD version 3.8.24, is used when the touch media has linear distortion, such as shearing or keystoning. Typically used when projecting images onto electronic whiteboards from the side, top or bottom. This algorithm is invoked when the calibration pattern 4 point with 20% margin is specified.

· Rotational Software
Software can be used to rotate desktops through 0, 90, 180 and 270 degrees. UPDD can automatically cater for rotated desktops and readjust calibration. See the rotate documentation.

· Multiple monitor and devices
UPDD can support any number of pointer devices and desktop segments. A desktop segment is the area of the desktop associated with the device. E.g. In a two monitor system, both with touch screens fitted, the entire desktop could be spread over the two monitors. In this case each touch screen is associated with one monitor being half the desktop. The calibration procedure will take place on the individual desktop segment associated with the device and cursor movement will be restricted to that desktop segment when the device is in use. See the multi-monitor and device documentation for further details.

· Video Resolution

Changing screen resolution on some systems may require a new calibration to be performed in the new resolution. A future release will detect screen resolution change automatically load calibration data previously set for that resolution.

· Custom Desktop segments

Custom segments can also be defined to associate a touch screen with a specific area of a desktop segment:

Example custom segment definition	Resultant custom segment calibration

· Default calibration settings

UPDD can be supplied with default calibration data. This is particular useful in complex configurations, especially when many toolbars are defined and UPDD is being used on a preconfigured system. This allows for the display and the toolbars to be calibrated ‘out the box’.

Calibration testing

A calibration test utility is available and is used to test devices in as much as it will draw a line as the pointer moves around to show the calibration accuracy. This is testing the route of the data from the device via the hardware port, processed by the UPPD driver and then fed into the system’s low level mouse interface.

Invoking the Test Utility

The Test utility can be invoked from the UPDD Console, Status dialog. A line is drawn at the point of touch. Whilst contact is made with the touch device data is displayed and shows co-ordinate data information. When a liftoff occurs information is displayed to show what click emulation is performed. A full screen test option (which can be set as default and therefore may be the screen shown) can be invoked from this test screen dialog to draw around the entire screen, as well as a test grid option which can be used to test the screen linearization.

Testing driver interface only

An option exists to test the driver interface only and bypass the Windows low level mouse interface. This is known as UPDD Direct mode. Direct operation can be invoked via test program, direct option as show:

TO FOLLOW.

When in direct mode the dialog displays *** Direct Mode ***. In this mode drawing is being achieved via UPDD API calls and not via mouse emulation.

Calibration pattern templates

For customers wishing to test touch hardware from a desktop (with the touch screen remote from the video display) we have created a template generator. The template combines the calibration pattern with the linearization grid. In the generator you simply specify the size of the template in imperial or metric dimensions, the number of calibration points and the % margin and request the template be drawn. The template can then be printed to a suitable printer (the browser printer driver or the printer should not attempt to rescale the HTML drawing!).

The following example shows a 6” x 4” template with 4 calibration points and a 5% margin:

Calibration parameters and User Interface calls

TBcalib has a number of calibration related parameters and also offers a command line interface to change various UPDD settings and can also be used to reinitialise the controller or reactivate the driver.

The calibration program exports this interface using the following syntax:

Windows

TBcalib {parameter}

Note: Entering the commands from a Windows command line would be tbcalib “{parameters}”

Mac OS X

/tbupddmx/tbcalib.app/Contents/MacOS/tbcalib {parameter}

Linux

/tbupddlx/upddcalib {parameter}

Please note parameters are case sensitive and must be defined as shown below.

Calibration parameters	Used with the calibration procedure
None passed	will calibrate the first active device on the system.
Device=n	perform request on the specified device and, if calibrating, the currently selected calibration style, default first in list. Will also calibrate any defined toolbars unless ‘Toolbar=ABogusValue’ is used to disable toolbar processing Normally used by calling programs to perform a given function against a specific device, such as the UPDD Console device calibration option N=the device handle of the device as held by UPDD. This option is used by UPDD SDK based programs utilising the UPDD API to determine the device handle using related API calls such as TBAPIGetRelativeDevice.
Device=connected	Perform request on the first connected device.
Toolbar=whatever	only calibrate toolbar whatever
TOOLBAR	only calibrate toolbars
Style=stylename	calibrates a named style
/all	calibrates all active devices and ‘calibratible’ toolbars.
/assignall	Automatically associates a desktop (monitor) with the touch screen used to perform calibration. Cycles through all monitors. Very useful in multiple touch monitor environments.
User Interface Calls	*When TBcalib is invoked with a user interface parameter only the function associated with the parameter is performed. As would be expected, calibration is not invoked.*
Device=n	See above definition
/reinit	Reinitialise the controller and re-establish a link
Equivalent API call	TBApiReinit(passedDeviceNumber);
/reload	Force the driver to re-read settings (not necessary when using this interface to change a setting)
Equivalent API call	TBApiReloadNoApply();
/toggletouch	Toggle the device enabled state
Equivalent API call	DWORD dw; TBApiGetSettingDWORD(passedDeviceNumber,_T("Enabled"),&dw); dw ^= 1; TBApiSetSettingDWORD(passedDeviceNumber,_T("Enabled"),dw);
/enable	Enable the device
Equivalent API call	TBApiSetSettingDWORD(passedDeviceNumber,_T("Enabled"),1);
/disable	Disable the device
Equivalent API call	TBApiSetSettingDWORD(passedDeviceNumber,_T("Enabled"),0);
/pointeroff	Disable the driver mouse pointer interface (system wide – all devices)
Equivalent API call	TBApiMousePortInterfaceEnable(false);
/pointeron	Enable the driver mouse pointer interface (system wide – all devices)
Equivalent API call	TBApiMousePortInterfaceEnable(true);
/soundon	Turn sound on for the device
Equivalent API call	TBApiSetSettingDWORD(passedDeviceNumber,_T("Sound"),1);
/soundoff	Turn sound on for the device
Equivalent API call	TBApiSetSettingDWORD(passedDeviceNumber,_T("Sound"),0);
/togglesound	Toggle sound setting for the device
Equivalent API call	DWORD dw; TBApiGetSettingDWORD(passedDeviceNumber,_T("Sound"),&dw); dw ^=1; TBApiSetSettingDWORD(passedDeviceNumber,_T("Sound"),dw); TBApiApply();
/screenresupdate	MAC OS X only – Requests the driver to recalculate calibration mapping based one the current screen resolution. To be used where a system is calibrated in one resolution but uses other resolutions (especially useful where applications are changing resolution)
Equivalent API call	DWORD nDevices; TBApiGetSettingDWORD(0, _T("Number Of Devices"), &nDevices); for(unsigned j = 0; j < nDevices; ++j) { int dev=0; dev = TBApiGetRelativeDevice(j); if(!dev) { continue; } else { SetupForMultiMonitor(dev,this); } }
Use the following options to change arbitrary UPDD file based ‘registry’ settings. UPDD registry settings are documented in the UPDD SDK user help file.
/setting:XXX=NNN	Set the DWORD value XXX to the hex numeric value XXX
/settingsz:XXX=ZZZ