Setting and Retrieving OCR Capabilities

Similar to TWAIN device capabilities, an OCR engine also has capabilities that can be queried and set.

The capabilities of an OCR engine are the various aspects of the OCR engine that can be changed or queried.  For example, the supported image file formats that the OCR engine recognizes, the file format to use when running the OCR engine against an image, the supported bit depths and color types of the image that the OCR supports, etc.

This technique of using capabilities minimizes the amount of custom coding you would need to do to support multiple OCR engines.  For the most part, a single code base will work for all OCR engines.

Once an OCR engine has been selected, the capabilities of the OCR engine can be queried or set.

As an example, let's retrieve all of the supported image file formats that the OCR engine recognizes as valid file types (for example, the eligible file types that can be processed by the OCR engine could be TIFF with no compression and BMP).

Here is code that selects the default OCR engine, and queries the OCR engine for all of the supported image file formats the engine will recognize, and checks if BMP is supported.

  LONG nFormats;

  int isSupported = 0;

  /* Initialize DTWAIN Library */

  DTWAIN_SysInitialize( );

  /* Initialize the OCR interface */

  DTWAIN_InitOCRInterface( );

  /* Select the default OCR engine */

   DTWAIN_OCRENGINE SelectedEngine = DTWAIN_SelectDefaultOCREngine( );

   if ( SelectedEngine != 0 )

   {

       /* Get the supported image file formats */

       DTWAIN_ARRAY aImageFormats;

      DTWAIN_GetOCRCapValues( SelectedEngine, DTWAIN_OCRCV_IMAGEFILEFORMAT, DTWAIN_CAPGET, &aImageFormats );

       /* display the formats */

       nFormats = DTWAIN_ArrayGetCount( aImageFormats );

       if ( nFormats > 0 )

       {

            LONG i;

            LONG imageFormat;

            for ( i = 0; i < nFormats; ++i )

            {

                DTWAIN_ArrayGetAtLong( aImageFormats, i, &imageFormat );

                printf( "supported format %d: %d\n", i+1, imageFormat );

            }

            /* See if DTWAIN_BMP is in the list of supported types */

           LONG nPos = DTWAIN_ArrayFindLong( aImageFormats, DTWAIN_BMP );

           if ( nPos >= 0 )

                 /* DTWAIN_BMP is supported */

                isSupported = 1;

       }

      DTWAIN_ArrayDestroy( aImageFormats );

   }

Note that the DTWAIN_GetOCRCapValues( ) function retrieves the capabilities of the OCR engine, all depending on which capability is being used to retrieve, and the retrieval mode.  The capability is the second parameter (in the example above, it is DTWAIN_OCRCV_IMAGEFILEFORMAT).  The retrieval mode is DTWAIN_CAPGET, which means to retrieve all of the available image file formats.

On return, the DTWAIN_ARRAY, aImageFormats is filled with the image file formats.  The image file formats are equivalent to the constants used by DTWAIN when acquiring to a file (for example DTWAIN_BMP, DTWAIN_TIFFNONE, etc.).  A list of those constants are found here.

Let's take the previous example, and set the file type that is to be used by setting the capability.

if ( isSupported )

{

   DTWAIN_ARRAY aSetImage = DTWAIN_ArrayCreate(DTWAIN_ARRAYLONG, 1);

  DTWAIN_ArraySetAt( aSetImage, 0, DTWAIN_BMP );

  DTWAIN_SetOCRCapValues( Selected, DTWAIN_OCRCV_IMAGEFILEFORMAT, DTWAIN_CAPSET, aSetImage );

  DTWAIN_ArrayDestroy( aSetImage );

}

The code above creates a DTWAIN_ARRAY that can hold one value, and sets the one value to DTWAIN_BMP.  Then the call to DTWAIN_SetOCRCapValues sets the capability specified (DTWAIN_OCRCV_IMAGEFILEFORMAT) using the values in aSetImage (which is only one value).

Going one step further, let's see what happens if we query the current setting of the image file format:

LONG curValue;

DTWAIN_GetOCRCapValues( SelectedEngine, DTWAIN_OCRCV_IMAGEFILEFORMAT, DTWAIN_CAPGETCURRENT, &aImageFormats);

DTWAIN_ArrayGetAtLong( aImageFormats, 0, &curValue );

The curValue should equal DTWAIN_BMP, since we set the current image format to DTWAIN_BMP in the previous code snippet.

So basically, the two functions that are important are:

DTWAIN_GetOCRCapValues

DTWAIN_SetOCRCapValues

These functions work very similar to DTWAIN_GetCapValues and DTWAIN_SetCapValues when getting/setting device capabilities.