L_OcrEngine_SetRuntimeFileCallback

#include "ltocr.h"

L_LTOCR_API L_INT EXT_CALLBACK L_OcrEngine_SetRuntimeFileCallback(engine, callback, userData)

Redirects searching and loading of engine files at runtime to a specified directory or memory buffer.

Parameters

L_OcrEngine engine

Handle to the OCR engine.

L_OcrRuntimeFileCallback callback

Callback that can be used to redirect searching and loading of engine files at runtime to a specified directory or memory buffer.

L_VOID * userData

Optional user data to pass to the callback function.

Returns

Comments

Important Note 1: The LEAD Engine OCR Runtime file shipping with version 20 of LEADTOOLS does not support redirecting through memory buffer. Contact support@leadtools.com for instructions on how to obtain a copy of these files with streaming support.

The OCR engine by default performs the task of locating and obtaining the runtime files necessary for the engine to perform its operation by either passing the name of the directory where these files reside to L_OcrEngine_Startup as the engineDirectory parameter, or relying on the automatic discovery of the engine files in the special folders as outlined in L_OcrEngine_Startup.

The above technique is suitable for desktop-based applications that install on a physical path on the machine. There are situations where the above is not desired or possible:

• The application may choose to download or extract runtime files on demand from internal resources embedded in the app or even external ones.

• Some environments, such as Android, do not support obtaining a physical path to resources embedded in the application.

L_OcrEngine_SetRuntimeFileCallback can be used to redirect the search and loading of OCR runtime files to support these types of applications.

An OCR engine instance will try to load one or more engine runtime files during its lifetime as follows:

• L_OcrEngine_Startup will try to locate (but not load) all known engine files to build the feature support matrix (obtained through L_OcrLanguageManager_GetSupportedLanguages).
• L_OcrEngine_Startup will load and cache the default language files (for instance, LEAD.en.bin).
• L_OcrLanguageManager_EnableLanguages will load and use the language files specified.
• L_OcrPage_Recognize may load additional language runtime files, depending on the zone types.

In other words, for any LEAD.xyz.bin runtime file, OCR engine may request a check if the file exist one or more times and may request loading it one or more times. The order and frequency of these operations is internal to the engine.

The runtime files reside on disk files by default. Therefore, a request to check if a file exists is a simple call to the operating system access. If the file does exist, a request to load the file is made by calling fopen(fullPathToFile, "rb") and then the content of the file is read. If the file does not exist, there will be no attempt to read it.

An application can use L_OcrEngine_SetRuntimeFileCallback and install a callback to intercept such calls and redirect checking for file existence and loading to a custom path or routine as follows:

1. Set a L_OcrRuntimeFileCallback callback using L_OcrEngine_SetRuntimeFileCallback before calling L_OcrEngine_Startup. The order is important because the engine checks for a redirect during Startup:

   // Create a LEAD OCR Engine instance 
   L_OcrEngine ocrEngine = NULL; 
   L_OcrEngineManager_CreateEngine(L_OcrEngineType_LEAD, &ocrEngine); 
   // Set a runtime file redirect callback 
   L_OcrEngine_SetRuntimeFileCallback(ocrEngine, MyOcrRuntimeFileCallback, /*if any*/ &userData); 
   // Now start up the engine without passing a directory name to the runtime files. 
   // The runtime file callback will be called as many times as necessary to locate and load the OCR 
   // runtime files required by the engine 
   L_OcrEngine_Startup( 
      ocrEngine, 
      NULL, 
      NULL, // NULL for 'const L_TCHAR* engineDirectory' parameter 
   ); 

2. Perform OCR operations as normal. The runtime file callback will be called as many times as necessary.

   // OCR a TIF file and save it as PDF 
   // The runtime file callback can be called as many times as necessary to locate and load the OCR 
   // runtime files required by the engine for this operation 
   L_OcrAutoRecognizeManager ocrAutoRecognizeManager; 
   L_OcrEngine_GetAutoRecognizeManager(ocrEngine, &ocrAutoRecognizeManager); 
   L_OcrAutoRecognizeManager_Run( 
      ocrAutoRecognizeManager, 
      L_TEXT("C:\\LEADTOOLS21\\Resources\\Images\\ocr1.tif"), 
      L_TEXT("C:\\LEADTOOLS21\\Resources\\Images\\out.pdf"), 
      DOCUMENTFORMAT_PDF, 
      NULL); 

3. Optionally, remove the runtime file callback. This must be done after shutting the engine down but before disposing it

   // Shutdown 
   L_OcrEngine_Shutdown(ocrEngine); 
   // Remove the runtime callback 
   L_OcrEngine_SetRuntimeFileCallback(ocrEngine, NULL, NULL); 
   // Destroy the engine 
   L_OcrEngine_Destroy(ocrEngine); 

4. The runtime file callback is called with an instance of L_OcrRuntimeFile that describes the runtime file and the operation requested as follows:

   Member	Description
   const L_TCHAR * FileName	Input only: The name of the OCR runtime file requested.
   L_OcrRuntimeFileMode Mode	Input only: Operation to perform on the file, such check for its existence, opening it for reading or closing it.
   L_TCHAR FullPath[MAX_PATH]	Output: Full path to where the file exists, if available.

Refer to the example below on how to use L_OcrEngine_SetRuntimeFileCallback.

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

Platforms

Win32, x64, Linux.

static L_INT EXT_CALLBACK MyRuntimeFileCallback(L_OcrEngine engine, L_OcrRuntimeFile* runtimeFile, L_VOID* userData); 
 
static void OcrRuntimeFileCallbackExample() 
{ 
   // This example assumes that some or all of the OCR runtime files are copied into "C:\MyDir" folder 
   const L_TCHAR* myDir = L"C:\\MyDir"; 
    
   // Create an OCR engine instance 
   L_OcrEngine ocrEngine = NULL; 
   L_OcrEngineManager_CreateEngine(L_OcrEngineType_LEAD, &ocrEngine); 
 
   // Install a OCR file runtime handler, passing our directory as the user data 
   L_OcrEngine_SetRuntimeFileCallback(ocrEngine, MyRuntimeFileCallback, (L_VOID*)myDir); 
 
   // Startup the engine 
   L_OcrEngine_Startup(ocrEngine, 
      NULL, 
      NULL // engineDirectory is NULL 
   ); 
 
   // Perform OCR operation 
   L_OcrAutoRecognizeManager ocrAutoRecognizeManager; 
   L_OcrEngine_GetAutoRecognizeManager(ocrEngine, &ocrAutoRecognizeManager); 
   L_OcrAutoRecognizeManager_Run( 
      ocrAutoRecognizeManager, 
      L_TEXT("C:\\LEADTOOLS21\\Resources\\Images\\ocr1.tif"), 
      L_TEXT("C:\\LEADTOOLS21\\Resources\\Images\\out.pdf"), 
      DOCUMENTFORMAT_PDF, 
      NULL); 
 
   // Shutdown 
   L_OcrEngine_Shutdown(ocrEngine); 
   // Remove the runtime callback 
   L_OcrEngine_SetRuntimeFileCallback(ocrEngine, NULL, NULL); 
   // Destroy the engine 
   L_OcrEngine_Destroy(ocrEngine); 
} 
 
static L_INT EXT_CALLBACK MyRuntimeFileCallback(L_OcrEngine /*ocrEngine*/, L_OcrRuntimeFile* runtimeFile, L_VOID* userData) 
{ 
   // Called by the OCR engine for each runtime file operation 
 
   // Get the directory (our user data) 
   const L_TCHAR* myDir = reinterpret_cast<L_TCHAR*>(userData); 
 
   L_INT ret = SUCCESS; 
 
   // Check the operation: 
   switch(runtimeFile->Mode) 
   { 
      case L_OcrRuntimeFileMode_Exists: 
         wprintf(L_TEXT("MyRuntimeFileCallback does '%s' exist\n"), runtimeFile->FileName); 
         // The engine is checking if a certain file exists 
         L_TCHAR fullPath[MAX_PATH]; 
         swprintf_s(fullPath, L_TEXT("%s\\%s"), myDir, runtimeFile->FileName); 
         if(_waccess_s(fullPath, 0) != 0) 
            ret = ERROR_FILENOTFOUND; 
         break; 
 
      case L_OcrRuntimeFileMode_Open: 
         wprintf(L_TEXT("MyRuntimeFileCallback open '%s'\n"), runtimeFile->FileName); 
         // The engine requested to open the file for reading 
         swprintf_s(fullPath, L_TEXT("%s\\%s"), myDir, runtimeFile->FileName); 
         break; 
 
      case L_OcrRuntimeFileMode_Close: 
         wprintf(L_TEXT("MyRuntimeFileCallback close '%s'\n"), runtimeFile->FileName); 
         // The engine requested to close the file after reading. 
         break; 
   } 
 
   return ret; 
}