|
Calibration and User Interface Revision 1.17 - 20th
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.
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.
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.
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 |
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.
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:
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_M |
|
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.
1st 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_M
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_M
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_M
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_M
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_M
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;
·
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’.
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.
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.

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.
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:

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 |
M |
|
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 |
|