RuntimeFileCallback Property

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

public OcrRuntimeFileCallback RuntimeFileCallback {get; set;} 

public:  
   property OcrRuntimeFileCallback^ RuntimeFileCallback 
   { 
      OcrRuntimeFileCallback^ get() 
      void set(OcrRuntimeFileCallback^ value) 
   } 

RuntimeFileCallback # get and set (IOcrEngine) 

Property Value

Handler that can be used to redirect searching and loading of engine files at runtime to a specified directory or memory stream. The default value is null.

Important Note 1: This property is only supported by the OcrEngineType.LEAD engine.

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

The value of RuntimeFileCallback property is null by default. Therefore, locating and obtaining the runtime files necessary for the OCR engine to perform its operation is performed by either passing the name of the directory where these files reside to Startup as the startupParameters parameter, or relying on the automatic discovery of the engine files in the special folders as outlined in 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.

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

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

• Startup will try to locate (but not load) all known engine files to build the feature support matrix (obtained through IOcrLanguageManager.GetSupportedLanguages or IOcrZoneManager.GetSupportedZoneTypes).
• Startup will load and cache the default language files (for instance, LEAD.en.bin).
• IOcrLanguageManager.EnableLanguages will load and use the language files specified.
• IOcrPage.Recognize may load additional language runtime files, depending on the zone types.

In other words, for any LEAD.xyz.bin runtime file, IOcrEngine 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 File.Exists(fullPathToFile). If the file does exist, a request to load the file is made by calling File.OpenRead(fullPathToFile) 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 RuntimeFileCallback to intercept such calls and redirect checking for file existence and loading to a custom path or routine as follows:

1. Add a handler to IOcrEngine.RuntimeFileCallback before calling IOcrEngine.Startup. The order is important because the engine checks for a redirect during Startup:

   C#

   // Create a LEAD OCR Engine instance 
   IOcrEngine ocrEngine = OcrEngineManager.CreateEngine(OcrEngineType.LEAD) 
   // Add a runtime file redirect handler 
   ocrEngine.RuntimeFileCallback = runtimeFileCallbackHandler; 
   // Now start up the engine without passing a directory name to the runtime files. 
   // The handler will be called as many times as necessary to locate and load the OCR 
   // runtime files required by the engine 
   ocrEngine.Startup(null, null, null, 
      null /* startupParameters is null*/ ); 

2. Perform OCR operations as normal. The handler will be called as many times as necessary.

   C#

   // OCR a TIF file and save it as PDF 
   // The handler can be called as many times as necessary to locate and load the OCR 
   // runtime files required by the engine for this operation 
   ocrEngine.AutoRecognizeManager.Run( 
      @"C:\LEADTOOLS23\Resources\Images\ocr1.tif", 
      @"C:\LEADTOOLS23\Resources\Images\out.pdf", 
      DocumentFormat.Pdf, 
      null, 
      null); 

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

   C#

   // Shutdown 
   ocrEngine.Shutdown(); 
   // Remove the handler 
   ocrEngine.RuntimeFileCallback = null; 
   // Dispose the engine 
   ocrEngine.Dispose(); 

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

   Member	Description
   FileName	Input only: The name of the OCR runtime file requested
   Guid	Input only: Unique identifier associated with this runtime file
   Mode	Input only: Operation to perform on the file, such check for its existence, opening it for reading or closing it
   FullPath	Output: Full path to where the file exists, if available
   Stream	Output: Stream containing the file data, if available

Note that the engine will check if the callback has set a value in OcrRuntimeFile.FullPath first. If the value is null, then OcrRuntimeFile.Stream is used.

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

This example shows how to use OcrRuntimeFileCallback to redirect LEAD OCR to load and locate files from a stream.

using Leadtools; 
using Leadtools.Codecs; 
using Leadtools.Ocr; 
using Leadtools.Document.Writer; 
 
public static void OcrRuntimeFileCallbackExample() 
{ 
   // This example assumes that some or all of the OCR runtime files are copied into "C:\MyDir" folder and simulates 
   // an environment where the runtime files can be obtained through helper methods HasResource and GetResourceStream. 
 
   // Create an OCR engine instance 
   IOcrEngine ocrEngine = OcrEngineManager.CreateEngine(OcrEngineType.LEAD); 
 
   // Install a OCR file runtime handler 
   ocrEngine.RuntimeFileCallback = MyRuntimeFileCallback; 
 
   // Startup the engine 
   ocrEngine.Startup(null, null, null, 
      null /* startupParameters is null*/); 
 
   // Perform OCR operation 
   ocrEngine.AutoRecognizeManager.Run( 
      @"C:\LEADTOOLS22\Resources\Images\ocr1.tif", 
      @"C:\LEADTOOLS22\Resources\Images\out.pdf", 
      DocumentFormat.Pdf, 
      null, 
      null); 
 
   // Shutdown 
   ocrEngine.Shutdown(); 
   // Remove the handler 
   ocrEngine.RuntimeFileCallback = null; 
   // Dispose the engine 
   ocrEngine.Dispose(); 
} 
 
private static RasterExceptionCode MyRuntimeFileCallback(IOcrEngine engine, OcrRuntimeFile runtimeFile) 
{ 
   // Called by the OCR engine for each runtime file operation 
 
   RasterExceptionCode result = RasterExceptionCode.Success; 
 
   // Check the operation: 
   switch (runtimeFile.Mode) 
   { 
      case OcrRuntimeFileMode.Exists: 
         Debug.WriteLine($"MyRuntimeFileCallback does '{runtimeFile.FileName}' exist"); 
         // The engine is checking if a certain file exists, call our HasResource helper 
         if (!HasResource(runtimeFile.FileName)) 
            result = RasterExceptionCode.FileNotFound; 
         break; 
 
      case OcrRuntimeFileMode.Open: 
         Debug.WriteLine($"MyRuntimeFileCallback open '{runtimeFile.FileName}'"); 
         // The engine requested to open the file for reading, call our GetResourceStream helper 
         // and set the Stream property accordingly 
         runtimeFile.Stream = GetResourceStream(runtimeFile.FileName); 
         break; 
 
      case OcrRuntimeFileMode.Close: 
         Debug.WriteLine($"MyRuntimeFileCallback close '{runtimeFile.FileName}'"); 
         // The engine requested to close the file after reading. 
         // Dispose our stream 
         runtimeFile.Stream.Dispose(); 
         break; 
   } 
 
   return result; 
} 
 
private static bool HasResource(string resourceName) 
{ 
   // Do we have this resource? 
   // In our simulation, we will simply check if the file exist on disk 
   // In an Android application, this can check if a resource with this name was embedded 
   return System.IO.File.Exists(Path.Combine(@"C:\MyDir", resourceName)); 
} 
 
private static Stream GetResourceStream(string resourceName) 
{ 
   // Get a stream that can read from resource 
   // In our simulation, we will simply check if the file exist on disk 
   // In an Android application, this can call the appropriate platform API to obtain 
   // a stream to the resource 
   return System.IO.File.OpenRead(Path.Combine(@"C:\MyDir", resourceName)); 
} 

 
import java.io.File; 
import java.io.IOException; 
import java.nio.file.Files; 
import java.nio.file.Path; 
import java.nio.file.Paths; 
 
import org.junit.*; 
import org.junit.runner.JUnitCore; 
import org.junit.runner.Result; 
import org.junit.runner.notification.Failure; 
import static org.junit.Assert.assertTrue; 
 
import leadtools.*; 
import leadtools.codecs.*; 
import leadtools.document.writer.*; 
import leadtools.ocr.*; 
 
 
public void IOcrRuntimeFileCallbackExample() { 
   final String LEAD_VARS_IMAGES_DIR = "C:\\LEADTOOLS23\\Resources\\Images"; 
   final String OCR_LEAD_RUNTIME_DIR = "C:\\LEADTOOLS23\\Bin\\Common\\OcrLEADRuntime"; 
 
   // Create an OCR engine instance 
   OcrEngine ocrEngine = OcrEngineManager.createEngine(OcrEngineType.LEAD); 
 
   // Install a OCR file runtime handler 
   ocrEngine.setRuntimeFileCallback(MyRuntimeFileCallback); 
 
   // Startup the engine 
   ocrEngine.startup(null, null, null, OCR_LEAD_RUNTIME_DIR); 
   assertTrue(ocrEngine.isStarted()); 
 
   // Perform OCR operation 
   ocrEngine.getAutoRecognizeManager().run( 
         combine(LEAD_VARS_IMAGES_DIR, "ocr1.tif"), 
         combine(LEAD_VARS_IMAGES_DIR, "out.pdf"), 
         DocumentFormat.PDF, null); 
 
   // Shutdown 
   ocrEngine.shutdown(); 
   assertTrue(!ocrEngine.isStarted()); 
   // Remove the handler 
   ocrEngine.setRuntimeFileCallback(null); 
   // Dispose the engine 
   ocrEngine.dispose(); 
 
   System.out.println("OCR operation completed successfully"); 
} 
 
OcrRuntimeFileCallbackListener MyRuntimeFileCallback = new OcrRuntimeFileCallbackListener() { 
 
   @Override 
   public RasterExceptionCode onCallback(OcrEngine arg0, OcrRuntimeFile runtimeFile) { 
      // Called by the OCR engine for each runtime file operation 
 
      RasterExceptionCode result = RasterExceptionCode.SUCCESS; 
      System.out.println(runtimeFile.getFileName()); 
 
      // Check the operation: 
      switch (runtimeFile.getMode()) { 
         case EXISTS: 
            System.out.println("MyRuntimeFileCallback does " + runtimeFile.getFileName() + " exist"); 
            // The engine is checking if a certain file exists, call our HasResource helper 
            if (!hasResource(runtimeFile.getFileName())) 
               result = RasterExceptionCode.FILE_NOT_FOUND; 
            break; 
 
         case OPEN: 
            System.out.println("MyRuntimeFileCallback open " + runtimeFile.getFileName()); 
            // The engine requested to open the file for reading, call our GetResourceStream 
            // helper 
            // and set the Stream property accordingly 
            runtimeFile.setStream(getResourceStream(runtimeFile.getFileName())); 
            break; 
 
         case CLOSE: 
            System.out.println("MyRuntimeFileCallback close " + runtimeFile.getFileName()); 
            // The engine requested to close the file after reading. 
            // Dispose our stream 
            runtimeFile.getStream().dispose(); 
            break; 
      } 
 
      return result; 
   } 
 
}; 
 
private boolean hasResource(String resourceName) { 
   final String OCR_LEAD_RUNTIME_DIR = "C:\\LEADTOOLS23\\Bin\\Common\\OcrLEADRuntime"; 
   // Do we have this resource? 
   // In our simulation, we will simply check if the file exist on disk 
   // In an Android application, this can check if a resource with this name was 
   // embedded 
   File file = new File(combine(OCR_LEAD_RUNTIME_DIR, resourceName)); 
   return file.exists(); 
} 
 
private ILeadStream getResourceStream(String resourceName) { 
 
   final String OCR_LEAD_RUNTIME_DIR = "C:\\LEADTOOLS23\\Bin\\Common\\OcrLEADRuntime"; 
   // Get a stream that can read from resource 
   // In our simulation, we will simply check if the file exist on disk 
   // In an Android application, this can call the appropriate platform API to 
   // obtain 
   // a stream to the resource 
   return LeadStreamFactory.create(combine(OCR_LEAD_RUNTIME_DIR, resourceName)); 
 
} 

Target Platforms

Reference

IOcrEngine Class

IOcrEngine Members

Leadtools.Ocr Namespace