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_BOOL DTWAIN_SetBlankPageDetection (
Parameters Source A DTWAIN_SOURCE denoting a TWAIN Source.
threshold Sets the percentage of white pixels to black pixels to determine if a page is blank.
options Sets the auto-discard options when processing blank pages.
bEnable Enables/disables the blank page processing mechanism.
Return Values The return value is TRUE if successful. Otherwise FALSE is returned.
Comments 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 Source is the DTWAIN_SOURCE that will be used when setting the mode.
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.
Notifications sent to application 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.
Examples: DTWAIN_SOURCE Source; /* ... */ /*1)*/ DTWAIN_SetBlankPageDetection( Source, 98.0, DTWAIN_BP_AUTODISCARD_NONE, TRUE ); /*2)*/ DTWAIN_SetBlankPageDetection( Source, 98.5, DTWAIN_BP_AUTODISCARD_ANY, TRUE ); /*3)*/ DTWAIN_SetBlankPageDetection( Source, 0.0, 0, FALSE );
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.
Limitations Please note that DTWAIN_SetBlankPageDetection currently has the following limitations:
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.
TWAIN State Transitions None
Prerequisite Function Call(s) DTWAIN Source Selection Function
See Also |