L_OcrPage_FromBitmap

#include "ltocr.h"

L_LTOCR_API L_INT EXT_FUNCTION L_OcrPage_FromBitmap(engine, page, bitmapHandle, sharingMode, callback, userData)

L_OcrEngine engine;	handle to the OCR engine
L_OcrPage* page;	address of L_OcrPage variable to be updated with the created OCR page handle
BITMAPHANDLE* bitmapHandle;	source bitmap handle
L_OcrBitmapSharingMode sharingMode;	options to determine the ownership of image
L_OcrProgressCallback callback;	optional callback to show operation progress
L_VOID* userData;	optional user data to pass to the callback function

Create an L_OcrPage from a bitmap.

Parameter	Description
engine	Handle to the OCR engine.
page	Address of L_OcrPage variable to be updated with the created OCR page handle.
bitmapHandle	Source bitmap handle. This parameter cannot be NULL.
sharingMode	Options to determine the ownership of image.
callback	Optional callback to show operation progress.
userData	Optional user data to pass to the callback function.

Returns

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

Comments

Use this function to quickly create an L_OcrPage from a bitmap handle directly, call the necessary method (such as L_OcrPage_Recognize) and then obtain the text directly using L_OcrPage_GetText or L_OcrPage_GetRecognizedCharacters.

To save the results of L_OcrPage to a document file such as PDF or Microsoft Word by directly, you must create an L_OcrDocument handle in file mode and add the page to it using L_OcrDocument_AddPage.

You must call L_OcrPage_Destroy after you finish using this L_OcrPage to free its memory.

The value of sharingMode determines what happens to the bitmap handle after it has been used to create the page as follows:

Option	Option
L_OcrImageSharingMode_None	The result L_OcrPage does not own the bitmap handle. When L_OcrPage is destroyed, the bitmap is not freed. This mode is useful for quickly creating an OCR page (and getting the recognition result) from a bitmap that is already used in other parts of your application. Using this option will save memory because you do not have to create a copy of the image and the page will use the same image data when performing recognition. Important: In this mode, it is the user responsibility to keep the bitmap handle alive for the whole duration the page is alive. Only free the bitmap after the L_OcrPage object is destroyed and no longer used.
L_OcrBitmapSharingMode_AutoFree	The result L_OcrPage owns the image. When L_OcrPage is destroyed, the btimap is freed as well. This mode is useful when the bitmap is no longer used by other parts of your application. For example, the bitmap is obtained from scanning or the camera and is only to be used for OCRing. Using this option will transfer the ownership of the bitmap handle to the page and it will be freed when the page is destroyed.

L_OcrImageSharingMode_None

The result L_OcrPage does not own the bitmap handle. When L_OcrPage is destroyed, the bitmap is not freed. This mode is useful for quickly creating an OCR page (and getting the recognition result) from a bitmap that is already used in other parts of your application. Using this option will save memory because you do not have to create a copy of the image and the page will use the same image data when performing recognition.
Important: In this mode, it is the user responsibility to keep the bitmap handle alive for the whole duration the page is alive. Only free the bitmap after the L_OcrPage object is destroyed and no longer used.

L_OcrBitmapSharingMode_AutoFree

The result L_OcrPage owns the image. When L_OcrPage is destroyed, the btimap is freed as well. This mode is useful when the bitmap is no longer used by other parts of your application. For example, the bitmap is obtained from scanning or the camera and is only to be used for OCRing. Using this option will transfer the ownership of the bitmap handle to the page and it will be freed when the page is destroyed.

Required DLLs and Libraries

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

Example

#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName 
#define OCR_ADVANTAGE_RUNTIME_DIR TEXT("C:\\LEADTOOLS 19\\Bin\\Common\\OcrAdvantageRuntime") 
L_INT CreateMultiPageFile(L_TCHAR* outputFileName) 
{ 
   // Create a muti-page TIF from Ocr1.tif, Ocr2.tif, Ocr3.tif and Ocr4.tif 
   HBITMAPLIST bitmapList; 
   L_INT retCode = -1; 
   SAVEFILEOPTION saveOptions = {0}; 
   retCode = L_CreateBitmapList(&bitmapList); 
   if(retCode != SUCCESS) 
      return retCode; 
   BITMAPHANDLE bitmaps[4]; 
   L_TCHAR *imageFiles[] = {MAKE_IMAGE_PATH(L_TEXT("OCR1.tif")), 
   MAKE_IMAGE_PATH(L_TEXT("OCR2.tif")), 
   MAKE_IMAGE_PATH(L_TEXT("OCR3.tif")), 
   MAKE_IMAGE_PATH(L_TEXT("OCR4.tif"))}; 
   for(L_INT i = 0; i < _countof(imageFiles); i++) 
   { 
      retCode = L_LoadBitmap(imageFiles[i], &bitmaps[i], sizeof(BITMAPHANDLE), 0, ORDER_RGB, NULL, NULL); 
      if(retCode != SUCCESS) 
         return retCode; 
      retCode = L_InsertBitmapListItem(bitmapList, (L_UINT)-1, &bitmaps[i]); 
      if(retCode != SUCCESS) 
         goto CLEANUP; 
   } 
   // Save the output file 
   retCode = L_GetDefaultSaveFileOption(&saveOptions, sizeof(SAVEFILEOPTION)); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
   // Save all pages 
   saveOptions.PageNumber = -1; 
   retCode = L_SaveBitmapList(outputFileName, bitmapList, FILE_CCITT_GROUP4, 1, 0, &saveOptions); 
CLEANUP: 
   //free all bitmaps in list & dispose of handle 
   L_DestroyBitmapList(bitmapList); 
   return retCode; 
} 
L_INT L_OcrPage_FromBitmapExample() 
{ 
   L_INT retCode = -1; 
   L_OcrEngine ocrEngine = NULL; 
   L_OcrDocumentManager ocrDocumentManager = NULL; 
   L_OcrDocument ocrDocument = NULL; 
   L_OcrPage ocrPage = NULL; 
   LOADFILEOPTION loadOpts; 
   FILEINFO fileInfo; 
   // For this example, we need a multi-page TIF file. 
   // If you have a different sample file, replace the file name below 
   L_TCHAR* multiPageFile = MAKE_IMAGE_PATH(L_TEXT("Ocr.tif")); 
   if(CreateMultiPageFile(multiPageFile) != SUCCESS) 
      return FAILURE; 
   // Create an instance of the engine 
   retCode = L_OcrEngineManager_CreateEngine(L_OcrEngineType_Advantage, &ocrEngine); 
   if(retCode != SUCCESS) 
      return retCode; 
   // Start the engine using default parameters 
   retCode = L_OcrEngine_Startup(ocrEngine, NULL, OCR_ADVANTAGE_RUNTIME_DIR); 
   if(retCode == SUCCESS) 
   { 
      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; 
      // Load each page of the multi-page tif file we created and process them 
      L_GetDefaultLoadFileOption(&loadOpts, sizeof(LOADFILEOPTION)); 
      retCode = L_FileInfo(multiPageFile, &fileInfo, sizeof(FILEINFO), FILEINFO_TOTALPAGES, &loadOpts); 
      if(retCode != SUCCESS) 
         goto CLEANUP; 
      for(L_INT pageNum = 1; pageNum <= fileInfo.TotalPages; pageNum++) 
      { 
         // Load page 
         BITMAPHANDLE bitmap = { 0 }; 
         loadOpts.PageNumber = pageNum; 
         retCode = L_LoadBitmap(multiPageFile, &bitmap, sizeof(BITMAPHANDLE), 0, ORDER_RGB, &loadOpts, &fileInfo); 
         if(retCode != SUCCESS) 
            goto CLEANUP; 
         // Create Ocr page 
         retCode = L_OcrPage_FromBitmap(ocrEngine, &ocrPage, &bitmap, L_OcrBitmapSharingMode_AutoFree, NULL, NULL); 
         if(retCode != SUCCESS) 
         { 
            L_FreeBitmap(&bitmap); 
            goto CLEANUP; 
         } 
         // Transfer ownership to the OCR page 
         bitmap.Flags.Allocated = 0; 
         // Find zones in the page 
         retCode = L_OcrPage_AutoZone(ocrPage, NULL, NULL); 
         if(retCode != SUCCESS) 
            goto CLEANUP; 
         // Recognize 
         retCode = L_OcrPage_Recognize(ocrPage, NULL, 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; 
         //Destroy the page to free the bitmap 
         L_OcrPage_Destroy(ocrPage); 
         ocrPage = NULL; 
      } 
      // Save 
      retCode = L_OcrDocument_Save(ocrDocument, MAKE_IMAGE_PATH(L_TEXT("Ocr.pdf")), DOCUMENTFORMAT_PDF, NULL, NULL); 
   } 
CLEANUP: 
   if(ocrPage != NULL) 
      L_OcrPage_Destroy(ocrPage); 
   if(ocrDocument != NULL) 
      L_OcrDocument_Destroy(ocrDocument); 
   if(ocrEngine != NULL) 
      L_OcrEngine_Destroy(ocrEngine); 
   return retCode; 
}

Help Version 19.0.2017.10.27

LEADTOOLS Advantage OCR C API Help

Introduction

Version History

Redistributables/Files To Be Included With Your Application

LEADTOOLS OCR Features

Quick Reference

Tutorials

Function References

Functions:	L_OcrPage_Destroy, 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_Recognize, 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 Advantage
	Starting and Shutting Down the OCR Engine
	Recognizing OCR Pages
	Working With OCR Pages