In This Topic ▼

L_OcrEngine_Startup

Summary

Starts the OCR engine.

Syntax

#include "ltocr.h"

L_LTOCR_API L_INT EXT_FUNCTION L_OcrEngine_Startup(engine, workDirectory, engineDirectory)

Parameters

L_OcrEngine engine

Handle to the OCR engine.

const L_TCHAR* workDirectory

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

const L_TCHAR* engineDirectory

The path to the folder containing the OCR engine runtime files.
By default, during setup the LEADTOOLS OCR Module setup installs the OCR engine files to "Installation Path\Bin\Common\OcrLEADRuntime" where Installation Path is the root folder where the LEADTOOLS for C API is installed (for example, C:\LEADTOOLS23).
If you pass NULL to this parameter then the LEADTOOLS OCR engine will look for these extra files in the default installation folder specified above.
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 L_OcrEngine_Startup method.

Returns

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

Comments

This method must be called before invoking any other methods or properties in this L_OcrEngine.

To check if the engine is started, use the L_OcrEngine_IsStarted method.

You must call L_OcrEngine_Shutdown to shut down the engine or you can also call L_OcrEngine_Destroy to shut down the engine and free the settings, memory and resources used.

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

Runtime Directories

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

OCR Engine	Directory
LEAD (L_OcrEngineType_LEAD)	Bin\Common\OcrLEADRuntime

Therefore, to start up an OCR engine pass the corresponding directory name in the engineDirectory parameters:

// Start the LEAD OCR Engine passing the path to the LEADTOOLS Setup installation folder. 
L_OcrEngine ocrEngine = NULL; 
L_OcrEngineManager_CreateEngine(L_OcrEngineType_LEAD, &ocrEngine); 
// Startup the engine 
L_OcrEngine_Startup(ocrEngine, NULL, L_TEXT("C:\\LEADTOOLS23\\Bin\\Common\\OcrLEADRuntime"));

For the LEAD engine, the toolkit supports the following as well as a physical path to a directory. All of these are performed when the user passes NULL as the engineDirectory parameter in L_OcrEngine_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 in disk:

YourApp.exe 
ltkrnx.dll 
ltfilx.dll 
ltocrx.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. And it can be simulated in any development environment by adding the LEAD OCR runtime files as "resource" to the project and using the "Copy to output" feature.

Using L_OcrEngine_SetRuntimeFileCallback to redirect the search and load of engine files at runtime to a specified directory.

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

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

L_INT L_OcrEngine_StartupExample() 
{ 
   // Load an image file 
   BITMAPHANDLE bitmap = { 0 }; 
   L_OcrEngine ocrEngine = NULL; 
   L_OcrPage ocrPage = NULL; 
   L_OcrDocumentManager ocrDocumentManager = NULL; 
   L_OcrDocument ocrDocument = NULL; 
 
   // Assume you copied the engine runtime files to C:\MyApp\Ocr 
   const L_TCHAR* engineDir = L_TEXT("C:\\MyApp\\Ocr"); 
 
   // Store the engine work directory into a path inside our application 
   // Note: You can pass NULL for the working directory and LEADTOOLS   
   // will automatically write to a temporary directory. 
   const L_TCHAR* workDir = L_TEXT("C:\\MyApp\\OcrTemp"); 
 
   // Create an instance of the engine    
   L_INT retCode = L_OcrEngineManager_CreateEngine(L_OcrEngineType_LEAD, &ocrEngine); 
   if(retCode != SUCCESS) 
      return retCode; 
 
   //// Show that the engine has not been started yet 
   if(L_OcrEngine_IsStarted(ocrEngine)) 
      std::cout << "Before calling Startup, IsStarted = true\n"; 
   else 
      std::cout << "Before calling Startup, IsStarted = false\n"; 
 
   // Start the engine using our parameters 
   retCode = L_OcrEngine_Startup(ocrEngine, workDir, engineDir); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
 
   // Make sure the engine is using our working directory 
   L_TCHAR workDirAfterStartup[MAX_PATH]; 
   L_OcrEngine_GetWorkDirectory(ocrEngine, workDirAfterStartup, MAX_PATH); 
   std::wcout << "Original workDir passed is \"" << workDir << "\",\nthe value of WorkDirectory after Startup is \"" << workDirAfterStartup << "\"\n"; 
 
   // show the engine directory where the engine runtime binaries resides 
   L_TCHAR engineDirectory[MAX_PATH]; 
   L_OcrEngine_GetWorkDirectory(ocrEngine, engineDirectory, MAX_PATH); 
   std::wcout << "Engine directory: " << engineDir << "\n"; 
 
   // show started engine type 
   L_OcrEngineType engineType; 
   L_OcrEngine_GetEngineType(ocrEngine, &engineType); 
   switch(engineType) 
   { 
      case L_OcrEngineType_LEAD: 
         std::wcout << "Started OCR engine type: LEAD engine\n"; 
         break; 
   } 
 
   // Show that the engine has started fine 
   if(L_OcrEngine_IsStarted(ocrEngine)) 
      std::cout << "After calling Startup, IsStarted = true\n"; 
   else 
   { 
      std::cout << "After calling Startup, IsStarted = false\n"; 
      goto CLEANUP; 
   } 
 
   // Load an image to process 
   retCode = L_LoadBitmap(MAKE_IMAGE_PATH(L_TEXT("Ocr1.tif")), &bitmap, sizeof(BITMAPHANDLE), 0, ORDER_RGB, NULL, NULL); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
 
   // Add an image to OCR page. Transfer ownership of the bitmap to the page 
   retCode = L_OcrPage_FromBitmap(ocrEngine, &ocrPage, &bitmap, L_OcrBitmapSharingMode_AutoFree, NULL, NULL); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
 
   // At this point, we have a valid page and bitmap ownership has transfered, so, we do not need to free the bitmap anymore 
   bitmap.Flags.Allocated = 0; 
 
   // 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 (as illustrated here). 
   retCode = L_OcrPage_Recognize(ocrPage, NULL, NULL); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
 
   // Get the Document Manager 
   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; 
 
   // In Document File Mode, add OcrPage to OcrDocument after recognition 
   retCode = L_OcrDocument_AddPage(ocrDocument, ocrPage); 
   if(retCode != SUCCESS) 
      goto CLEANUP; 
 
   // Adding the page to a file based document will take a snap shot of the recognition data and store it in the document. At this 
   // point, the page is no longer needed. So destroy it to free up memory not used anymore 
   L_OcrPage_Destroy(ocrPage); 
   // Set the handle to NULL so we do not free it in our clean-up code 
   ocrPage = NULL; 
 
   // Save the document we have as PDF 
   retCode = L_OcrDocument_Save(ocrDocument, MAKE_IMAGE_PATH(L_TEXT("Ocr1.pdf")), DOCUMENTFORMAT_PDF, NULL, NULL); 
 
CLEANUP: 
   if(bitmap.Flags.Allocated) 
      L_FreeBitmap(&bitmap); 
 
   if(ocrPage != NULL) 
      L_OcrPage_Destroy(ocrPage); 
 
   if(ocrDocument != NULL) 
      L_OcrDocument_Destroy(ocrDocument); 
 
   if(ocrEngine != NULL) 
      L_OcrEngine_Destroy(ocrEngine); 
 
   return retCode; 
}