SaneTwain

Introduction

When I bought a new scanner some time ago, I chose one which was supported by SANE, as it seemed logical to me to connect it to my Linux server, so I could use it from my regular Windows desktop, or from my laptop.

To my surprise, there were no decent SANE to TWAIN bridges available. There were two projects (WinSANE and another WinSANE) but neither of those did what I wanted if I could them to work at all. Another solution seemed to be to use a Windows port of XSane but that also wasn't what I wanted: I use Corel PhotoPAINT, and I want to scan from within PhotoPAINT. (When I was more or less finished, I saw that another bridge (twain-to-sane-bridge) had been released. Luckily, again, that did not everything I needed.)

So I decided to write my own bridge. A first attempt used the Windows port of the net backend of SANE which was used for WinSANE, but somehow I didn't get it to work without generating a GPF after a while. The project was put on hold for a while, and in october 2001 I took it up again. This time I decided to write my own socket communication layer, talking to the SANE net backend myself.

For the TWAIN layer on top of the SANE layer, I looked around for examples of TWAIN DataSources. The TWAIN working group provides an example with their development kit, but it didn't stand out in clarity. On the Dosadi website I found the GenDS package, which supports developers in writing TWAIN datasources. This framework worked just fine, although getting Borland VCL (used for the GUI) and Microsoft MFC (used by GenDS) to work together took some effort.

From version 1.27 onwards, I've replace the GenDS toolkit by a port of another TWAIN layer, based upon the TWAIN SANE layer for MacOS X. After upgrading to Windows XP and version 6 of the Borland C++ compiler, I found that I couldn't get the combination of MFC and VCL to compile successfully.

Installation and setup

After downloading SaneTwain (see below), unzip the files. Put ScanImage.exe anywhere you want, it is a stand-alone version of SaneTwain, more or less like xscanimage. Put the SaneTwain.ds file in the twain_32 folder of your Windows system folder (usually c:\Windows or c:\WinNT). If you don't have a twain_32 folder, your computer might not have TWAIN installed, see the TWAIN website for details on downloading the TWAIN Data Source Manager. Make sure the SaneTwain.ds file has execution rights set.

It is recommended to start ScanImage first, to set-up the connection to your SANE server. (Note: if you are using Windows NT or 2000, it is probably wise to run it the first time as Administrator logged in to the Local Computer). The first time the program is started, a properties window will be shown. This window can be recalled later using the the properties button (). All settings in this window are stored in the sanetwain.ini file, which is stored in your Windows folder (usually C:\WINDOWS or C:\WINNT).

If the sanetwain.ini file is read-only, the properties button will be disabled, and the user cannot change any of the above properties. This might be useful when the Windows system folder is not writeable to all users.

Connection settings

On the "Connection" tab, you can enter hostname and portnumber (the default is usually OK). Leave the "Get list of devices at startup" checkbox checked, so the software will retrieve a list of available devices. Unless your SANE setup is not a default one, the username can also be left as PCUSER.

Preview settings

On the "Preview" tab, you can usually leave "Use minimum resolution" checked, unless the minimum resolution for your scanner is too low to give acceptable previews. If this is the case, change it to "Use the following resolution" and enter a suitable resolution in the next field.

General settings

On the "General" tab, there is an option to instruct SaneTwain to display its window always on top of all other windows. This might be useful if you are using SaneTwain from a TWAIN application which raises itself on top of the SaneTwain window.

The next option, when checked, will cause all inactive options to hidden (instead of being shown disabled). Any change will take effect after the next restart.

When you change a scanner option, and the backend instructs SaneTwain to reload scanner options, any regions you might have set will be removed. If you want to keep any regions (which could be invalid due to the changed scanner options), uncheck "Remove regions when parameters change".

If you want to define a default region to be used by default each time you use SaneTwain, check the "Save regions on exit". Any regions active when the application closes will be saved to the sanetwain.ini file, and restored next time the program starts. This is mutually exclusive with the previous option.

See the ADF section for more information on the ADF option.

By default, images saved to disk when using ScanImage.exe are in BMP format. When the "Save images as JPEG" is checked, all images are saved as JPG files, using the quality factor given.

Printer settings

Check "Show printer setup dialog before print" to bring up the standard Windows printer setup window before each print action.

By default, each scan made will be printed immediately after the scan completes. If you want to collect all scans into a single print job, check "Delay printing until program exit".

If you want a different printer used as default with the Print button, select a printer here. Note: this will not change your default Windows printer. This can be useful for example when you use the print option always to print a scan to a Fax printer driver.

Startup settings

If you want SaneTwain to automatically start a preview or a full scan when the program is started, check either "Acquire preview on program start" or "Acquire full scan on program start".

On this tab you can also select the language to use in the user interface. Only languages for which I have translations are shown. If you are willing to create a translation for another language, and are willing to keep those translations up to date if I add new strings, please contact me!

Please note that after changing the language you need to restart the application to take full effect. Also note that any saved option values are saved "localized", so they need to be resaved.

Using SaneTwain in "closed" environments

When using SaneTwain in a "closed" environment such as a terminal environment where users are not allowed to write to or update files in the Windows folder, it is possible to provide a read-only INI file. Create the INI file logged in as a user who is allowed to modify files in the Windows folder (or copy an INI file from another computer), and change the file properties to "Read-Only". SaneTwain will read the file, but will not allow the user to change any settings.

Additionally, it is possible to define a number of "preset" devices in the INI file, and allow the user to select one of those (note that this differs from "Get devices at startup", which only fetches the devices from a single server - this option allows scanners attached to different servers to be used using a single INI file).

To enable this, using the regular user interface, create scanner settings for each required scanner. This might involve setting hostname for each scanner, letting the software retrieve all available scanners, setting options, and saving them (see the section Saving options below). After each scanner, move the the Host and optionally Port and Username keys to the section for the scanner being configured, and optionally rename the scanner device name (for a more user friendly scanner name; the scanner device name is used as section identifier in the INI file).

When done with all scanners, add a Devices key to the [Connection] section, using a comma separated string of scanner names as value. Optionally set the Device key to one of these scanners to use as default, or remove the key.

Now the next time SaneTwain starts up, it will insert each defined scanner in the combobox for choosing a device, and will set its perset option values.

An example of this setup is as follows:

[Connection]
Devices=My Scanner (color),My Scanner (gray)
User=PCUSER
Port=6566
Device=My Scanner (color)
GetDevices=0

[My Scanner (color)]
Host=scanner.example.tld
Device=epson:/dev/usb/scanner0
mode=Color
resolution=150

[My Scanner (gray)]
Host=scanner.example.tld
Device=epson:/dev/usb/scanner0
mode=Gray
resolution=300

The main window

After pressing OK, the main window should appear (see above). In the combobox at the top right, all available devices should appear. If you have just one device, or have only one device you want to use with SaneTwain, you press the properties button (

) and uncheck the checkbox: this will shorten startup time. The drawback is that you cannot change devices within a single session.

Setting options

The SaneTwain GUI will query the selected SANE device and will retrieve all options available. Each of the options (except for a few well know options, see below) are translated into an input component and placed on one of the option tabs. For string, fixed and integer options withou constraints, a text input field is used. For options with a list constraint, a combobox is used. For options with a range constraint a trackbar is used, except when the option allows multiple values, then a curve input window is used (see below). Boolean values are represented by a checkbox, and 'button' options by a button (...).

When the value of an option is changed, the new value is sent to the SANE backend. This in turn might lead to a reloading of other option values: for example when the scan mode is changed from "color" to "black and white" the dropout option might be disabled, as it has no meaning for the new mode.

For a few well known options, there are special cases: the scan resolution and scan mode will appear on the main window toolbar if the backend supports these options.

Saving options

It is possible to save option values as defaults to the sanetwain.ini file. Just move the mouse over the input component for the option (e.g. a combobox, or a text entry field), and press Ctrl+S. A message should appear at the bottom of the window with the name of the option and the saved value. The next time SaneTwain is started, the defaults will be read after opening the scanner device. Saving options does not work for "button" options and options which can have multiple values. All options can be saved in one go by pressing Ctrl+A when the main window has focus. Note that this might not work with all combinations of options and values, as setting one option might influence possible values for other options, and all options are restored from sanetwain.ini in the order the backend defined.

Preview

You can request a preview from the SANE backend by pressing the preview button (

). This will retrieve a preview using the lowest resolution available, in the scan mode selected. When the backend supports setting the region-of-interest (i.e. allowing scanning only parts of the scan area), SaneTwain will allow you to select regions with the mouse.

Regions

The main image at the top shows two selected regions. Regions can be selected (when supported by the backend) by pressing the left mouse button at one of the corners of the region you want to select, and while holding down the mouse button, dragging the mouse to the opposite corner. During this drag a "rubber band" will show the new region. After releasing the mouse button, the new region will be drawn using a "walking ants" rectangle.

Existing regions can be resized by moving the mouse over one of the region borders (the mouse cursor will change to indicate you are over a region) and pressing the mouse button and dragging the border to its new position.

A region can be deleted by moving the mouse over one of its borders, and pressing the right mouse button. A pop-up window will show (see image on the right) from which you can select the Delete option.

The same pop-up also contains a number of preset paper sizes. When selecting one of those, all currently defined regions are deleted, and a new region of the specified size is created, anchored in the top-left hand corner.

Scan

After selecting the regions you want to scan, press the scan button (

) to scan those areas. When using ScanImage a file selection dialog box will appear asking for the name of the image (when scanning a single region) or the basename of the image when scanning multiple regions. The basename will be appended by a sequence number for each region.

Print

When running SaneTwain as stand-alone application (using ScanImage.exe), there will also be a print button (

). After selecting the regions you want to scan, press the print button to scan those areas and print each region as a separate document. This function is mainly intended to make a quick copy of a page, or to fax a page, so there are not many options which can be set. When the button itself is pressed, the default printer is used. If you have more than one printer installed, you can select the printer to use through the small popdown menu which is attached to the little triangle to the right of the button. Selecting a printer will immediately start the scan.

Curve input window

For numeric options which can have multiple values (most notably gamma correction tables), a special curve input window is available. These options have a curve button (

) as input component. When you press the button, a separate window will open. The idea behind the window is that for each value on the X axis, the "curve value" at the Y axis is used as the X'th value of the option.

By using the buttons at the top of the window, three pre-defined curves can be selected, or a "gamma curve" can be drawn, using a specific gamma value. After selecting one of the pre-defined curves, the curve can be modified by dragging on of the red handles to a new position, or by clicking on the curve between two red handles, which will insert a new handle.

ADF scanning

There is now basic ADF support. SaneTwain will try to determine if your scanner supports Automatic Document Feeding (ADF) by looking for an option 'source' with a value 'Automatic Document Feeder' or 'ADF', or a boolean option with the letters 'adf' in its name, and set to true.

Currently, only one region per page is allowed when using an ADF. By default, SaneTwain scans just a single page each time. By unchecking the appropriate option on the 'General' settings-tab, SaneTwain will try to keep scanning the same region over and over until the scanner returns an error.

The TWAIN datasource version of SaneTwain currently ignores the "scan single page" option, and allways will try to scan all pages in the feeder.

As I don't have an ADF myself, I would welcome any comments on this feature.

Miscellaneous

SaneTwain tries to guess whether the scanner backend has an option which would require the user to press a button before starting the scan. As there is no "well-known" option for this, SaneTwain inspects the option names for the string "wait" and "button". If such an option is encountered, and it set when a scan should start, a messagebox will pop-up reminding you that a button should be pressed. (Note: this is not fool proof, let me know if this not work with your scanner setup).

It is now possible to float the Preview and Options tabs if you want to. Just drag a tab off the SaneTwain window - the mouse cursor will change to indicate when you can release the mouse button. To attach a floating tab back to the main window, drag and drop it where it originally came from.

Known issues

The following are known issues, bugs, etc:

For SANE options of type 'fixed' which have a range constraint, a trackbar is used which can only handle a resolution of 0.01, so not all values van be set
For SANE integer and fixed options which can have multiple values, only those who have range constraints are supported (using a curve input window such as used for gamma tables)
When dragging a trackbar, or typing text into a textfield, for each change the SANE backend is contacted (this is what xscanimage also does, though)
Although the curve input window is also used for options which have an allowed range which is different from the number of allowed values, the curve is still shown in a square shaped window
When using the curve input window for a ranged option, the 'quant' property of the option is ignored
When using SANE authorization, passwords are sent as plain text
Because the allowed values for the SANE option mode are not pre-defined, the TWAIN layer tries to guess whether the backend supports TWTP_BW, TWTP_GRAY and/or TWTP_RGB pixeltypes
Some TWAIN applications will try to set TWAIN capabilities (SANE options) before showing the GUI. For those applications (most "regular" paint programs don't do this), it is advised to uncheck "Get list of devices on startup" as changing devices within a session might remove or alter options which the TWAIN application has set
Only the TWAIN capabilities for pixeltype, (x and y) resolution, image transfer count, and region-of-interest are supported, but only if the backend supports a similar option
For 16 bits per channel modes, SaneTwain will not save files in/provide TWAIN with those modes, but will use 8 bits per channel instead. This is due to DIB file format limitations, and me not yet having found a good drop-in replacement for regular bitmaps.

FAQ

I get an error "Couldn't initialize dynamic link to twain_32.dll"
Try upgrading to the latest version of TWAIN on www.twain.org.
I get errors like "Error 64: The provided Network name is no longer available", "Read error -1" and "Write error -1"
Try upgrading to the latest version of SANE. I've had multiple reports from users with similar problems which disappeared after upgrading to a version >= 1.0.7.
Using the SANE network backend, I can see my scanner, set options, etc., but I cannot preview or scan
Make sure that the networked scanner is not behind a firewall which blocks ports > 1024. Currently, SANE asks the operating system a new port (> 1024) to use when doing the actual preview or scan. The normal SANE port (6566 by default) is used only for setting options etc. The port returned by the operating system cannot be determined beforehand.
I'm getting connection timeouts
Try adding a line Timeout=<value> (without quotes) to the [Connection] section of sanetwain.ini. Value should be the socket timeout in milli-seconds. It defaults to 60000 (or 60 seconds).
I'm using Windows 2000, and having problems
I've had several reports on problems which could be traced to access rights on the TWAIN libraries (in the Windows folder), or the sanetwain.ini file. One user suggested to install the software using the Administrator account (of the Local Machine) if the computer is participating in a domain. Once installed and working, it can be used by any user by default.
The hostname, port and user fields are disabled in the preferences dialog
These fields are disabled when in the INI file the Devices key has been set to a list of devices to show in the combobox. Change these values in the INI file directly.
The saned server on my Linux box is crashing
Older versions of SANE and some backends had some problems with SaneTwain (inadvertently) requesting a scanner device using an empty device name. Try setting the Device key in the [Connection] section of sanetwain.ini by hand. The value should extacly match the device name as returned by scanimage -L from the SANE package. If this does not help, please send me a bug report, including you INI file, and the output from saned -d128 (see the saned manual page).
I get "Invalid argument (usually an invalid option value)" messages when trying to scan
In normal situations, this message would indicate that you tried to set an option to a value which is not allowed by the backend. However, in some situations this message might also appear when the backend failed setting the value on the scanner. This could be caused by a "slow" USB backend on your server, see e.g. for example this message on the SANE mailing list, or the FAQ on the EPSON backend pages
I cannot scan more than one image into Word, then it crashes
I've experienced this error as well, and have so far not been able to figure out what triggers the error. During debugging I found that rigorously removing a specific registry key related to scanning would allow Word to scan multiple images in a single session. For a quick fix, try adding the following to sanetwain.ini:
```
[Voodoo]
RemoveWordKey=\Software\Microsoft\Office\10.0\Common\Scan
```
The exact name of the key is depends on the Word version you are using, and it might not help with other versions of Word. If this is set, SaneTwain will remove the given key on startup, therefore hopefully allowing Word to scan. Use at your own risk.

Download

The latest stable version of SaneTwain is available as a ZIP-file. The ZIP-file contains ScanImage.exe, SaneTwain.ds and this documentation. The latest beta-version is also available as ZIP-file, but that one does not contain the documentation, and might not always contain both DS and EXE. A Windows installer is also available. My thanks to Fritz Elfert for providing an initial installer package.

License and credits

The binaries of SaneTwain.ds and ScanImage.exe are released as e-mail-ware: please send me an e-mail if you use the program. If you are really ecstatic about SaneTwain, I have a wish list at Amazon. The TWAIN layer is partly based on the TWAIN SANE Interface for MacOS X by Mattias Ellert. Two header files from the SANE project are used. Translations were gracefully provided by J�rg Napp, Roland Jeremies, Serdar Ozler, Peter Vereshagin, Anthony Bourguignon and Wladston Viana. Fritz Elfert provided the installer for SaneTwain.

Version history

1.00

initial version

1.01

added --debug option, limited DEBUG support
fixed bug: when connecting and authorization was outright rejected, we went in a loop (thinking the user type a wrong password)
fixed bug with display of version number

1.02

fixed bug when trying to put a trackbar (for resolution) on the toolbar [SaneTwain uses a regular editbox now instead]
ignore any SANE_STATUS_INVALID errors when ACTION_GETting a value
Changed the MaskEdit for a CurrencyEdit for ints and floats

1.03

options tabs now are only added when there are options to show for that tab
don't get value anymore when option is disabled; don't ignore STATUS_INVALID anymore when ACTION_GETting a value

1.04

added a preview resolution option to the properties tag

1.05

added some more debugging output for --debug

1.06

when using an edit box for resolution, delay sending a new value to the backend until the scan button is pressed

1.07

fixed minor bug which caused disabled options to appear enabled in the user interface

1.08

1 bit and 8 bit images are now saved and transferred as such
the preview window will now always stay on top, as some TWAIN applications will hide the window and not close it after a scan

1.09

added option for username to use

1.10

fixed bug which could cause banding on certain backends

1.11

added an option to keep the window always on top (was the default before, should now explicitly be turned on)
when the sanetwain.ini file is read-only, SaneTwain no longer tries to save the current settings. This is useful when the Windows directory is not writeable for regular users
added the option to save default values for options to the sanetwain.ini file

1.12

fixed bug when starting SaneTwain for the first time, the INI file wouldn't get created

1.13

added [Connection] TimeOut=value option in sanetwain.ini (value is socket timeout in milli-seconds; defaults to 60000)

1.14

added possibility to press ESC to cancel a scan

1.15

added option for starting a preview on first show of window
added option for not removing selected regions
the software tries to guess whether there is an option which forces the backend to wait for the button on the scanner. If set, SaneTwain will show a dialog box before scanning
allow for dragging the Preview and Options tabs from the main window so they can float
added rudimentary print option for ScanImage.exe [works for me, no guarantees for other printers]
fixed some bugs related to a read-only sanetwain.ini

1.16

fixed some problems with text entry boxes and transfer of focus

1.17

fixed a problem I accidently re-introduced w.r.t. disabled options
fixed a bug that caused a scan not to be properly "cancelled" when the scanner handle was 0

1.18

added option to autostart a scan upon startup

1.19

fixed bug when autoscanning using the datasource
added option to set default printer to use
added option to save regions on exit, and load on entry
added option to popup printer setup dialog before print
rudimentary ADF support. YMMV!
fixed bug where setting string options with a constraint from INI file did not actually set new value (e.g. for mode)
resizing the window now also resizes the preview

1.20

added a check on minimum scan region size, preventing single mouse clicks resulting in a miniscule region
removed setting the scan mode from the TWAIN supplied pixelType when the user has saved a value for the mode option

1.21

more debug messages when using --debug
when using ADF, scans were not saved to separate files
enabled ADF for the TWAIN datasource; assumes ADF on by default!
fixed bug when removing regions without the mouse being over a region border
added support for saving as JPEG images
buttons now autosize to tak full caption
labels wrap and autosize when too large
added option to hide disabled options
SANE_TYPE_FIXED options with a raneg constraint now have a working slider
fixed bug when backend has both regular and x-resolution option

1.22

major bug fix w.r.t. painting of non-existing regions (with many thanks to Jochen Staerk)

1.23

added option to delay printing until program exit

1.24

further fix w.r.t. slow performance

1.25

save of current window position/size on exit and restore on load

1.26

write dpi to BMP files

1.27

replaced the TWAIN layer
internationalization
update GUI to have XP look-and-feel (in TWAIN mode only when TWAIN application has XP themes enabled)
added paper size presets in the popup menu
added shortcut to save all option values using Ctrl-A
allow resizing from corners of region
added option to have a number of pre-set device settings in the INI file
some options (using sliders and text entry fields) where not properly restored when using saved values
fixed bug which could cause saned to crash (when supplying an empty device name, and cancelling a failed open call)
fixed bug preventing negative region coordinates
fixed major bugs in 1 and 16 bit modes
fixed bug with respect to not showing proper resolution
fixed bug in setting region selection received from TWAIN application
fixed bug when an error occurs in retrieving an option, and the valueSize is unreliable
do not try to GET inactive options, this won't work on all backends
ignore "not supported" errors on GET options
do not disable cancel() calls after first cancel(), so scanner will always be in a predictable state (with many thanks to Andreas Beule)
skip empty regions in the INI-file (and fix popup not to generate them anymore)
do not scan when user selected 'Cancel' on print settings dialog
use lower timeout when waiting for socket to get ready for read/write so startup is seriously improved (not on all scanners; with many thanks to Ruediger Hahn)
fixed translation bug when running SaneTwain for the first time
fixed bug which causes regions to move whilst resizing

1.28

attempt at fixing multipage ADF scans in TWAIN mode
added Portuguese
enable translations of strings from the SANE backend