#include "ltocr.h"

L_LTOCR_API L_INT EXT_FUNCTION L_OcrPage_Recognize(page, callback, userData)

L_OcrPage page; handle to the OCR page
L_OcrProgressCallback callback; optional callback to show operation progress.
L_VOID* userData; optional user data to pass to the callback function

Recognizes the OCR data found on this L_OcrPage.

Parameter Description
page Handle to the OCR page.
callback Optional callback to show operation progress.
userData Optional user data to pass to the callback function.


SUCCESS The function was successful.
< 1 An error occurred. Refer to Return Codes.


Perform image pre-processing by calling the L_OcrPage_AutoPreprocess method prior to calling L_OcrPage_Recognize.

If the page zones of this L_OcrPage is empty (i.e. there are no zones defined), then the page-layout decomposition process will be activated automatically in order to create a zone list for the bitmap before recognition. Hence, L_OcrPage_AutoZone will be implicitly called.

This method uses the checking subsystem (IOcrSpellCheckManager) to either flag suspicious characters or words, or to allow auto-correction during the recognition process.

After having recognized all the zones on the page, L_OcrPage_Recognize stores the necessary information about the recognized characters internally. You can later use the L_OcrDocument to save the data to a file using the many formats supported by this L_OcrEngine such as Text, PDF or Microsoft Word.

To recognize a multi-page document you can iterate through the pages of the L_OcrDocument object and call Recognize on each page in case the OCR document is of memory-based type, otherwise you have to recognize the page before you add it to the L_OcrDocument.

You can use the L_OcrProgressCallback to show the operation progress or to abort it. For more information and an example, refer to L_OcrProgressCallback.

Since the format of the recognized data file is not documented, you can use L_OcrPage_GetRecognizedCharacters and L_OcrPage_SetRecognizedCharacters to examine or modify the data. Any changes you make to the recognition data will be saved in the result document when you save L_OcrDocument.

After the page is successfully recognized, if you tried and called L_OcrPage_IsRecognized method then it should update its 'value' parameter with L_TRUE.

Use L_OcrPage_Unrecognize to clear the recognition data stored in a page.

If you are only interested in the recognition data as text (in other words, you are not planning to save the result document to disk), then you can use the L_OcrPage_GetText method and obtain the result data as a string. A common technique in OCR is to perform form processing by adding a zone manually around the required "field" and calling L_OcrPage_GetText to get the string value of the field.

Since the recognition algorithm may use the checking subsystem, you must set up the L_OcrSpellCheckManager prior to calling L_OcrPage_Recognize.

To get the accuracy and timing data of the latest successful recognition process use L_OcrPage_GetRecognizeStatistics after calling L_OcrPage_Recognize.

Note on AutoZone/Recognize and the page image: In certain cases, L_OcrPage_AutoZone and L_OcrPage_Recognize will perform image processing on the page that might result in the page being manipulated. For example, if you add a zone of type table, the engine might automatically deskew the page if required. This result in the image representation of the image to be different after L_OcrPage_AutoZone or L_OcrPage_Recognize is called. If your application has a requirement to view the bitmap of the page, then call L_OcrPage_GetBitmap after L_OcrPage_AutoZone or L_OcrPage_Recognize to get the latest version of the bitmap representation of the page in case it has changed. The LEADTOOLS OCR Module - LEAD Engine demo for C API do exactly that.

Required DLLs and Libraries

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

See Also

Functions: L_OcrPage_Destroy, L_OcrPage_FromBitmap, L_OcrPage_GetBitmap, L_OcrPage_SetBitmap, L_OcrPage_GetOverlayBitmap, L_OcrPage_SetOverlayBitmap, L_OcrPage_SetBitmapChangedCallback, L_OcrPage_IsInverted, L_OcrPage_GetRotateAngle, L_OcrPage_GetDeskewAngle, L_OcrPage_AutoPreprocess, L_OcrPage_AutoZone, L_OcrPage_GetZoneCount, L_OcrPage_InsertZone, L_OcrPage_AddZone, L_OcrPage_IndexOfZone, L_OcrPage_GetZoneAt, L_OcrPage_SetZoneAt, L_OcrPage_RemoveZone, L_OcrPage_RemoveZoneAt, L_OcrPage_ClearZones, L_OcrPage_GetZoneCells, L_OcrPage_SetZoneCells, L_OcrPage_HitTestZone, L_OcrPage_IsRecognized, L_OcrPage_Unrecognize, L_OcrPage_GetRecognizeStatistics, L_OcrPage_GetRecognizedCharacters, L_OcrPage_SetRecognizedCharacters, L_OcrPage_FreePageCharacters, L_OcrPage_GetZoneWords, L_OcrPage_FreeWords, L_OcrPage_GetText, L_OcrPage_ExtractZoneMICRData, L_OcrPage_DetectLanguages, L_OcrPage_LoadZonesFile, L_OcrPage_SaveZonesFile, L_OcrPage_SaveXml, L_OcrPage_GetAutoPreprocessValues
Topics: Programming with LEADTOOLS OCR Module - LEAD Engine
Starting and Shutting Down the OCR Engine
Recognizing OCR Pages
Working With OCR Pages


void ShowZonesInfo(L_OcrPage ocrPage) 
   L_UINT count = 0; 
   L_OcrPage_GetZoneCount(ocrPage, &count); 
   if(count < 1) 
      std::cout << "No Zone information exists to output."; 
   std::cout << "Zones:\n"; 
   for(L_UINT index = 0; index < count; index++) 
      L_OcrZone ocrZone; 
      ocrZone.StructSize = sizeof(L_OcrZone); 
      L_OcrPage_GetZoneAt(ocrPage, index, &ocrZone); 
      std::cout << "Zone index: " << index << std::endl; 
      std::cout << "  Id                  " << ocrZone.Id << std::endl; 
      std::cout << "  Bounds              (" << ocrZone.Bounds.left << ","  
         << ocrZone.Bounds.top << ","  
         << ocrZone.Bounds.right << ","  
         << ocrZone.Bounds.bottom << ")\n"; 
      std::cout << "  ZoneType            " << ocrZone.ZoneType << std::endl; 
      std::cout << "  CharacterFilters:   " << ocrZone.CharacterFilters << std::endl; 
      std::cout << "----------------------------------\n"; 
L_INT L_OcrPage_RecognizeExample() 
   L_OcrEngine ocrEngine = NULL; 
   L_OcrDocumentManager ocrDocumentManager = NULL; 
   L_OcrDocument ocrDocument = NULL; 
   BITMAPHANDLE bitmap     = { 0 }, 
                tempBitmap = { 0 }; 
   L_OcrPage ocrPage = NULL; 
   L_BOOL recognized = false; 
   // Create an instance of the engine 
   L_INT retCode = L_OcrEngineManager_CreateEngine(L_OcrEngineType_Advantage, &ocrEngine); 
   if(retCode != SUCCESS) 
      return retCode; 
   // Start the engine using default parameters 
   std::cout << "Starting up the engine...\n"; 
   retCode = L_OcrEngine_Startup(ocrEngine, NULL, OCR_ADVANTAGE_RUNTIME_DIR); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   // Load an image to process 
   retCode = L_LoadBitmap(MAKE_IMAGE_PATH(L_TEXT("Ocr1.tif")), &bitmap, sizeof(BITMAPHANDLE), 0, ORDER_RGB, NULL, NULL); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   // Add an image to OCR page. Transfer ownership of the bitmap to the page 
   retCode = L_OcrPage_FromBitmap(ocrEngine, &ocrPage, &bitmap, L_OcrBitmapSharingMode_AutoFree, NULL, NULL); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   // At this point, we have a valid page and bitmap ownership has transfered, so, we do not need to free the bitmap anymore 
   bitmap.Flags.Allocated = 0; 
   // Auto-recognize the zones in the page 
   retCode = L_OcrPage_AutoZone(ocrPage, NULL, NULL); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   retCode = L_OcrPage_GetBitmap(ocrPage, L_OcrPageBitmapType_Original, &tempBitmap, sizeof(BITMAPHANDLE)); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   // Show its information 
   std::cout << "Size: " << tempBitmap.Width << " by " << tempBitmap.Height <<" pixels\n"; 
   std::cout << "Resolution: " << tempBitmap.XResolution << "by " << tempBitmap.YResolution << " dots/inch\n"; 
   std::cout << "Bits/Pixel: " << tempBitmap.BitsPerPixel << ", Bytes/Line: " << tempBitmap.BytesPerLine << std::endl; 
   L_RGBQUAD* palette = tempBitmap.pPalette; 
   int paletteEntries; 
   if (&palette != NULL) 
      paletteEntries = sizeof(palette) / 3; 
      paletteEntries = 0; 
   std::cout << "Number of entries in the palette: " << paletteEntries << std::endl; 
   std::cout << "Original format of this page: " << tempBitmap.OriginalFormat << std::endl; 
   retCode = L_OcrPage_IsRecognized(ocrPage, &recognized); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   std::cout << "Has this page been recognized? : " << recognized << std::endl; 
   // Output zone information 
   // Recognize it and save it as PDF 
   retCode = L_OcrPage_Recognize(ocrPage, NULL, NULL); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   // Get the document manager 
   retCode = L_OcrEngine_GetDocumentManager(ocrEngine, &ocrDocumentManager); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   // Create an OCR document 
   retCode = L_OcrDocumentManager_CreateDocument(ocrDocumentManager, &ocrDocument, L_OcrCreateDocumentOptions_AutoDeleteFile, NULL); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   // In Document File Mode, add OcrPage to OcrDocument after recognition 
   retCode = L_OcrDocument_AddPage(ocrDocument, ocrPage); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   retCode = L_OcrDocument_Save(ocrDocument, MAKE_IMAGE_PATH(L_TEXT("Ocr1.pdf")), DOCUMENTFORMAT_PDF, NULL, NULL); 
   if(ocrPage != NULL) 
   if(ocrDocument != NULL) 
   if(ocrEngine != NULL) 
   return retCode; 
Help Version 20.0.2019.3.12
Products | Support | Contact Us | Intellectual Property Notices
© 1991-2019 LEAD Technologies, Inc. All Rights Reserved.