DTWAIN_SetBlankPageDetection

The DTWAIN_SetBlankPageDetection function allows detection of blank pages when acquiring from a TWAIN device, and optionally allows automatic discarding of blank pages.

DTWAIN_SOURCE	Source,
DTWAIN_FLOAT	threshold,
LONG	options,
DTWAIN_BOOL	bEnable );

Sets the percentage of white pixels to black pixels to determine if a page is blank.

The DTWAIN_SetBlankPageDetection function allows DTWAIN to determine if an acquired page is blank. If the page is determined to be blank, DTWAIN can automatically discard the page (i.e. not have it sent to the application), or DTWAIN can inform your application that an acquired page is blank, and your application can decide to discard the page.

The threshold parameter is the percentage that is used by DTWAIN to determine if a page is blank. This percentage is based on the ratio of the number of white pixels to dark or black pixels. For most cases, a threshold value of 98.5 to 99 percent is needed for proper blank page detection. If your application considers dark or totally black pages as blank, then the threshold should be closer to 0% instead of 100%.

The options sets the "auto-discard" feature, where DTWAIN will automatically discard blank pages when they are detected. The options parameter can be one or a combination of the following:

DTWAIN_BP_AUTODISCARD_NONE - This option turns off the auto-discard feature. In this case, DTWAIN will send a notification to your application that a blank page has been detected, and your application can decide to discard the page or not. Your application will get a notification immediately after the page has been acquired from the device, and once again after DTWAIN does post-processing on the returned image (for cropping, resampling, etc.). See later on in this topic on the notifications that are sent to your application when a blank page is detected.

DTWAIN_BP_AUTODISCARD_IMMEDIATE - This option will automatically discard blank pages that are immediately returned from the device. The bitmap that is immediately returned has not been cropped or resampled by DTWAIN, but is the raw image that has been acquired from the device.

DTWAIN_BP_AUTODISCARD_AFTERPROCESS - This option will automatically discard blank pages after they have been possibly cropped and resampled by DTWAIN. For example, if you have called DTWAIN_SetAcquireArea2, DTWAIN needs to crop the image after it has been acquired from the device. If after the image has been cropped internally by DTWAIN, the resulting image is blank, then the page is blank.

DTWAIN_BP_AUTODISCARD_ANY - Combines DTWAIN_BP_AUTODISCARD_IMMEDIATE and DTWAIN_BP_AUTODISCARD_AFTERPROCESS options.

The bEnable option turns on or off the blank page detection. If bEnable is TRUE, then the blank page detection is turned on, else if bEnable is FALSE, the blank page detection is disabled.

The following notifications are sent to your application when a blank page is detected, and the blank page detection has been turned on:

DTWAIN_TN_BLANKPAGEDETECTED1 - This notification is sent to your application when the initial page that is returned from the TWAIN device is blank. If you have DTWAIN_BP_AUTODISCARD_NONE in your option argument when calling DTWAIN_SetBlankPageDetection, your notification handler must return either 0 to discard the page, or 1 to keep the page. If you used any other option argument when DTWAIN_SetBlankPageDetection was called (i.e. the DTWAIN_BP_AUTODISCARD_IMMEDIATE or DTWAIN_BP_AUTODISCARD_AFTERPROCESS option(s)), then the return value from this notification is ignored by DTWAIN, and the page is automatically discarded.

DTWAIN_TN_BLANKPAGEDETECTED2 - This notification is sent to your application when the page has been adjusted (either cropped, resampled, etc.) by DTWAIN. If you have DTWAIN_BP_AUTODISCARD_NONE in your option argument when calling DTWAIN_SetBlankPageDetection, your notification handler must return either 0 to discard the page, or 1 to keep the page. If you used any other option argument when DTWAIN_SetBlankPageDetection was called (i.e. the DTWAIN_BP_AUTODISCARD_IMMEDIATE or DTWAIN_BP_AUTODISCARD_AFTERPROCESS option(s)), then the return value from this notification is ignored by DTWAIN, and the page is automatically discarded.

DTWAIN_TN_BLANKPAGEDISCARDED1 - This notification is sent to inform your handler that the initial page that was returned from the TWAIN device has been discarded. The return value from this notification should always be 1.

DTWAIN_TN_BLANKPAGEDISCARDED2 - This notification is sent to inform your handler that the DTWAIN-adjusted page has been discarded. The return value from this notification should always be 1.

/*1)*/ DTWAIN_SetBlankPageDetection( Source, 98.0, DTWAIN_BP_AUTODISCARD_NONE, TRUE );

/*2)*/ DTWAIN_SetBlankPageDetection( Source, 98.5, DTWAIN_BP_AUTODISCARD_ANY, TRUE );

The first call 1) to DTWAIN_SetBlankPageDetection allows DTWAIN to detect blank pages, and will send the DTWAIN_TN_BLANKPAGEDETECTED1 and DTWAIN_TN_BLANKPAGEDETECTED2 notifications to the application when a blank page is detected. The application is then responsible for returning 0 or 1 from each of these notifications, depending on whether the page should be discarded or kept.

The second call, 2), allows DTWAIN to automatically discard blank pages when a blank page is detected immediately after the page is acquired, or after DTWAIN has finished processing the file. Both DTWAIN_TN_BLANKPAGEDETECTED1 and DTWAIN_TN_BLANKPAGEDETECTED2 notifications are sent to the application, however no action needs to be taken by the application when processing these notifications.

The third call, 3), turns off blank page detection, since the last parameter is FALSE.

If job control is also enabled, and the job relies on blank pages as job separation pages, then a combination of having DTWAIN remove blank pages and job control may produce undesired effects. Therefore it is recommended not to automatically discard blank pages if blank pages are also used to separate jobs.

Please note that DTWAIN_SetBlankPageDetection currently has the following limitations:

•	Detecting and discarding blank pages has full support when using DTWAIN_AcquireNative, DTWAIN_AcquireNativeEx, or DTWAIN_AcquireToClipboard functions. There are no limitations when using these functions.

•

Detecting and discarding blank pages has partial support for DTWAIN_AcquireBuffered and DTWAIN_AcquireBufferedEx. The compression type must be in DIB format (not TIFF, JPEG, or any other compression type that your TWAIN device may support) to guarantee that blank pages can be detected. To ensure that DIB's are acquired, your application can call DTWAIN_SetCompressionType using DTWAIN_CP_NONE as the compression type.

•	Detecting and discarding blank pages has full support when using DTWAIN_AcquireFile and DTWAIN_AcquireFileEx only when the DTWAIN_USESOURCEMODE flag is not set when calling DTWAIN_AcquireFile or DTWAIN_AcquireFileEx. See DTWAIN_AcquireFile for more information on the various flags.

For languages that have difficulties with DTWAIN_FLOAT parameters, the alternate function that can be used as a replacement for DTWAIN_SetBlankPageDetection is DTWAIN_SetBlankPageDetectionString.