#include "ltocr.h"
L_LTOCR_API L_INT EXT_FUNCTION L_OcrEngine_Startup(engine, workDirectory, engineDirectory)
Starts the OCR engine.
Handle to the OCR engine.
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).
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:\LEADTOOLS21).
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.
Value | Meaning |
---|---|
SUCCESS | The function was successful. |
< 1 | An error occurred. Refer to Return Codes. |
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.
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:\\LEADTOOLS21\\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
:
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:
app.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.
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
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_Advantage, &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_Advantage:
std::wcout << "Started OCR engine type: Advantage\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;
}