Multi-Threading with LEADTOOLS OCR

The .NET OCR class library (Leadtools.Forms.Ocr) provides a common gateway to the various OCR runtime engines available with LEADTOOLS. Use the OcrEngineManager.CreateEngine method with the runtime engine type required to obtain an instance of the Leadtools.Forms.Ocr.IOcrEngine:


             // Create an instance of the OCR engine of a given type
             IOcrEngine ocrEngineInstance = OcrEngineManager.CreateEngine(ocrEngineType, useThunkServer)
             // Start up the engine and use it ...

From this instance, you can then obtain one or more instances of Leadtools.Forms.Ocr.IOcrDocument (or Leadtools.Forms.Ocr.IOcrAutoRecognizeManager that creates IOcrDocuments internally) that is used to perform all OCR operations needed: from loading source images such as TIF and raster PDF; zoning; and recognizing and exporting to a PDF, DOC, DOCX(2007/2010), HTML or TXT final document. Do so as follows:


             // Create an instance of OCR document from the engine
             IOcrDocument ocrDocument= ocrEngineInstance.DocumentManager.CreateDocument();
             // Add pages, zone them, recognize them and save them
             // to the final document:
             ocrDocument.Pages.AddPages(imageFileName, null);
             ocrDocument.Recognize(null);
             ocrDocument.Save(documentFileName, DocumentFormat.Pdf, null);


             // Use IOcrAutoRecognizeManager to automatically recognize a document
             IOcrAutoRecognizeJob ocrJob = ocrEngine.AutoRecognizeManager.CreateJob(
                new OcrAutoRecognizeJobData(imageFileName, DocumentFormat.Pdf, documentFileName));
             ocrEngine.AutoRecognizeManager.RunJob(ocrJob);

All of these operations are performed in an engine runtime-independent manner by making calls to Leadtools.Forms.Ocr.IOcrEngine, Leadtools.Forms.Ocr.IOcrAutoRecognizeManager, Leadtools.Forms.Ocr.IOcrDocument and other interfaces which interact internally with the engine runtime to perform the action required.

LEADTOOLS has support for the following engine runtimes:

Professional - Fastest and most accurate, supports Asian languages and handwritten recognition
Advantage - Most affordable
Plus - Balanced
Arabic - Specific for Arabic language OCR

Contact the LEADTOOLS support at http://www.leadtools.com for more information.

Depending on application requirements, platform and OCR engine runtime type; a "Thunk" mechanism may be required when using the LEADTOOLS OCR modules. The LEADTOOLS OCR Thunk Server is a COM+ object that can be used to host an instance of internal OCR engine runtime in a separate process and provide support for the following:

Some of the OCR engines only have 32-bit (x86) runtimes that cannot be used normally by a 64-bit (x64) application. The Thunk Server internally marshals the calls between the 64-bit application and the 32-bit runtime seamlessly.
Some OCR engines are not thread-safe. Therefore, you cannot create more than one instance of Leadtools.Forms.Ocr.IOcrEngine in an application at the same time and in the same process. This restriction is removed when using the Thunk Server since each instance of the OCR runtime is stored in a separate process. Note that you can create an instance of Leadtools.Forms.Ocr.IOcrEngine, dispose of it, and then create another instance without any restrictions.

The useThunkServer parameter of the OcrEngineManager.CreateEngine method can be used to determine when the Thunk Server is used, based on the following table:

Note: In this table "platform" means the application's native platform (whether it is x86 and x64, not the operating system).

OCR Engine Type	Platform	useThunkServer value	Notes
Advantage	x86	False/True	Ignored. Advantage OCR engine runtime is thread safe. The Thunk Server is never used with this engine.
Advantage	x64	False/True	Ignored. Advantage OCR engine runtime is thread safe and supports x64 natively. The Thunk Server is never used with this engine.
Professional/Plus/Arabic	x86	False	The Thunk Server is not used and the engine runtime is loaded in the same process as the calling application. Use this if only one instance of Leadtools.Forms.Ocr.IOcrEngine will be created at the same time and in the same process.
Professional/Plus/Arabic	x86	True	The Thunk Server is used and the engine runtime is loaded in a separate process from the calling application. Use this if multiple instance of Leadtools.Forms.Ocr.IOcrEngine will be created at the same time and in the same process.
Professional/Plus/Arabic	x64	False	Ignored, the Thunk Server will always be used because the OCR runtime does not support x64 natively. Instead the engine runtime will be loaded in a separate process. Thus, multiple Leadtools.Forms.Ocr.IOcrEngine instance can be created in the same time by the calling process.
Professional/Plus/Arabic	x64	True	Ignored, the Thunk Server will always be used because the OCR runtime does not support x64 natively. Instead the engine runtime will be loaded in a separate process. Thus, multiple Leadtools.Forms.Ocr.IOcrEngine instance can be created in the same time by the calling process.

The LEADTOOLS OCR interfaces are designed to handle all the data marshaling internally. Your application program will not change if the Thunk Server is used; you can switch between using the Thunk Server or not by simply changing the value of useThunkServer.

All this marshaling behinds the scene may cause a certain performance penalty. Thus, it is recommended that you design your application to not use the Thunk Server if possible by using the Advantage OCR engine, developing for x86 only (which runs on x64 platforms) or using one of the multi-threading techniques that do not require the Thunk Server when multi-threaded is needed in a server-based application (as described below).

Multi-threaded OCR application can be achieved using two ways:

Multi-threaded OCR Applications Using Multiple Engines

In this scenario, you create and use a dedicated Leadtools.Forms.Ocr.IOcrEngine instance in each thread. From the table above, we can deduce that useThunkServer must be true when creating these instances. Of course, in the Advantage OCR engine case, useThunkServer is never used.

All the LEADTOOLS OCR engines in all platforms support this scenario.

The OCR Multi-threaded Demo source code shipping with LEADTOOLS shows an example of this scenario in the following cases:

The x64 version of the demo
In the x86 version; the Professional and Advantage OCR engines use the multi Leadtools.Forms.Ocr.IOcrDocument or multi IOcrAutoRecognizeManager.RunJob technique described in the next section, but if the Plus or Arabic OCR engines are used, then multiple IOcrEngines are created using the Thunk Server

The x86 and x64 C# and VB demo source code can be found at these locations:


             [LEADTOOLS Installation Folder]\Examples\DotNet\CS\OcrMultiThreadingDemo


             [LEADTOOLS Installation Folder]\Examples\DotNet\VB\OcrMultiThreadingDemo

Multi-threaded OCR Applications Using Multiple Documents

Leadtools.Forms.Ocr.IOcrDocument is the fully contained object that is used to load source images such as TIF and raster PDF, zoning, recognizing and exporting to final a document of type PDF, DOC, DOCX(2007/2010), HTML or TXT. Thus, another way to achieve multi-threading in an OCR application is to create one instance of Leadtools.Forms.Ocr.IOcrEngine in the main thread. Then, queue work items in dedicated threads with each using its own Leadtools.Forms.Ocr.IOcrDocument instance. Leadtools.Forms.Ocr.IOcrAutoRecognizeManager is a helper interface that creates Leadtools.Forms.Ocr.IOcrDocuments internally and can be used in the same way as described above.

Since only one instance of Leadtools.Forms.Ocr.IOcrEngine will be created at any time, the Thunk Server is not needed and no performance penalty occurs.

Not all OCR engine types support this scenario. They are liste in the table below:

OCR Engine Type	Platform	Multi-Document supported
Advantage	x86/x64	Yes with unlimited number of documents at the same time.
Professional	x86	Yes with up to 64 documents at the same time.
Professional	x64	No
Plus/Arabic	x86/x64	No

The OCR Multi-threaded Demo source code shipping with LEADTOOLS shows an example of this scenario in the following cases:

In the x86 version with the Professional or Advantage OCR engines

Sample Applications

The following lists sample applications and then recommend a way to achieve thread-safety and process integrity when using LEADTOOLS OCR engines.

OCR HTTP Web Service Version 1

An HTTP Web Service application generally runs in a session-less mode. Resources cannot be shared between multiple connections.

Create a Web Service application and add the following method:


             
             [WebMethod]
             public void Recognize(string imageFileName, DocumentFormat format, string documentFileName)
             {
                // Unlock support
                string MY_LICENSE_FILE = "d:\\temp\\TestLic.lic";
                string MY_DEVELOPER_KEY = "xyz123abc";
                RasterSupport.SetLicense(MY_LICENSE_FILE, MY_DEVELOPER_KEY);
                // Create the engine using the Thunk Server
                using(IOcrEngine ocrEngine = OcrEngineManager.CreateEngine(OcrEngineType.[EngineTypeHere], true))
                {
                   // Start it
                   ocrEngine.Startup(null, null, null, @"C:\LEADTOOLS 18\Bin\Common\OcrAdvantageRuntime");
                   // Recognize
                   IOcrAutoRecognizeJob ocrJob = ocrEngine.AutoRecognizeManager.CreateJob(
                      new OcrAutoRecognizeJobData(imageFileName, format, documentFileName));
                   ocrEngine.AutoRecognizeManager.RunJob(ocrJob);
                }
             }

In this version, we created a web method in an HTTP Web Service to recognize an input image file to an output document file in a specific format. We created an Leadtools.Forms.Ocr.IOcrEngine with useThunkServer set to true to insure thread-safety. The code above will work for all engines and in all platforms.

Engines and Platforms Supported: All.

Pros: Easy to implement.

Cons: Performance hit from marshalling using the Thunk Server. Process memory and resources are shared between all connections.

OCR HTTP Web Service Version 2

Create an x86 console application (MyOcrRecognize.exe) that performs OCR:


             static void Main(string[] args)
             {
                // Get the parameters
                string imageFileName = args[0];
                DocumentFormat format = (DocumentFormat)Enum.Parse(typeof(DocumentFormat), args[1]);
                string documentFileName = args[2];
            
                // Unlock support
                string MY_LICENSE_FILE = "d:\\temp\\TestLic.lic";
                string MY_DEVELOPER_KEY = "xyz123abc";
                RasterSupport.SetLicense(MY_LICENSE_FILE, MY_DEVELOPER_KEY);
                // Create the engine without Thunk Server
                using(IOcrEngine ocrEngine = OcrEngineManager.CreateEngine(OcrEngineType.[EngineTypeHere], false))
                {
                   // Start it
                   ocrEngine.Startup(null, null, null, @"C:\LEADTOOLS 18\Bin\Common\OcrAdvantageRuntime");
                   // Recognize
                   IOcrAutoRecognizeJob ocrJob = ocrEngine.AutoRecognizeManager.CreateJob(
                      new OcrAutoRecognizeJobData(imageFileName, format, documentFileName));
                   ocrEngine.AutoRecognizeManager.RunJob(ocrJob);
                }
             }

Create a Web Service application and add the following method:


             [WebMethod]
             public void Recognize(string imageFileName, DocumentFormat format, string documentFileName)
             {
                // Call our OCR console app
                string arguments = "\"" + imageFileName + "\"" + format.ToString() + "\"" + documentFileName + "\"";
                Process.Start("MyOcrRecognize.exe", arguments);
             }

In this version, we create two applications:

An x86 console application that creates an Leadtools.Forms.Ocr.IOcrEngine and performs OCR without using the Thunk Server since each instance of this application will run in its own process. Options are passed through the standard command line.

And a web method in an HTTP Web Service that creates new instance of the OCR application for each request.

Engines and Platforms Supported: All.

Pros: No performance hit from marshalling using the Thunk Server. Complete process separation and safety. Each connection will use its own dedicated process to OCR.

Cons: Performance hit from creating and destroying processes. More complex to implement than the first version.

OCR Windows Service or Server Version 1

A Windows Service or Server generally runs in a session-enabled mode. Resources can be shared between multiple connections. The server will usually create a thread to process each connection.

Typically, a Windows Service or Server has the following methods: StartServer, ProcessRequest and StopServer.

This is the first version implementation of the service/server:


             void StartServer()
             {
                // Unlock support once here
                string MY_LICENSE_FILE = "d:\\temp\\TestLic.lic";
                string MY_DEVELOPER_KEY = "xyz123abc";
                RasterSupport.SetLicense(MY_LICENSE_FILE, MY_DEVELOPER_KEY);
             }
            
             void StopServer()
             {
             }
            
             void ProcessRequest(string imageFileName, DocumentFormat format, string documentFileName)
             {
                // Queue the work
                ThreadPool.QueueUserWorkItem(delegate(object o)
                {
                   // Create the engine using the Thunk Server
                   using(IOcrEngine ocrEngine = OcrEngineManager.CreateEngine([EngineTypeHere], true))
                   {
                      // Start it
                      ocrEngine.Startup(null, null, null, @"C:\LEADTOOLS 18\Bin\Common\OcrAdvantageRuntime");
                      // Recognize
                      IOcrAutoRecognizeJob ocrJob = ocrEngine.AutoRecognizeManager.CreateJob(
                         new OcrAutoRecognizeJobData(imageFileName, format, documentFileName));
                      ocrEngine.AutoRecognizeManager.RunJob(ocrJob);
                   }
                });
             }

Engines and Platforms Supported: All.

Pros: Easy to implement.

Cons: Performance hit from marshalling using the Thunk Server. Process memory and resources are shared between all connections.

OCR Windows Service or Server Version 2

In version 2, we will re-use MyOcrRecognize.exe from earlier to perform the OCR operation in a separate process:


             void StartServer()
             {
             }
            
             void StopServer()
             {
             }
            
             void ProcessRequest(string imageFileName, DocumentFormat format, string documentFileName)
             {
                // Queue the work
                ThreadPool.QueueUserWorkItem(delegate(object o)
                {
                   // Call our OCR console app
                   string arguments = "\"" + imageFileName + "\"" + format.ToString() + "\"" + documentFileName + "\"";
                   Process.Start("MyOcrRecognize.exe", arguments);
                });
             }

Engines and Platforms Supported: All.

Pros: No performance hit from marshalling using the Thunk Server. Complete process separation and safety. Each connection will use its own dedicated process to OCR.

Cons: Performance hit from creating and destroying processes. More complex to implement than the first version.

OCR Windows Service or Server Version 3

In version 3, we will use the multi-document capabilities of the engine (if supported) to perform true multi-threading:


             // Shared instance of IOcrEngine
             private IOcrEngine ocrEngine;
            
             void StartServer()
             {
                // Unlock support
                string MY_LICENSE_FILE = "d:\\temp\\TestLic.lic";
                string MY_DEVELOPER_KEY = "xyz123abc";
                RasterSupport.SetLicense(MY_LICENSE_FILE, MY_DEVELOPER_KEY);
                // Start the OCR engine without using the Thunk Server
                ocrEngine = OcrEngineManager.CreateEngine([EngineTypeHere], false));
                // Start it
                ocrEngine.Startup(null, null, null, @"C:\LEADTOOLS 18\Bin\Common\OcrAdvantageRuntime");
             }
            
             void StopServer()
             {
                // Stop the OCR engine
                ocrEngine.Dispose();
             }
            
             void ProcessRequest(string imageFileName, DocumentFormat format, string documentFileName)
             {
                // Queue the work
                ThreadPool.QueueUserWorkItem(delegate(object o)
                {
                   // Recognize
                   IOcrAutoRecognizeJob ocrJob = ocrEngine.AutoRecognizeManager.CreateJob(
                      new OcrAutoRecognizeJobData(imageFileName, format, documentFileName));
                   ocrEngine.AutoRecognizeManager.RunJob(ocrJob);
                });
             }

Engines and Platforms Supported: Advantage x86 and x64, Professional x86.

Pros: No performance hit from marshalling using the Thunk Server. True multi-threading.

Cons: Not supported by all OCR engines and platforms. Restriction on number of recognition operation in some engines (64 in Professional).