Correct TWAIN Usage

Background Smoothing:

The purpose of Background Smoothing is to remove overall mottle or discolorations in the background of the scanned image typically resulting from scanning and/or paper non-uniformity. Background Smoothing improves overall appearance of the image and also results in higher file compression ratios. These results are achieved by “smoothing” up to three background colors (one neutral and two additional colors). Optionally one or more background colors may be smoothed to white.

Background smoothing is only available for Color/Grayscale output.

The type of background smoothing that is applied to the image is selected using ICAP_BACKGROUNDADJUSTMODE. Selecting TWBS_AUTOMATIC or TWBS_AUTOMATICBASIC will “smooth” up to three background colors. Selecting TWBS_CHANGETOWHITE will allow one or more background colors to be smoothed to white.

When the TWBS_CHANGETOWHITE adjustment mode is selected, ICAP_ BACKGROUNDADJUSTAPPLYTO becomes available. ICAP_ BACKGROUNDADJUSTAPPLYTO is used to select which background colors to smooth to white.

TWBA_ PREDOMINATE will smooth the predominate background color to white.

TWBA_NEUTRAL will smooth just the neutral color to white and also smooth the two additional background colors.

TWBA_ALL will smooth up to three background colors to white.

The aggressiveness of the background smoothing is selected using ICAP_BACKGROUNDADJUSTAGGRESSIVENESS. The more higher the value, the more likely a pixel will be determined to be background.

This is available when ICAP_BACKGROUNDADJUSTMODE is not set to TWBS_NONE or TWBS_AUTOMATICBASIC.

Blank Image Deletion:

This feature allows the user to instruct the driver to remove images that are considered blank. The driver can determine if an image is blank based on the content in the image or the final image size after any compression. The driver determines if it is blank on a per image basis. For example, if a Color and Black and White images are being created on the Front, it is possible that Front Color image will not be considered blank, but the Black and White image will be considered blank.

Blank image deletion, for a camera, can be turned on by setting CAP_BLANKPAGEMODE to TWBM_CONTENT (content based) or TWBM_COMPSIZE (final image size). It can be turned off by setting CAP_BLANKPAGEMODE to TWBM_NONE. However, blank page detection based on content is not available for all scanners.

When TWBM_CONTENT is selected, CAP_BLANKPAGECONTENT becomes available. CAP_BLANKPAGECONTENT is used to set the content percentage. If the image content is less or equal to the percent specified, the image will be deleted.

When TWBM_COMPSIZE is selected, CAP_BLANKPAGECOMPSIZEBW (Black and White image), CAP_BLANKPAGECOMPSIZEGRAY (Grayscale image) and CAP_BLANKPAGECOMPSIZERGB (Color image) are use to set the image size. If the final image size is less that the corresponding value, the image is deleted. For backward compatibility, the value CAP_BLANKPAGEMODE will be changed when any CAP_BLANKPAGECOMPSIZExxx is changed. If any value becomes non-zero, CAP_BLANKPAGEMODE will be set to TWBM_COMPSIZE. If all three values become zero, CAP_BLANKPAGEMODE well be set to TWBM_NONE.

Color Adjustments:

There are adjustments for Color/Grayscale outputs. These adjustments allow users to modify the overall Brightness, Contrast and Hue (red, green and blue) of their scanned documents; they are applied after the image has been color corrected. The user may also turn off color correction, including gamma correction (i.e. raw scanner image); the other adjustments are still applied.

All the possible adjustments are: Brightness, Contrast, Red, Green, Blue, and Raw. However, not all scanners support these.

Brightness and Contrast is controlled using ICAP_COLORBRIGHTNESSMODE.

TWCBR_NONE means no adjustment is made.

TWCBR_MANUAL means the user can adjust Brightness and Contrast (see ICAP_BRIGHTNESS and ICAP_CONTRAST).

TWCBR_AUTOMATICBASIC means the scanner will automatically adjust the image.

Brightness is controlled using ICAP_BRIGHTNESS. Increasing this will make documents appear to be lighter. This is ignored if ICAP_COLORBRIGHTNESSMODE is not set to TWCBR_MANUAL.

Contrast is controlled using ICAP_CONTRAST. Increasing this, for Color/Grayscale, will increase the image’s tonal range. This is ignored if ICAP_COLORBRIGHTNESSMODE is not set to TWCBR_MANUAL.

Color Balance is controlled using ICAP_COLORBALANCEMODE.

TWCBM_NONE means no adjustment is made.

TWCBM_MANUAL means the user can adjust Red, Green and Blue (see ICAP_COLORBALANCEREAD/GREEN/BLUE)

TWCBM_AUTOMATICBASIC means the scanner will automatically adjust the balance to be white.

TWCBM_AUTOMATIC is the same as TWCBM_AUTOMATICBASIC but the user can also adjust the aggressiveness of the balance (see ICAP_COLORBALANCEAUTOMATICAGRESSIVENESS)

The aggressiveness of the auto white is set using ICAP_COLORBALANCEAUTOMATICAGGRESSIVENESS. The higher the value, the more likely a pixel will be determined to be white.

Red, Green, and Blue are controlled using ICAP_COLORBALANCERED, ICAP_COLORBALANCEGREEN, and ICAP_COLORBALANCEBLUE; respectively. Increasing Blue, for example, will make the image appear bluer. This is ignored if ICAP_COLORBALANCEMODE is not set to TWCBM_MANUAL

Raw (i.e. no color/gamma correction) is controlled using ICAP_GAMMAENABLED.

Color Sharpening:

Apply ICAP_COLORSHARPEN to color and grayscale images: 0 indicates no sharpening. 1 is normal, 2 is more sharpening, and a value of 3 applies a lot of sharpening.

Document Type

If supported by the scanner, Document type indicates the type of content that is on the document. This is available for all outputs; however, for some scanners the selection needs to be the same for the Front and Back.

This is controlled using ICAP_DOCUMENTTYPE.

How to select the type:

------------------------------------------------------

If your documents contain a mix of text and business graphics (e.g. charts, graphs, etc), then select: TWDT_TEXTWITHGRAPHICS.

If your documents contain only text, then select: TWDT_TEXT.

If your documents contain mainly photographs, or you want the color correction optimized for photographs, then select: TWDT_PHOTO.

If, supported by the scanner and, your documents contain a mix of text and photographs, then select: TWDT_TEXTWITHPHOTO. If not supported, then TWDT_PHOTO or TWDT_TEXTWITHGRAPHICS is suggested.

NOTE: refer to the Color Table section of this guide for information on backward compatibility with color tables

Media Type

If supported by the scanner, Media type indicates the type of paper being scanned. This is available for all outputs; however, for some scanners the selection needs to be the same for the Front and Back.

This is controlled using ICAP_MEDIATYPE.

How to select the type:

------------------------------------------------------

If your documents are normal everyday paper (e.g. copier paper, inkjet paper, etc), then select: TWMT_PLAINPAPER.

If your documents are lightweight or thin (e.g. rice paper, ‘tissue’ paper, etc), then select: TWMT_THINPAPER.

If your documents are glossy (e.g. photographic paper), then select: TWMT_GLOSSYPAPER.

If your documents are magazine articles, then select: TWMT_MAGAZINE. If not supported, then TWMT_GLOSSYPAPER or TWMT_PLAINPAPER is suggested.

If your documents appear to be normal everyday paper but are thick (e.g. card stock), then select: TWMT_CARDSTOCK.

NOTE: unless otherwise specified, if the desired type is not supported by the scanner, then select TWMT_PLAINPAPER.

NOTE: refer to the Color Table section of this guide for information on backward compatibility with color tables

Color Tables

For scanners than now support Document Type (ICAP_DOCUMENTTYPE) and Media Type (ICAP_MEDIATYPE), Color Tables is only supported for backwards compatibility. That means selecting ICAP_COLORTABLE will still work, however it is highly recommend that code be setup to handle Document and Media Type.

For reference, the mapping between Color Tables and Document/Media Types is as follows:

--------------------------------------------------------------------------------------------

‘Mixed’ and ‘Text with Pictures’: TWDT_TEXTWITHGRAPHICS / TWMT_PLAINPAPER.

‘Photo’ and ‘Pictures’: TWDT_PHOTO / TWMT_GLOSSY.

‘Text’: TWDT_TEXT / TWMT_PLAINPAPER

Electronic Color Drop-Out (ECDO):

There are adjustments for Bitonal/Grayscale outputs. These adjustments allow users to select the ECDO color of their scanned documents.

The applications should only try to set the TWCD_FILE values. The DAT_ECDO operation for a way to map the display strings to the various ICAP_ECDO values.

ICAP_ECDOTREATASCOLOR allows you to indicate that a color other than black or dark blue ink was used for the data entered on the form. This not available on all scanner models or when ECDO is set to (none).

NOTE: refer to the ICAP_FILTERENUM section of this guide for information on backward compatibility with ECDO

Orthogonal Rotation:

This will rotate an image in 90 degree increments. The rotation occurs after the image has been cropped and/or deskewed.

This is set using ICAP_ROTATION to indicate the number of degrees.

Some scanners support Automatic orthogonal rotation. When set, the driver will automatically determine the degrees of rotation based on the content of the image. This is turned on by setting ICAP_AUTOMATICROTATE to true.

ICAP_ORTHOGONALROTATE is a custom capability. It’s a combination of ICAP_AUTOMATICROTATE and ICAP_ROTATION plus the TWOROT_AUTOMATIC_90 (or 180, 270). When ICAP_ORTHOGONALROTATE sets to TWOROT_AUTOMATIC_90 the driver uses auto-orient algorithm automatically determine orthogonal rotation. However, if the orientation cannot be determined, the image will be rotated 90 degrees.

For your reference, the following table shows the mapping between ICAP_ORTHOGONALROTATE and ICAP_AUTOMATICROTATE and ICAP_ROTATION.

ICAP_ORTHOGONALROTATE	ICAP_AUTOMATICROTATE	ICAP_ROTATION
TWOROT_NONE	False	0
TWOROT_90	False	90
TWOROT_180	False	180
TWOROT_270	False	270
TWOROT_AUTOMATIC	True	0
TWOROT_AUTOMATIC_90	True	0
TWOROT_AUTOMATIC_180	True	0
TWOROT_AUTOMATIC_270	True	0

Automatic Rotation:

If Automatic orthogonal rotation is supported (see Orthogonal Rotation) then the TWAIN feature Automatic Rotate is also supported (ICAP_AUTOMATICROTATE).

If ICAP_AUTOMATICROTATE is set to true, then ICAP_ROTATION is set to 0

ICAP_AUTOMATICROTATE will automatically be updated anytime ICAP_ROTATION is changed

Multifeed UDDS Sensors

The TWAIN driver provides the ability to detect a multifeed condition by setting the CAP_ULTRASONICSENSITIVITY to TWUS_LOW, TWUS_MEDIUM or TWUS_HIGH.

When CAP_ULTRASONICSENSITIVITY is not TWUSS_DISABLED, if supported, each sensor (CAP_ULTRASONICSENSOR*) can be individually turned on (TWUO_ENABLED) or off (TWUO_DISABLED). For scanners that support the “Ignore” feature, TWUO_IGNOREZONE can also be selected.
NOTE: at least one sensor must remain on.

When TWUO_IGNOREZONE is selected, the height of the area to be ignored is controlled by CAP_ULTRASONICSENSORZONEHEIGHT. This setting will apply to all sensors set to TWUO_IGNOREZONE.

Multifeed Response:

The Multifeed Response is used to indicate what action to take when a multifeed is detected by the scanner. This value is only available when multifeed detection is turned on (i.e. CAP_ULTRASONICSENSITIVITY is not set to TWUSS_DISABLED, or CAP_PAGESIZELIMIT is not zero).

Going forward CAP_MULTIFEEDRESPONSE should be used instead of the values: CAP_DOUBLEFEEDSTOP and CAP_DOUBLEFEEDENDJOB. These values don’t allow access to all the possible multifeed responses, but are left in for backwards compatibility. All three values will automatically be updated, to stay in sync, when any of them are changed.

For your reference, the following table shows the mapping between CAP_MULTIFEEDRESPONSE and CAP_DOUBLEFEEDSTOP and CAP_DOUBLEFEEDENDJOB.

CAP_DOUBLEFEEDSTOP	CAP_DOUBLEFEEDENDJOB	CAP_MULTIFEEDRESPONSE
True	True	TWMR_ENDOFJOB
True	True	TWMR_ENDOFJOBLEAVEPAPER
True	False	TWMR_STOPFEEDER
False	False	TWMR_CONTINUE

Image Edge Fill:

This feature fills the edges of the final electronic image by covering the area with the specified color. Use ICAP_IMAGEEDGEFILL to specify the color to fill with.

If scanner supported TWIE_AUTOMATIC and TWIE_AUTOMATICWITHTEAR the edge of an image is automatically filled in with the same color space as the image.

When TWIE_AUTOMATIC or TWIE_AUTOMATICWITHTEAR is selected the ICAP_CROPPINGMODE is automatically changed to TWCR_AUTOMATICBORDERDETECTION and the ICAP_AUTOMATICDESKEW is also changed to TRUE.

If the current value of ICAP_IMAGEEDGEFILL is TWIE_AUTOMATIC or TWIE_AUTOMATICWITHTEAR and ICAP_CROPPINGMODE is changed to not TWCR_AUTOMATICBORDERDETECTION or ICAP_AUTOMATICDESKEW is changed to FALSE then ICAP_IMAGEEDGEFILL is automatically changed to TWIE_NONE.

For the TWIE_WHITE and TWIE_BLACK, use ICAP_IMAGEEDGELEFT, ICAP_IMAGEEDGERIGHT, ICAP_IMAGEEDGETOP and ICAP_IMAGEEDGEBOTTOM to specify the amount of fill for each edge.

If you want all sides to be forced to have the same amount of fill, then set ICAP_IMAGEEDGEFILLALLSIDES to True. The driver uses the value for the top edge (ICAP_IMAGEEDGETOP) as the size of the fill for the other three edges. In addition, the left (ICAP_ IMAGEEDGELEFT), right (ICAP_ IMAGEEDGERIGHT), and bottom (ICAP_ IMAGEEDGEBOTTOM) edge will have read-only access since their values are automatically set to match the top edge.

Sides Different:

The purpose of Sides Different allows the user to determine if Front and Rear values need to be the same or not.

When CAP_SIDESDIFFERENT is changed to False (i.e. transitioned from True to False), the driver will make the sides the same by copying all the Front camera settings to the Rear camera. While CAP_SIDESDIFFERENT is False, any value that is set on the current camera (e.g. Front) will automatically be set on the opposite camera (e.g. Rear).

When CAP_SIDESDIFFERENT is set to True, the driver would then allow different values for the Front and Rear camera. Realize that when CAP_SIDESDIFFERENT has a value of True, the values for Front and Rear may not actually be different. This would be the case when Sides Different is first set to True (i.e. transitioned from False to True), and no other values have been changed.

Device Events:

Applications can register for device events by issuing a CAP_DEVICEEVENT for events the driver wants to receive. For a list of supported events for each scanner model, refer to kdscust.h.

Applications are notified of device events via DG_CONTROL / DAT_NULL / MSG_DEVICEEVENT. Upon receiving a MSG_DEVICEEVENT, the application must immediately issue a DG_CONTROL / MSG_DEVICEEVENT / MSG_GET to obtain the event information.

TWDE_LAMPWARMUP

For version 9.3 drivers and up, the application can ask the driver to send this custom CAP_DEVICEEVENT if the lamps need to warmup prior to scanning. This event will be issued after a MSG_ENABLEDS if the lamps are not warmed up. The number of seconds before the lamps are ready will be in the TimeBeforeFirstCapture field of the TW_DEVICEVENT structure.

NOTE: The number of seconds may be longer than what it actually take. This could happen because an error occurred (e.g. opening cover, cancelling) or for models that do not have an accurate warmup value. Because of this, if your application is displaying a “please wait” message for the user, the message needs to be closed when MSG_XFERREADY is received.

Blank Image Deletion:

Getting Logs Programmatically:

This feature allows the user to retrieve logs. There are text based logs, XML based logs and EKLOG package files. A log is retrieved by issuing a DG_CONTROL/DAT_LOG/MSG_GET with a properly filled in TW_LOG structure. Fill in a TW_LOG structure with the desired log (LogType), the desired device (DeviceType), and the full path and name of the file (Filename) to store the log data into.

For all scanners, set DeviceType to TWDV_ADF to get the base scanners information. For those scanners that support the flatbed as an accessory (e.g. i1200, i1300, i1400), you will need to make a second call, with DeviceType set to TWDV_FLATBED, to get the flatbed’s information. This is necessary because the flatbed is a separate device.

DAT_LOG will return TWRC_FAILURE/TWCC_OPERATIONERROR if a request is made for a log that is not supported by the scanner (e.g. not all scanners have an operator log).

DAT_LOG will return TWRC_FAILURE/TWCC_BADVALUE if the DeviceType is TWDV_FLATBED and there is no separate flatbed scanner (e.g. i1000A4 & i1000A3) attached. Since this is the only case when this error code is returned, applications could make use of this by always issuing the second DAT_LOG call and let this be the way to know there is no separate flatbed scanner attached.

The text based logs are ones that can be easily viewed in something like Notepad, each log entry will be on its own line. These logs contain the same information as is shown on the driver UI on the Log tab. The language for the translated text will be based on the current language selected for the driver. The format of each log entry is not guaranteed, so you should never parse the entries to get information.

The XML based logs are designed to be flexible across scanners and to allow for future expansion. The following notes apply to the XML based logs:

Not all fields may be returned for each scanner. For example, rear lamp-on hours would not be returned for a simplex scanner; patch counts would not be returned on a scanner that does not support patch reading; and versions will only be returned for the items that the scanner actually has. Therefore, it is the responsibility of the application to handle tags not being there.
The order of the tags is not guaranteed. Therefore it is the responsibility of the application to parse the entire XML.
The character format for the entire XML is UTF-8
The spacing shown below is for clarity; it may or may not be as shown. It is the responsibility of the application to handle variable spacing.

The possible logs (LogType) are:

TWGL_GENERAL: this returns the text based log called General on the driver UI. This log is not common among scanner families.
TWGL_OPERATOR: this returns the text based log called Operator on the driver UI. This log is not common among scanner families.
TWGL_GENERAL_XML: this returns a XML based log that contains information typically found in the General log: model, serial number, versions, meters, etc.
TWGL_EKLOG: returns an EKLOG package file for Service (the same kind of file that can be generated from the TWAIN User Interface); when using this type be sure to offer a description of the log (why it’s being sent), and set SaveImages to TRUE if delivering device or application images with the package. This is not a viewable log.

The XML format of the TWGL_GENERAL_XML log is as follows. Included are examples of what the tag values could be. The text to the right of the tags is a description of what the tag is (the numbers in parenthesis refer to the tag notes below. The descriptions will not appear in the log file:

<tw_log>

<cdname> KODAK i1210/i1220 Scanner</cdname> Family name from CD

<modelname>i1220</modelname> name of scanner model

<versioncd>1.25</versioncd> CD version

<versiontwain>9.64</versiontwain> TWAIN driver version

<versionui>3.23</versionui> TWAIN UI version

<flatbed>false</flatbed> flatbed attached (1)

<printer>false</printer> printer accessory available (1)

<background>black</background> front camera’s background color (2)

<backgroundrear>black</backgroundrear> rear camera’s background color (2)

<connection>USBSCAN 2.0</connection> interface scanner is connected to (3)

<serialnumber>1234567890</serialnumber> scanner’s serial number

<versionfirmware>1.43</versionfirmware> scanner firmware version

<versionhippo>4.5.1</versionhippo> image processing version

<versiondriver>2.3</versiondriver> driver.dll version

<versiondevice>2.10</versiondevice> device.dll version

<versiondevicemanager>1.1</versiondevicemanager> devicemanager.dll version

<meterpower>104</meterpower> time scanner has been on (4)

<metertransport>99</metertransport> time transport has been on (4)

<meterlampfront>104</meterlampfront> time front lamps have been on (4)

<meterlamprear>100</meterlamprear> time rear lamps have been on (4)

<meterfirstscan>2008/12/03 15:58:44.245</meterfirstscan> time & date of first scan (5)

<meterpagecount>5</meterpagecount> number of pages scanned

<multifeedcount>0</multifeedcount> # multifeeds seen (6)

<patchcountfront>0</patchcountfront> # patches seen on the front (6)

<patchcountrear>0</patchcountrear> # patches seen on the rear (6)

</tw_log>

Tag Notes:

The values for this tag are: true and false. If this tag is not present, then assume the value is false.
The values for this tag are: black, white and switchable. If this tag is not present, then assume the background is black.
Typical values will be: USBSCAN 2.0, USBSCAN 1.1, and SCSISCAN (for 1394 devices).
This tag will contain the number of hours in tenths. For example, a value of 104 equates to 10.4 hours.
This tag will contain a zero-filled date and time with the format: YYYY/MM/DD[space]HH:MM:SS.mmm
This count is based on what occurred during the previous scan session. This value is reset to zero at the start of every scan session.

Combine/Merge Front and Back Images:

This feature allows the user to instruct the driver to combine the front and back images from a document into a single image. This feature is designed for use with Duplex scanning from the document feeder, where there is one image per side and the front and back camera settings are the same. For example: CAP_DUPLEXENABLED set to True; Sides Different (CAP_SIDESDIFFERENT) is False; one camera per side has been enabled (i.e. just Color, or just Grayscale, or just Black and White).

This feature is only available for duplex scanner models. Even if this is turned on, the images will not be combined if more than one camera per side is enabled or the flatbed is scanned.

When this feature is on, the application will receive one image that contains both the front and the back of the page; instead of one image for the front and another image for the rear. If the final image has the original images one on top of the other (e.g. front on top of back), then the width of the final image will be based on the wider of the two original images. If the final image has the original images one to the left of the other (e.g. front to the left of the back), then the height of the final image will be based on the taller of the two original images. Any area that needs to be filled in (i.e. any padding of the narrower or shorter image) will be based on the color of the camera’s background. For example, if the camera’s background is black, then the image will be padded with black.

This feature can be turned on by setting CAP_IMAGEMERGE to a value other than TWIM_NONE. The valid choices are: TWIM_FRONTONTOP (front is on top of the back), TWIM_FRONTONBOTTOM (back is on top of front), TWIM_FRONTONLEFT (front is to the left of the back), and TWIM_FRONTONRIGHT (back is to the left of the front).

Feeder Mode

This allows you to select how the scanner transports documents through the scanner. This affects how the documents are fed into the scanner, how fast they move through the scanner, and how they are placed in the output tray.

The available enumerations for this capability, ICAP_FEEDERMODE, are different based on scanner and defined as follows:

· TWFM_NONE: No additional handling is performed. Best used when all documents are similar in size.

· TWFM_STACKINGIMPROVED: Aids in controlling how the documents are stacked/ordered in the output tray for mixed document sets. This should work for the majority of mixed sets.

· TWFM_STACKINGBEST: When your document set contains a great variability in size, this option provides the best control of how the documents are stacked/ordered within the output tray.

· TWFM_SPECIAL: For irregularly shaped documents (e.g., pages with coupons removed or documents with large holes or cutouts in them).

· TWFM_FRAGILE: For documents that need extra care as they are transported through the scanner and placed in the output tray.

· TWFM_THICK: For thick documents.

Controlled Dual Stacking Accessory

If you have the Controlled Dual Stacking Accessory installed, then you can separate documents into the two stacks of the Dual Stacking Accessory output tray. Separation of documents will be possible via any combination of document length, document content (toggle patch), and multifeed detection.

The first step is to turn on the feature by setting the following CAP:

· CAP_DUALSTACKINGENABLED - Set to TRUE to enable the Controlled Dual Stacking Accessory

Next, determine which stack of the output tray to place detected documents into by setting the following CAP.

· CAP_DUALSTACKINGSTACK - If CAP_DUALSTACKINGSTACK is set to TWDSS_STACK1, then documents that match any of the defined detection settings will be separated from the document set and placed in stack 1. All other documents will be placed in stack 2.

- If CAP_DUALSTACKINGSTACK is set to TWDSS_STACK2, then documents that match any of the defined detection settings will be separated from the document set and placed in stack 2. All other documents will be placed in stack 1.

Next, define the document detection criteria. Separation of documents will be possible via any combination of document length, document content (toggle patch), and multifeed detection.

If you would like to select which documents to separate from the document set based on the document's length, then you would set the following CAPs:

· CAP_DUALSTACKINGLENGTHMODE - Set to TWDSLM_LESSTHAN, TWDSLM_GREATERTHAN, or TWDSLM_BETWEEN

· CAP_DUALSTACKINGLENGTH1 - If CAP_DUALSTACKINGLENGTHMODE is set to TWDSLM_LESSTHAN, then any documents shorter than this length will be separated and placed in the selected CAP_DUALSTACKINGSTACK.

- If CAP_DUALSTACKINGLENGTHMODE is set to TWDSLM_GREATERTHAN, then any documents longer than this length will be separated and placed in the selected CAP_DUALSTACKINGSTACK.

- If CAP_DUALSTACKINGLENGTHMODE is set to TWDSLM_BETWEEN, then any documents whose length falls between CAP_DUALSTACKINGLENGTH1 and CAP_DUALSTACKINGLENGTH2 will be separated and placed in the selected CAP_DUALSTACKINGSTACK.

· CAP_DUALSTACKINGLENGTH2 - If CAP_DUALSTACKINGLENGTHMODE is "between", then any documents whose length falls between CAP_DUALSTACKINGLENGTH1 and CAP_DUALSTACKINGLENGTH2 will be separated and placed in the selected CAP_DUALSTACKINGSTACK.

If you would like to select which patch sheets, if any, to separate from the document set and place in the selected stack, then you would set the following CAPs:

· CAP_DUALSTACKINGPATCHTRANSFER - Set to TRUE will place Patch Type Transfer sheets in the selected CAP_DUALSTACKINGSTACK.

· CAP_DUALSTACKINGPATCHTYPE1 - Set to TRUE will place Patch Type 1 sheets in the selected CAP_DUALSTACKINGSTACK.

· CAP_DUALSTACKINGPATCHTYPE2 - Set to TRUE will place Patch Type 2 sheets in the selected CAP_DUALSTACKINGSTACK.

· CAP_DUALSTACKINGPATCHTYPE3 - Set to TRUE will place Patch Type 3 sheets in the selected CAP_DUALSTACKINGSTACK.

· CAP_DUALSTACKINGPATCHTYPE4 - Set to TRUE will place Patch Type 4 sheets in the selected CAP_DUALSTACKINGSTACK.

· CAP_DUALSTACKINGPATCHTYPE6 - Set to TRUE will place Patch Type 6 sheets in the selected CAP_DUALSTACKINGSTACK.

NOTE: You can select any combination of the above Patch Types.

If you would like to separate all documents that are determined to have been multifed, then you would set the following CAPs:

· CAP_DUALSTACKINGMULTIFEED - Set to TRUE will place documents that are determined to have been multifed in the selected CAP_DUALSTACKINGSTACK

Background

This will allow the user to select the color of the imaging background. This can be set differently per side.. The imaging background is what the scanner will see where there is no paper.

Use CAP_BACKGROUND to set the background color to white (i.e. TWBK_WHITE) or Black (i.e.TWBK_BLACK),

Examples of when the white background is useful are:

· Scanning non-rectangular documents and, in the final image, you want the area outside the document to be White instead of Black.

· Scanning lightweight or thin paper, with printing on one side, and you do not want the black background to bleed through the document and appear in the final image.

Physical Height Adjust

For scanners that support this setting, it is provided as a way to optimize throughput. It limits the maximum document length that the scanner can scan. So while the scanner is capable of scanning longer documents, it will not process any documents that are longer then this setting. Setting this to larger lengths may reduce the scanner’s throughput. For example, the scanner may be able to scan up to an 80 inch long document (i.e. the range maximum would be 80 inches), but if the default for this setting is 17 inches then the scanner will stop if something longer than 17 inches is scanned. To scan something longer than the default, this capability will need to be modified.

The range for this setting is determined by the scanner; therefore it should be read when connecting to the scanner. An example range is 2.5” to 3 meters.

When this capability, ICAP_PHYSICALHEIGHTADJUST, is modified the maximum paper size (i.e. ICAP_PHYSICALHEIGHT) will be impacted as well as any settings based on that (e.g. ICAP_SUPPORTEDSIZES, ICAP_FRAMES, CAP_PRINTERPOSITION, CAP_PAGESIZELIMIT). Therefore, it is recommended to re-read those values as appropriate.

NOTE: Some combinations of ICAP_PIXELTYPE and ICAP_XRESOLUTION may not be supported by the scanner when this capability is set to larger values. Instead of preventing these values from being set, and to allow for greater flexibility with applications, the scanner will not generate an error until it scans a document whose length is not supported.

OCP Buttons:

This feature allows the application to set the displayed text on the OCP for each button. The driver may not remember this information. So we recommend that the application should send the text after successfully MSG_OPENDS. The maximum number of buttons that are allowed to be configured is 9.

To configure the number of buttons for the user to scroll through, the App must send an array of TW_OCPBUTTONS structures which has the number of the buttons defined plus an extra one that has Text field blank. For example, if the user wants to setup the text for 3 buttons then define the array of 4 TW_OCPBUTTONS structures. Set the Text for the first 3 items and set the Text to blank for the 4th.

For the scanners that don’t have the ability to display the text, the application still can configure the number of buttons for the user to scroll through.

The order of the buttons displayed on the OCP is the same order of the buttons defined in the array.

The Text is in the current language. The Ansi code page which is based on the CAP_LANGUAGE is used for the conversion.

NumDataFields indicates how many fields, after it and before Reserved, are filled in by the application.

PaperSource is used to indicate which Paper Source the button will scan from. Set it to the desired TWPU_* value. Refer to CAP_PAPERSOURCE for a list of TWPU_* values. For example, if setting a button to "Color PDF" and the paper source is "Document Feeder", then set:

Text = "Color PDF"

NumDataFields = 1

PaperSource = TWPU_ADF

NOTE: Not all scanners make use of PaperSource

The Reserved field must be initialized to zero.

Hole Fill:

The Hole Fill feature is designed to remove “punch holes” in the original document from the resultant image. The output image is the same as the input image with the identified “holes” in the document image filled in with background. In the Bitonal case the background is white.

This feature can be turned on by setting ICAP_HOLEFILLENABLED to TRUE.

Streak Filter:

The Streak Filter Fill feature is designed to remove “streaks” in the original document from the resultant image. The amount of "aggressiveness" that the Streak Filter algorithm applies can be adjusted as needed.

This feature can be turned on by setting ICAP_STREAKREMOVALENABLED to TRUE.

The amount of aggressiveness can be adjusted by setting ICAP_STREAKREMOVALAGGRESSIVENESS to a value ranging from -2 to 2 in steps of 1; the default is 0. This value does not apply if ICAP_STREAKREMOVALENABLED is FALSE.

Cropping Mode:

This feature allows the user to specify how the scanner will detect document as it is being fed through the scanner.

The available enumerations for this capability, ICAP_CROPPINGMODE, are different based on scanner and defined as follows:

· TWCR_AUTOMATICBORDERDETECTION: The scanner will automatically find each document (regardless of size).

· TWCR_TRANSPORT: The scanner will return an image based on the area you specify in the ICAP_FRAMES or ICAP_FRAMESANGLE. It is suggested that you only use this option for scan jobs that contain same-sized documents.

· TWCR_DOCUMENT: The scanner will return an image based on the area you specify in the ICAP_FRAMES or ICAP_FRAMESANGLE which is relative to entire document.

· TWCR_AGGRESSIVEAUTOCROP: The scanner will automatically find each document and will straighten any document that may have been fed crooked. It’s also eliminating any residual border. Residual border can be caused by variations in a document edge; for example, when a document is not a perfect rectangle and/or was fed crooked.

· TWCR_CONTINUOUS: The scanner will split the document into separate images based on the area you specify with the ICAP_FRAMES or ICAP_FRAMESANGLE. It is suggested that you select an area that covers the entire width of the document and a height around 11 inches (297 mm).

· TWCR_PHOTO: The scanner will locate the photograph on the document and return an image that contains just the photograph. If the scanner finds more than one photograph on a document, one image is still returned which contains all photographs.

· TWCR_PHOTOINROI: The scanner will locate the photograph on the area you specify in the ICAP_FRAMES or ICAP_FRAMESANGLE and return an image that contains just the photograph. If the scanner finds more than one photograph on a specify area, one image is still returned which contains all photographs.

When TWIE_AUTOMATIC or TWIE_AUTOMATICWITHTEAR is selected from ICAP_IMAGEEDGEFILL the ICAP_CROPPINGMODE is automatically changed to TWCR_AUTOMATICBORDERDETECTION and the ICAP_AUTOMATICDESKEW is also changed to TRUE.

When the ICAP_CROPPINGMODE value is changed other capabilities are also changed. The following table shows the mapping between ICAP_CROPPINGMODE and ICAP_AUTOMATICDESKEW and ICAP_IMAGEEDGEFILL

ICAP_CROPPINGMODE	ICAP_AUTOMATICDESKEW	ICAP_IMAGEEDGEFILL (If current value is TWIE_AUTOMATIC or TWIE_AUTOMATICWITHTEAR)
TWCR_AUTOMATICBORDERDETECTION	TRUE	No change
TWCR_TRANSPORT	FALSE	TWIE_NONE
TWCR_DOCUMENT	TRUE	TWIE_NONE
TWCR_AGGRESSIVEAUTOCROP	TRUE	TWIE_NONE
TWCR_CONTINUOUS	FALSE	TWIE_NONE
TWCR_PHOTO	TRUE	TWIE_NONE
TWCR_PHOTOINROI	TRUE	TWIE_NONE

Foreground Boldness:

Use this option for documents or forms where you want the foreground (e.g. text, lines, etc.) to be more prominent.

Foreground Boldness is only available for Color/Grayscale output.

The available enumerations for this capability, ICAP_FOREGROUNDBOLDNESSMODE are defined as follows:

· TWFB_NONE: No Foreground Boldness is applied to the image.

TWFB_AUTOMATICBASIC: All foreground will be bolder.

TWFB_AUTOMATIC: For advanced users that want to further adjust the aggressiveness of the Foreground Boldness algorithm.

The aggressiveness of the Foreground Boldness algorithm is selected using ICAP_FOREGROUNDBOLDNESSAGGRESSIVENESS. The higher the value, the more boldness is applied to the image foreground. This is available only when ICAP_FOREGROUNDBOLDNESSMODE is set to TWFB_AUTOMATIC.