Startup Method

Summary

Starts the OCR engine.

Syntax

Objective-C

C++

Java

public void Startup( 
   RasterCodecs rasterCodecs, 
   DocumentWriter documentWriter, 
   string workDirectory, 
   string startupParameters 
)

Sub Startup( _ 
   ByVal rasterCodecs As RasterCodecs, _ 
   ByVal documentWriter As DocumentWriter, _ 
   ByVal workDirectory As String, _ 
   ByVal startupParameters As String _ 
)

- (BOOL)startup:(nullable LTRasterCodecs *)rasterCodecs  
 documentWriter:(nullable LTDocumentWriter *)documentWriter  
  workDirectory:(nullable NSString *)workDirectory  
engineDirectory:(nullable NSString *)engineDirectory  
          error:(NSError **)error

public void startup( 
   RasterCodecs rasterCodecs,  
   DocumentWriter documentWriter,  
   String workDirectory,  
   String startupParameters 
)

void Startup(  
   RasterCodecs^ rasterCodecs, 
   DocumentWriter^ documentWriter, 
   String^ workDirectory, 
   String^ startupParameters 
)

Parameters

rasterCodecs
Optional instance of a RasterCodecs object to be used when loading image files from disk inside the engine. You can pass your own initialized instance of RasterCodecs to be used. The same object will then be used internally by the OCR engine when loading raster image files. Otherwise, pass null (Nothing in VB) and the IOcrEngine will create and use its own version of RasterCodecs when needed. Refer to RasterCodecsInstance for more information on how this parameter is used by the OCR engine during its lifetime, refer to OCR Engine and RasterCodecs/DocumentWriter Usage.

documentWriter
Optional instance of a DocumentWriter object to be used when saving OCR documents to disk inside the engine. You can pass your own initialized instance of DocumentWriter to be used. The same object will then be used internally by the OCR engine when saving OCR documents to disk. Otherwise, pass null (Nothing in VB) and the IOcrEngine will create and use its own version of DocumentWriter when needed. Refer to DocumentWriterInstance for more information on how this parameter is used by the OCR engine during its lifetime, refer to OCR Engine and RasterCodecs/DocumentWriter Usage.

workDirectory
Optional path to a directory to be used when the engine saves temporary files. The IOcrEngine object will create various temporary files during recognition and document saving processes. It will use the path passed in workDirectory as the location where these temporary files will be created. You can pass null (Nothing in VB) to let the engine select the temporary directory of the current logged in user (TEMP).

In either case, the value of working directory of the current started IOcrEngine can be obtained through the WorkDirectory property.

The engine automatically deletes any temporary files created. However, if an unexpected error occurs (for example, an unhandled exception), some temporary files may still reside in the work directory after the application exits. A typical application may use a custom directory inside the application path and manually deletes any files that may reside there before calling Startup in case the previous instance of the application exited abnormally.

If the value of the workDirectory parameter is not null (Nothing in VB), then it must refer to a valid directory that exists in the system and the process that created the engine must have enough access rights to read, write and delete files from this directory.

startupParameters
Optional startup parameter. The value of this parameter depends on the type of this IOcrEngine as follows:

Engine	startupParameters
OcrEngineType.LEAD	The path to the folder containing the OCR engine files. If you pass null (Nothing in VB) to startupParameters, then the LEADTOOLS OCR engine will look for these extra files in the runtime directory specified. When you are ready to package your application, you might want to change the location where the LEADTOOLS OCR engine looks for these extra files. You can use this property to do that. Set the path you want before calling the Startup method.
OcrEngineType.Arabic	The path to the folder containing the OCR engine files. If you pass null (Nothing in VB) to startupParameters, then the LEADTOOLS OCR engine will look for these extra files in the runtime directory specified. When you are ready to package your application, you might want to change the location where the LEADTOOLS OCR engine looks for these extra files. You can use this property to do that. Set the path you want before calling the Startup method.
OcrEngineType.OmniPage	The path to the folder containing the OCR engine files. If you pass null (Nothing in VB) to startupParameters, then the LEADTOOLS OCR engine will look for these extra files in the runtime directory specified. When you are ready to package your application, you might want to change the location where the LEADTOOLS OCR engine looks for these extra files. You can use this property to do that. Set the path you want before calling the Startup method.

Remarks

The Startup method must be called before invoking any other methods or properties in this IOcrEngine.

To check if the engine is started, use the IsStarted property.

You must call Shutdown to shut down the engine and free the memory and resources used.

You can call the Startup method multiple times, only the first call will start the engine while subsequent calls will only increment an internal counter. You must call Shutdown for each Startup called.

The IOcrEngine interface implements IDisposable. It is highly recommended that you call Dispose (or use the using statement in C# or Using statement in VB) when creating the IOcrEngine instance. The Dispose method will automatically shut down the engine if it has been started.

Runtime Directories

LEADTOOLS default setup installs the OCR runtime files into the following directories:

OCR Engine	Directory
LEAD (OcrEngineType.LEAD)	Bin\Common\OcrLEADRuntime
Omni Page (OcrEngineType.OmniPage)	Bin\Common\OcrOmniPageRuntime
Arabic Omni Page (OcrEngineType.OmniPageArabic)	Bin\Common\OcrOmniPageRuntime

To start up a specific OCR engine, pass the corresponding directory name in the startupParameters parameters:

// Start the LEAD OCR Engine passing the path to the LEADTOOLS Setup installation folder. 
IOcrEngine ocrEngine = OcrEngineManager.CreateEngine(OcrEngineType.LEAD, false); 
ocrEngine.Startup(null, null, null, @"C:\LEADTOOLS 20\Bin\Common\OcrLEADRuntime");

Or as shown in the example below, the application can copy these folders inside the app package and pass the folder name.

OmniPage Based Engines

For the OmniPage based engine, using a physical path to a directory is the only supported way to start up the engine. Passing null as the startupParameters parameter in Startup is not allowed.

LEAD Engine

For the LEAD engine, the toolkit supports a physical path to a directory as well as automatically detecting the runtime files location when the user passes null as the startupParameters parameter in Startup:

Inside the application bin directory.

When the application starts, it will check for a "LEADTOOLS/OcrLEADRuntime" directory inside the folder where the caller EXE resides. For instance, this could be the layout of the application on disk:

app.exe 
Leadtools.dll 
Leadtools.Codecs.dll 
Leadtools.Ocr.dll 
Leadtools.Ocr.LEADEngine.dll 
LEADTOOLS\OcrLEADRuntime\LEAD.en.bin 
LEADTOOLS\OcrLEADRuntime\LEAD.en.bin2

This is the default approach used when adding the LEADTOOLS OCR libraries as a Nuget in Visual Studio. It can be simulated in any development environment by adding the LEAD OCR runtime files as a "resource" to the project and using the "Copy to output" feature.

IOcrEngine includes the IOcrEngine.RuntimeFileCallback event which can be used to:
- Redirect the searching and loading of engine files at runtime to a specified directory
- Load the engine files from a memory stream

This support is very helpful in some environments that do not support a physical path to resource files, such as Android. Refer to IOcrEngine.RuntimeFileCallback for more information and an example.

Example

The following example assumes you copied the OCR engine runtime files to C:\MyApp\Ocr.

using Leadtools; 
using Leadtools.Codecs; 
using Leadtools.Ocr; 
using Leadtools.Document.Writer; 
 
public void StartupEngineExample() 
{ 
   // Use RasterCodecs to load an image file 
   // Note: You can let the engine load the image file directly as shown in the other examples 
   RasterCodecs codecs = new RasterCodecs(); 
   RasterImage image = codecs.Load(Path.Combine(LEAD_VARS.ImagesDir, "Ocr1.tif")); 
 
   // Assume you copied the engine runtime files to C:\MyApp\Ocr 
   string engineDir = @"C:\MyApp\Ocr"; 
 
   // Store the engine work directory into a path inside our application 
   string workDir = @"C:\MyApp\OcrTemp"; 
 
   // Delete all files in the work directory in case the previous version of our application exited abnormally and 
   // the engine did not get the chance to clean all of its temporary files (if any) 
   Directory.Delete(workDir, true); 
 
   // Re-create the work directory 
   Directory.CreateDirectory(workDir); 
 
   // Create an instance of the engine 
   using (IOcrEngine ocrEngine = OcrEngineManager.CreateEngine(OcrEngineType.LEAD, false)) 
   { 
      // Show that the engine has not been started yet 
      Console.WriteLine("Before calling Startup, IsStarted = " + ocrEngine.IsStarted); 
 
      // Start the engine using our parameters 
      // Since we already have a RasterCodecs object, we can re-use it to save memory and resources 
      ocrEngine.Startup(codecs, null, workDir, engineDir); 
 
      // Make sure the engine is using our working directory 
      Console.WriteLine("workDir passed is {0}, the value of WorkDirectory after Startup is {1}", workDir, ocrEngine.WorkDirectory); 
 
      // Show that the engine has started fine 
      Console.WriteLine("After calling Startup, EngineType is {0}, IsStarted = {1}", ocrEngine.EngineType, ocrEngine.IsStarted); 
 
      // Maks sure the engine is using our own version of RasterCodecs 
      Debug.Assert(codecs == ocrEngine.RasterCodecsInstance); 
 
      // Create a page from the raster image as page to the document 
      IOcrPage ocrPage = ocrEngine.CreatePage(image, OcrImageSharingMode.AutoDispose); 
      // image belongs to the page and will be dispose when the page is disposed 
 
      // Recognize the page 
      // Note, Recognize can be called without calling AutoZone or manually adding zones. The engine will 
      // check and automatically auto-zones the page 
      ocrPage.Recognize(null); 
 
      // Create a file based document 
      using (IOcrDocument ocrDocument = ocrEngine.DocumentManager.CreateDocument(null, OcrCreateDocumentOptions.AutoDeleteFile)) 
      { 
         // Add the page 
         ocrDocument.Pages.Add(ocrPage); 
         // No need for the page anymore 
         ocrPage.Dispose(); 
 
         // Save the document we have as PDF 
         string pdfFileName = Path.Combine(LEAD_VARS.ImagesDir, "Ocr1.pdf"); 
         ocrDocument.Save(pdfFileName, DocumentFormat.Pdf, null); 
      } 
 
      // Shutdown the engine 
      // Note: calling Dispose will also automatically shutdown the engine if it has been started 
      ocrEngine.Shutdown(); 
   } 
} 
 
static class LEAD_VARS 
{ 
   public const string ImagesDir = @"C:\Users\Public\Documents\LEADTOOLS Images"; 
}

Imports Leadtools 
Imports Leadtools.Codecs 
Imports Leadtools.Ocr 
Imports Leadtools.Document.Writer 
 
Public Sub StartupEngineExample() 
   ' Use RasterCodecs to load an image file 
   ' Note: You can let the engine load the image file directly as shown in the other examples 
   Dim codecs As New RasterCodecs() 
   Dim image As RasterImage = codecs.Load(Path.Combine(LEAD_VARS.ImagesDir, "Ocr1.tif")) 
 
   ' Assume you copied the engine runtime files to C:\MyApp\Ocr 
   Dim engineDir As String = "C:\MyApp\Ocr" 
 
   ' Store the engine work directory into a path inside our application 
   Dim workDir As String = "C:\MyApp\OcrTemp" 
 
   ' Delete all files in the work directory in case the previous version of our application exited abnormally and 
   ' the engine did not get the chance to clean all of its temporary files (if any) 
   Directory.Delete(workDir, True) 
 
   ' Re-create the work directory 
   Directory.CreateDirectory(workDir) 
 
   ' Create an instance of the engine 
   Using ocrEngine As IOcrEngine = OcrEngineManager.CreateEngine(OcrEngineType.LEAD, False) 
      ' Show that the engine has not been started yet 
      Console.WriteLine("Before calling Startup, IsStarted = " & ocrEngine.IsStarted) 
 
      ' Start the engine using our parameters 
      ' Since we already have a RasterCodecs object, we can re-use it to save memory and resources 
      ocrEngine.Startup(codecs, Nothing, workDir, engineDir) 
 
      ' Make sure the engine is using our working directory 
      Console.WriteLine("workDir passed is {0}, the value of WorkDirectory after Startup is {1}", workDir, ocrEngine.WorkDirectory) 
 
      ' Show that the engine has started fine 
      Console.WriteLine("After calling Startup, EngineType is {0}, IsStarted = {1}", ocrEngine.EngineType, ocrEngine.IsStarted) 
 
      ' Maks sure the engine is using our own version of RasterCodecs 
      Debug.Assert(codecs Is ocrEngine.RasterCodecsInstance) 
 
      ' Create a page from the raster image as page to the document 
      Dim ocrPage As IOcrPage = ocrEngine.CreatePage(image, OcrImageSharingMode.AutoDispose) 
      ' image belongs to the page and will be dispose when the page is disposed 
 
      ' Recognize the page 
      ' Note, Recognize can be called without calling AutoZone or manually adding zones. The engine will 
      ' check and automatically auto-zones the page 
      ocrPage.Recognize(Nothing) 
 
      ' Create a file based document 
      Using ocrDocument As IOcrDocument = ocrEngine.DocumentManager.CreateDocument(Nothing, OcrCreateDocumentOptions.AutoDeleteFile) 
         ' Add the page 
         ocrDocument.Pages.Add(ocrPage) 
         ' No need for the page anymore 
         ocrPage.Dispose() 
 
         ' Save the document we have as PDF 
         Dim pdfFileName As String = Path.Combine(LEAD_VARS.ImagesDir, "Ocr1.pdf") 
         ocrDocument.Save(pdfFileName, DocumentFormat.Pdf, Nothing) 
      End Using 
 
      ' Shutdown the engine 
      ' Note: calling Dispose will also automatically shutdown the engine if it has been started 
      ocrEngine.Shutdown() 
   End Using 
End Sub 
 
Public NotInheritable Class LEAD_VARS 
   Public Const ImagesDir As String = "C:\Users\Public\Documents\LEADTOOLS Images" 
End Class