Frame 3 - Twain driver for LabVIEW / IMAQ Vision

First, install the Twain driver of your peripheral device (found on the floppy disk provided by the manufacturer of your hardware). It must install the libraries “twain.dll” and “twain_32.dll” in your windows folder. You must also install the user interface corresponding to your hardware in the folder \Twain or \Twain_32. Test your configuration by calling the TWAIN plug-in from the software provided with your peripheral device (scanner, camera...). If you do not succeed getting an image at this point, please contact the reseller of your hardware.

The setup program of the IMAQ Vision Vi’s for TWAIN asks you for your LabVIEW folder. It adds a library called Twain.llb in your \user.lib folder. This library appears as a new function sub-menu called Twain and is located in the User Libraries function palette.

TWAIN defines a standard software protocol and API (application programming interface) for communication between software applications and image acquisition devices (the source of the data).

The three key elements in TWAIN are:
- The application software: An application must be modified to use TWAIN.

- The Source Manager software: This software manages the interactions between the application and the Source. This software is shipped for free with each TWAIN application and Source.

- The Soure software: This software controls the image acquisition device and is written by the device developer to comply with TWAIN specifications. Traditional device drivers are now included with the Source software and do not need to be shipped by applications.

The TWAIN library for LabVIEW, was created in order to simplify the development of TWAIN based applications with LabVIEW/IMAQ Vision environment. The TWAIN library for LabVIEW manages all communications and data exchanges between your LabVIEW application and the TWAIN source manager - data sources.

When an application uses TWAIN to acquire data, the acquisition process may be visible to the application’s users in the following three areas:

All Vi’s dedicated to TWAIN are contained within the "AVTwain.llb" library. This library is found in "\LABVIEW\USER.LIB". On choosing "User Libraries\Twain" menu, you will see the following icons:

This set of Vi’s gives access to the following functions to acquire an image:
- Demonstration vi on how to build the TWAIN part of your application;
- Select, initialize, and close the data source of the acquisition (scanner, digital camera, etc...);
- Setup the document feeder; - Setup the acquisition settings (units, image type and resolution, ...);
- Select a region of interest (ROI) in the image ;
- Transfer an image from a TWAIN data source to an IMAQ Vision image.

The acquisition of an image through a TWAIN session requires several steps:
1. First, check if twain protocol is availabale with “Twain_isAvailable.vi”.
2. Open, a Twain source with “Twain_OpenDefaultSource.vi”.
3. Setup the acquisition with ‘Twain_Units.vi”, Twain_Resolution.vi” and “Twain_PixelType.vi”.
4. Create an IMAQ Vision image with “IMAQ_Create.vi”.
5. Then, the “TWAIN_Xfer.vi” will acquire the image, and transfer it to the IMAQ Vision image.
6. Call “TWAIN_CloseSource.vi” when Twain is no longer needed in your application.

Here is a very simple diagram (“Demo_Twain.vi”), which shows how to use the functions:

This Vi returns “TRUE” if the TWAIN protocol is installed on the system, “FALSE” otherwise.

Is Available is a boolean indicator which returns “TRUE” if the TWAIN protocol is installed on the system, of “FALSE” otherwise.

error out is a LabVIEW cluster error returning the text of the current error.

State is an enumerator indicator, which returns the current state of the TWAIN source.
Possible states are:
- Error
- Pre-Session: the TWAIN source manager is not loaded.
- Loaded: the TWAN source manager is loaded.
- Open: the TWAIN source manager is loaded and opened.
- Enabled: the TWAIN source is enabled to acquire.
- Transfer Ready: the image is ready to transfer.
- Transferring: transferring of the image is in progress.

error out is a LabVIEW cluster error returning the text of the current error.

Registration only provides some debug/development informations to the TWAIN Source Manager and any sources you may open. ‘Twain_RegisterApplication” is optional, but If you use registration, you may call this Vi first in your application.

Twain Application Info is a LabVIEW cluster which contains debug/development informations:
- Your software application major version number (integer number)
- Your software application minor version number (integer number)
- Your software application language
- Your country
- Your software application version information (string)
- Software developer information (string)
- Software family information (string)
- Software product information (string)

Example:
- Major version number : “1”
- Minor version number : “0”
- Language: “French”
- Country: “France”
- Version information: “v1.0 release”
- Developer information: “Mister X.“
- Family information: “image acquisition/processing software”

error out is a LabVIEW cluster error returning the text of the current error.

Note: Some TWAIN sources may not recognize this function. If so, this is a limitation of the TWAIN data source.

paper size is an enumerator, which allows to select the scanner paper size format, available formats are:
- A4 Letter
- B5 Letter
- Us Letter
- Us Legal
- A5
- B4
- B6
- Us Ledger
- A3
- B3
- A6
- C4
- C5
- C6
- Us Executive.

error out is a LabVIEW cluster error returning the text of the current error.

"TWAIN_ShowUI.vi”, allows to programatically show or hide the user interface panel of the TWAIN source. If you want to hide the source user interface, you must also, call “TWAIN_Units.vi”, “TWAIN_Resolution.vi” and ‘TWAIN_PixelType.vi” in order to properly setup the acquisition parameters.

Note: Some TWAIN sources may not recognize this function. If so, this is a limitation of the TWAIN data source.

Hide is a boolean, a “True” state hides the user interface, a “False” state shows the user interface.

error out is a LabVIEW cluster error returning the text of the current error.

"TWAIN_ShowIndicators.vi”, allows to programatically show or hide the indicators of the TWAIN source (like progress bars when scanning documents). Note: Some TWAIN sources may not recognize this function. If so, this is a limitation of the TWAIN data source.

Hide is a boolean, a “True” state hides the user interface, a “False” state shows the user interface.

error out is a LabVIEW cluster error returning the text of the current error.

These Vi’s allow to setup the TWAIN source manager :
- TWAIN_LoadSourceManager: loads the source manager into memory.
- TWAIN_OpenSourceManager: loads(if necessary), and opens the source manager into memory.
- TWAIN_CloseSourceManager: abort transfer (if any), and closes the source manager.
- TWAIN_UnloadSourceManager: abort transfer (if any), closes (if necessary), and unloads the source manager from memory.

error out is a LabVIEW cluster error returning the text of the current error.

These Vi’s allow to setup the TWAIN source manager :
- TWAIN_SelectImageSource: Opens the TWAIN source dialog box (“Select source...”), in order to select the acquisition source (if there is only source installed in the system, it is selected automatically).
- TWAIN_OpenDefaultSource: Opens the default source, or the currently selected source. 7
- TWAIN_CloseSource: Closes the current source.
- TWAIN_EnableSource: Enables the open source (in case it was previously disabled).
- TWAIN_DisableSource: Disables the open source.

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_HasFeeder.vi” returns informations about the presence or absence of a document feeder.

Has Feeder is a boolean indicator which returns “TRUE” if the TWAIN source has a document feeder, of “FALSE” otherwise.

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_FeederLoaded.vi” returns informations about the presence or absence of a document in the document feeder, the document feeder must have been selected using “TWAIN_SelectFeeder.vi”before calling this Vi.

Feeder Loaded is a boolean indicator which returns “TRUE” if the TWAIN source has a document in the document feeder, of “FALSE” otherwise.

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_AutoFeed.vi” sets/gets informations about the Automatic feeder mode. The document feeder must have been selected using “TWAIN_SelectFeeder.vi”before calling this Vi.

In “Set” Mode, this vi turns on/off the automatic feeding trough the feeder.

Auto Feed In is a boolean, this connector is useful only in the “Set” mode, a “TRUE” state turns the automatic feeder on, a “FALSE” state turns the automatic feeder off.

Set/Get is a boolean,,a “TRUE” state executes vi in “Set” mode, a “FALSE” executes vi in “Get” mode.

Auto Feed Out is a boolean, this connector is useful only in the “Get” mode, it returns “TRUE” if the TWAIN source document feeder is in automatic, or “FALSE” otherwise.

error out is a LabVIEW cluster error returning the text of the current error.

In “Set” Mode, this vi selects/deselects the document feeder according to the value in “Select Feed In”.

In “Get” Mode, this vi gets the current document feeder selection status, and returns it in “Select Feed Out”.

Select Feed In is a boolean, this connector is useful only in the “Set” mode,a “TRUE” state selects the document feeder, a “FALSE” state deselects the document feeder.

Set/Get is a boolean, a “TRUE” state executes vi in “Set” mode, a “FALSE” executes vi in “Get” mode.

Select Feed Out is a boolean, this connector is useful only in the “Get” mode, it returns “TRUE” if the TWAIN source document feeder is selected, or “FALSE” otherwise.

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_Units.vi” sets/gets informations about the current units .
Possible units setings are:
- inches
- centimeters
- picas
- points
- twips
- pixels

In “Set” Mode, this vi sets the current unit with the value in the “Unit In” connector.

In “Get” Mode, this vi gets the current units status, and returns it in the “Unit Out” connector.

Note: Some TWAIN sources may not recognize this function. If so, this is a limitation of the TWAIN data source (some TWAIN sources recognizes only the Inches unit).

Unit In is an enum control, this connector is useful only in the “Set” mode,it selects the current unit.

Set/Get is a boolean, a “TRUE” state executes vi in “Set” mode, a “FALSE” executes vi in “Get” mode.

Unit Out is an enum indicator, this connector is useful only in the “Get” mode, it returns the current unit status.

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_Units.vi” sets/gets informations about the current resolution (in dots/unit) .

In “Set” Mode, this vi sets the current resolution (in both x and y) with the value in the “Res dots/unit In” connector.

In “Get” Mode, this vi gets the current resolution, and returns it in the “Res dots/unit Out” connector.

Note: Some TWAIN sources may not recognize this function. If so, this is a limitation of the TWAIN data source.

Res dots/units In is a control, this connector is useful only in the “Set” mode, it selects the current resolution in both x and y (dots/unit).

Set/Get is a boolean, a “TRUE” state executes vi in “Set” mode, a “FALSE” executes vi in “Get” mode.

Res dots/units Out is an indicator, this connector is useful only in the “Get” mode, it returns the current resolution in both x and y (dots/unit).

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_PixelType.vi” sets/gets informations about the current pixel type.
Possible values of pixel type are:
- 2 colors black/white
- 256 grayscale values
- 256 palettized colors
- True RGB colors

In “Set” Mode, this vi sets the current pixel type with the value in the “Pixel Type In” connector.

In “Get” Mode, this vi gets the current resolution, and returns it in the “Pixel Type Out” connector.

Note: Some TWAIN sources may not recognize this function. If so, this is a limitation of the TWAIN data source.

Pixel Type In is a control, this connector is useful only in the “Set” mode, it selects the current pixel type.

Set/Get is a boolean, a “TRUE” state executes vi in “Set” mode, a “FALSE” executes vi in “Get” mode.

Pixel Type Out is an indicator, this connector is useful only in the “Get” mode, it returns the current pixel type.

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_SetROI.vi” sets the current region of interest . A “region of of interest” (ROI), is a 4 values cluster which defines the pixels coordinates of the rectangular acquisition region.
- 1st value is the x coordinate of the ROI top-left pixel.
- 2nd value is the y coordinate of the ROI top-left pixel.
- 3rd value is the width of the ROI.
- 4th value is the height of the ROI.

Note: Some TWAIN sources may not recognize this function. If so, this is a limitation of the TWAIN data source.

Region Of Interest is a cluster, defines the coordinates of the acquisition region.

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_GetROI.vi” gets the current region of interest . A “region of of interest” (ROI), is a 4 values cluster which defines the pixels coordinates of the rectangular acquisition region.
- 1st value is the x coordinate of the ROI top-left pixel.
- 2nd value is the y coordinate of the ROI top-left pixel.
- 3rd value is the width of the ROI.
- 4th value is the height of the ROI.

Note: Some TWAIN sources may not recognize this function. If so, this is a limitation of the TWAIN data source.

Region Of Interest is a cluster, which returns the coordinates of the acquisition region.

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_GetROI.vi” gets the default region of interest (defined by default in the TWAIN source user interface panel). A “region of of interest” (ROI), is a 4 values cluster which defines the pixels coordinates of the rectangular acquisition region.
- 1st value is the x coordinate of the ROI top-left pixel.
- 2nd value is the y coordinate of the ROI top-left pixel.
- 3rd value is the width of the ROI.
- 4th value is the height of the ROI.

Note: Some TWAIN sources may not recognize this function. If so, this is a limitation of the TWAIN data source.

Region Of Interest is a cluster, which returns the coordinates of the acquisition region.

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_ResetROI.vi” erases the current Region of interest. A “region of of interest” (ROI), is a 4 values cluster which defines the pixels coordinates of the rectangular acquisition region.
- 1st value is the x coordinate of the ROI top-left pixel.
- 2nd value is the y coordinate of the ROI top-left pixel.
- 3rd value is the width of the ROI.
- 4th value is the height of the ROI.

Note: Some TWAIN sources may not recognize this function. If so, this is a limitation of the TWAIN data source.

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_MultiXfer.vi” sets/gets informations about the multi transfer mode. The multi transfer allows to transfer multiple images from a TWAIN source, without closing and re-opening the source each time. So, if multi transfer mode is on, the TWAIN source is left open after a transfer, in order to allow additional acquistion(s) in the same session.

In “Set” Mode, this vi turns on/off the multi transfer mode according to the value in “Allow Multitransfer In”.

In “Get” Mode, this vi gets the current multi transfer mode status, and returns it in “Allow Multitransfer Out”.

Note: in multi transfer mode, this vi can be used in conjunction with the “TWAIN_State.vi”:
- If “TWAIN_State.vi” returns a “Transfer Ready”state, it means that the source knows it has at least one more image to acquire.
- If “TWAIN_State.vi” returns a “Source Enable” state, it means that the user has not closed the source, so it might be able to acquire another image
- If “TWAIN_State.vi” returns a “Transferring” state, it means an image transfer is in progress.

Allow Multi Transfer In is a boolean, this connector is useful only in the “Set” mode.,a “TRUE” state turns on the multi transfer mode , a “FALSE” state turns off the multi transfer mode.

Set/Get is a boolean,,a “TRUE” state executes vi in “Set” mode, a “FALSE” executes vi in “Get” mode.

Set/Get is a boolean, a “TRUE” state executes vi in “Set” mode, a “FALSE” executes vi in “Get” mode

error out is a LabVIEW cluster error returning the text of the current error.

“Twain_Xfer.vi” transfers an image acquired by the TWAIN protocol to an IMAQ Vision Image.

Notes:
- you must call “IMAQ Create.vi” first and connect the Newly created image to the “Image In” connector.
- If the “Image In” resolution and/or type doesn’t match the acquisition settings then “Image In” will be automatically resize and/or convert.

Color Palette is an IMAQ Vision color palette indicator, this connector is useful only when working with 8 bits IMAQ Vision image (grayscale, black/white, or palettized pixel type). You will have to connect this color palette to the “IMAQ Winddraw.vi” in order to display the acquired image with good colors.

error out is a LabVIEW cluster error returning the text of the current error.