Previous Up Next Guide

Using Capabilities

The TWAIN system allows your application to configure the device using capabilities. Capabilities are the options which are available on the scanner. Your application can query and set the capabilities.

Querying Capabilities

In order to query capabilities, you have to create a Source object. The following interactive session shows the three functions for querying capabilities.

C:\Python22>python
Python 2.2 (#28, Dec 21 2001, 12:21:22) [MSC 32 bit (Intel)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import Tkinter
>>> F=Tkinter.Frame()
>>> import twain
>>> sm=twain.SourceManager(F.winfo_id())
>>> ss=sm.OpenSource()
>>> ss.GetCapability(twain.ICAP_IMAGEFILEFORMAT)
(4, (0, 0, [2, 4, 0]))
>>> ss.GetCapabilityDefault(twain.ICAP_IMAGEFILEFORMAT)
(4, 2)
>>> ss.GetCapabilityCurrent(twain.ICAP_IMAGEFILEFORMAT)
(4, 2)
>>>

You need to have a window handle before you can create a SourceManager object. Here, I create a Tk Frame window, and use it's window handle in to initiate the SourceManager.

The Capabilities are related to the Source, not the SourceManager, so you have to create a Source object, i.e. you connect to your scanner software.

The Capbililities are defined by numeric constants. The names of the constants are in the TWAIN specification, chapter 9. There are three groups of capabilities, CAP_*, ICAP_* and ACAP_*. The CAP_* values are generic capabilities. The ICAP_* values refer to image-specific capabilities. The ACAP_* values refer to audio-specific capabilities. These capabilities are defined in the twain module (for specification version 1.9). In this example we are looking at the Image File Format capability (ICAP_IMAGEFILEFORMAT).

The GetCapability() method returns the available capabilities. The available capabilities are returned in one of four standard containers, 'ONEVALUE', 'RANGE', 'ENUMERATION' or 'ARRAY'. The ICAP_IMAGEFILEFORMAT capabities are returned here as an ENUMERATOR.

The ENUMERATION, ONEVALUE and ARRAY are all returned as tuples, where the first value is the type of the value. The type of the value is shown in the specification (chapter 9). The type used here is type '4', which is twain.TWTY_UINT16 (unsigned 16bit integer). The type constants are all prefixed with TWTY_ and are defined in the twain module.

The ENUMERATION indicates that the value has a set of specific, allowed values. The ENUMERATION includes a tuple with three members. These are, the index current value of the capability, the index of the default value of the capability, and the list of possible values, here 2, 4, 0. This return value is therefore interpreted as:

The GetCapabilityDefault() method returns the default value of capability. The default capability is normally a single value and is returned as the second member of the tuple (the first is the type as we said above). This is the value, to which the capability is set when you connect initially, or when you reset the capability.

The GetCapabilityCurrent() method returns the current value of capability. The current capability is normally a single value and is returned as the second member of the tuple (the first is the type as we said above).

Setting Capababilities

Your application can modify the capabilities in three ways:

To set the current value of the capability, use the SetCapability method. This method take three parameters, the identity of the capabaility (CAP_*, ICAP_* or ACAP_*), the type of the value (as returned from GetCapabilityCurrent), and the new value.

>>> ss.GetCapabilityCurrent(twain.ICAP_IMAGEFILEFORMAT, TWTY_UINT16, TWFF_JFIF)

This command instructs the scanner to return the image data as JPEG Interchange file format.

Note that, although the call to SetCabilility may return success, this does not indicate that the source accepted the value. The source may return success to indicate that it set it to the 'next best' value. Your application can retrieve the values from the scanner to verify that it was set as expected.

To reset a value to the default value, use the ResetCapability method This method requires a single argument of the capability identifier.

>>> ss.ResetCapabilityCurrent(twain.ICAP_IMAGEFILEFORMAT)

The twain systems supports restricting a capability, i.e. if your application only support 8bit images, don't allow the user to scan 24bit iamges. This functionality is not currently available in the twain module.

twexplore.py

The demonstration program twexplore.py allows you to quickly view the capabilities of your Source. The main screen shows a grid with the capability names, their values and their current values. If you double-click on an item, you are given a dialog, with which you can change the capability. The grid is refreshed each time a capability is change, so you can see the impact of the change, i.e. changing units changes the values for dimensions.

Twain Types

Parameters passed to the SetCapability must be consistent with the values expected by the TWAIN API, see chapter 9 of the specification. From the python perspective, the parameters are passed in the following format:

TWTY_INT*, TWTY_UINT*, TWTY_BOOL All of these values are passed as a Python integer or Python long integer.
TWTY_FIX32 These values are passed as a Python floating point number.
TWTY_FRAME These values are passed a Python tuple (Left, Top, Right, Bottom).
TWTY_STR* These values are passed a Python strings.

Wierd Stuff

The return value from GetCapability() can be in the format of a 'RANGE' or an 'ARRAY'.

A RANGE is converted to a python dictionary type. Ranges define values which are flexible within a specific range. There is not type information returned with a range. It contains 5 values, 'DefaultValue', 'MaxValue', 'MinValue', 'CurrentValue' and 'StepSize'. ICAP_XRESOLUTION is an example of a capability which is returned as an array.

>>> ss.GetCapability(twain.ICAP_XRESOLUTION)
{'StepSize': 1, 'DefaultValue': 150, 'CurrentValue': 150, 'MaxValue': 1600, 
'MinValue': 12}
>>>

An ARRAY is a value with no current or default information. It can be considered as a simple version of the enumerator. It is returned in a tuple, with the type. The CAP_SUPPORTEDCAPS is returned as an ARRAY.

>>> ss.GetCapability(twain.CAP_SUPPORTEDCAPS)
(4, [4101, 1, 4380, 4364, 4370, 257, 258, 4376, 4388, 4111, 4362, 4103, 4099, 0,
 40963, 64, 64, 0, 0, 0, 0, 0, 0, 0, 0])

The capability ICAP_SUPPORTEDCAPS should list the capabilities supported by the twain source. The demo program twexplore lists 'Supported Capabilities' in green.

Previous Up Next Guide