Thanks for downloading Dynamsoft Label Recognizer Package!

Your download will start shortly. If your download does not begin, click here to retry.

User Guide - C++

In this guide, you will learn step by step on how to build a label recognizer application with Dynamsoft Label Recognizer SDK using C++ language.

Read more on Dynamsoft Label Recognizer Features

Table of Contents

User Guide - C++

Requirements

Windows
- Windows 7, 8, 10, 2003, 2008, 2008 R2, 2012.
- Visual Studio 2012 or above
Linux
- Linux x64: Ubuntu 14.04.4+ LTS, Debian 8+, etc.
- GCC 5.4+

Installation

If you don’t have SDK yet, please go to Dynamsoft website to get it. After the folder is decompressed, the root directory of the DLR installation package is called [INSTALLATION FOLDER] in this guide.

Build Your First Application

Let’s start by creating a console application which demonstrates the minimum code needed to recognize text from an image file.

You can download the complete source code from here.

Create A New Project

For Windows

Open Visual Studio. Go to File > New > Project, select Empty App and enter RecognizeAnImage in the name text box.
Add a new source file named RecognizeAnImage.cpp into the project.

For Linux

Create a new source file named RecognizeAnImage.cpp and place it into the folder [INSTALLATION FOLDER]\Dynamsoft\Resources\LabelRecognizer\Samples\HelloWorld\RecognizeAnImage.

Create a file named Makefile and put it in the same directory as the file RecognizeAnImage.cpp. The content of Makefile is as follows:

 CC=gcc
 CCFLAGS=-c -std=c++11

 DLRMODEL_PATH=../../../Distributables/CharacterModel
 DS_LIB_PATH=../../../Distributables/Lib/Linux/x64
 DS_JSON_PATH=../../../Distributables/DLR-PresetTemplates.json
 LDFLAGS=-L $(DS_LIB_PATH) -Wl,-rpath=$(DS_LIB_PATH) -Wl,-rpath=./
 DS_LIB=-lDynamsoftCaptureVisionRouter -lDynamsoftCore -lDynamsoftLicense

 STDLIB=-lstdc++

 TARGET=RecognizeAnImage
 OBJECT=RecognizeAnImage.o
 SOURCE=RecognizeAnImage.cpp

 # build rule for target.
 $(TARGET): $(OBJECT)
     $(CC) -o $(TARGET) $(OBJECT) $(STDLIB) $(DS_LIB) $(LDFLAGS)
     cp -r $(DLRMODEL_PATH) $(DS_LIB_PATH)
     cp  $(DS_JSON_PATH) $(DS_LIB_PATH)

 # target to build an object file
 $(OBJECT): $(SOURCE)
     $(CC) $(CCFLAGS) $(SOURCE)

 # the clean target
 .PHONY : clean
 clean: 
     rm -f $(OBJECT) $(TARGET) -r $(DS_LIB_PATH)/CharacterModel

Note: The DS_LIB_PATH variable should be set to the correct directory where the DLR library files are located. The files and character models directory can be found in [INSTALLATION FOLDER]/Dynamsoft/Distributables/Lib/Linux/x64.

Include the Library

Add headers and libs in RecognizeAnImage.cpp.

 #include <iostream>
 #include <string>
 #include "[INSTALLATION FOLDER]/Dynamsoft/Include/DynamsoftCaptureVisionRouter.h"

 using namespace std;
 using namespace dynamsoft::cvr;
 using namespace dynamsoft::dlr;
 using namespace dynamsoft::license;

 // The following code only applies to Windows.
 #if defined(_WIN64) || defined(_WIN32)
     #ifdef _WIN64
         #pragma comment(lib, "[INSTALLATION FOLDER]/Dynamsoft/Distributables/Lib/Windows/x64/DynamsoftCaptureVisionRouterx64.lib")
         #pragma comment(lib, "[INSTALLATION FOLDER]/Dynamsoft/Distributables/Lib/Windows/x64/DynamsoftCorex64.lib")
         #pragma comment(lib, "[INSTALLATION FOLDER]/Dynamsoft/Distributables/Lib/Windows/x64/DynamsoftLicensex64.lib")
     #else
         #pragma comment(lib, "[INSTALLATION FOLDER]/Dynamsoft/Distributables/Lib/Windows/x86/DynamsoftCaptureVisionRouterx86.lib")
         #pragma comment(lib, "[INSTALLATION FOLDER]/Dynamsoft/Distributables/Lib/Windows/x86/DynamsoftCorex86.lib")
         #pragma comment(lib, "[INSTALLATION FOLDER]/Dynamsoft/Distributables/Lib/Windows/x86/DynamsoftLicensex86.lib")
     #endif
 #endif

Initialize a Capture Vision Router Instance

Initialize the license key
```
 char error[512];
    
 CLicenseManager::InitLicense("DLS2eyJvcmdhbml6YXRpb25JRCI6IjIwMDAwMSJ9", error, 512);
 cout << "License initialization: " << error << endl;
```
Note:
- An internet connection is required for the license to work.
- “DLS2***” is a default free public trial license used in the sample.
- If the license has expired, please request an extension through the customer portal.

Create an instance of Dynamsoft Capture Vision Router

 CCaptureVisionRouter* router = new CCaptureVisionRouter();

Recognize and Output Recognition Results

Recognize an image file

 string imageFile = "[INSTALLATION FOLDER]/Dynamsoft/Resources/LabelRecognizer/Images/dlr-sample-vin.png";
 CCapturedResult* result = router->Capture(imageFile.c_str(), CPresetTemplate::PT_RECOGNIZE_TEXT_LINES);

Note:

Please change all [INSTALLATION FOLDER] in above code snippet to your unpacking path.

Output the recognition results

 cout << "File: " << imageFile << endl;

 if (result->GetErrorCode() != 0) {
     cout << "Error: " << result->GetErrorCode() << "," << result->GetErrorString() << endl;
 }

 int count = result->GetItemsCount();
 cout << "Recognized " << count << " text lines" << endl;
 for (int i = 0; i < count; i++) {
     const CCapturedResultItem* item = result->GetItem(i);

     CapturedResultItemType type = item->GetType();
     if (type == CapturedResultItemType::CRIT_TEXT_LINE) {
         const CTextLineResultItem* textLine = dynamic_cast<const CTextLineResultItem*>(item);

         cout << ">>Line result " << i << ": " << textLine->GetText() << endl;
     }
 }

Release the Allocated Memory

result->Release();
delete router, router = NULL;

Build and Run the Project

On windows

Build the application through Visual Studio.
Copy the related DLL files to the same folder as the EXE file. The DLL files can be found in [INSTALLATION FOLDER]\Dynamsoft\Distributables\Lib\Windows\[platforms]

Note: Select the corresponding folder (x86 or x64) based on your project’s platform setting.
Copy the [INSTALLATION FOLDER]\Dynamsoft\Distributables\CharacterModel directory to the same folder as the EXE file.
Copy the [INSTALLATION FOLDER]\Dynamsoft\Distributables\DLR-PresetTemplates.json file to the same folder as the EXE file.
Run the program RecognizeAnImage.exe.

On Linux

Open a terminal and change to the target directory where Makefile located in. Build the sample:
```
 >make
```
Run the program RecognizeAnImage.
```
 >./RecognizeAnImage
```

Process Multiple Images

If you need to process multiple images at once instead of one image, you can follow these steps:

Preparation Steps

Create a new project named RecognizeMultipleImages.
Initialize a Capture Vision Router Instance.
Include the Library.

You can download the complete source code from here.

Add an Image Source as the Input

The class CDirectoryFetcher is capable of converting a local directory to an image source. We will use it to connect multiple images to the image-processing engine.

Include additional DynamsoftUtility module which contains CDirectoryFetcher.

 using namespace dynamsoft::utility;

 // The following code only applies to Windows.
 #if defined(_WIN64) || defined(_WIN32)
     #ifdef _WIN64
         #pragma comment(lib, "[INSTALLATION FOLDER]/Dynamsoft/Distributables/Lib/Windows/x64/DynamsoftUtilityx64.lib")
     #else
         #pragma comment(lib, "[INSTALLATION FOLDER]/Dynamsoft/Distributables/Lib/Windows/x86/DynamsoftUtilityx86.lib")
     #endif
 #endif

Setting up a directory fetcher to retrieve image data sources from a directory.

 CDirectoryFetcher *dirFetcher = new CDirectoryFetcher;
 dirFetcher->SetDirectory("[Your Image Path]");

 router->SetInput(dirFetcher);

Create a class MyImageSourceStateListener to implement the CImageSourceStateListenter interface, and call StopCapturing in the callback function.

 class MyImageSourceStateListener : public CImageSourceStateListener
 {
 private:
     CCaptureVisionRouter* m_router;

 public:
     MyImageSourceStateListener(CCaptureVisionRouter* router) {
         m_router = router;
     }

     virtual void OnImageSourceStateReceived(ImageSourceState state)
     {
         if(state == ISS_EXHAUSTED)
             m_router->StopCapturing();
     }
 };

 CImageSourceStateListener *listener = new MyImageSourceStateListener(router);
 router->AddImageSourceStateListener(listener);

Add Captured Result Receiver

Create a class MyResultReceiver to implement the CCapturedResultReceiver interface, and get the recognition results in OnRecognizedTextLinesReceived callback function.

 class MyResultReceiver : public CCapturedResultReceiver
 {
 public:
     virtual void OnRecognizedTextLinesReceived(CRecognizedTextLinesResult* pResult)
     {
         if(pResult->GetErrorCode() != EC_OK)
             cout << "Error: " << pResult->GetErrorString() << endl;

         int lCount = pResult->GetItemsCount();
         cout << "Recognized " << lCount << " text lines" << endl;
         for (int li = 0; li < lCount; ++li)
         {
             const CTextLineResultItem* textLine = pResult->GetItem(li);
             cout << ">>Text line result " << li << ": " << textLine->GetText() << endl;
         }
     }
 };

For the error handling mechanism, the SDK returns Error Code in the CRecognizedTextLinesResult object. You can add error handling code as needed. See Error Code for a full list of supported error codes.

 CCapturedResultReceiver* recv = new MyResultReceiver();
 router->AddResultReceiver(recv);

Start Recognition

Start recognition with the default Label Recognizer Template.
```
 router->StartCapturing(CPresetTemplate::PT_RECOGNIZE_TEXT_LINES, true);
```
Note:
- During the process, the callback function OnRecognizedTextLinesReceived() is triggered each time an image finishes processing. After all images are processed, the listener function OnImageSourceStateReceived() will return the image source state as ISS_EXHAUSTED and the process is stopped with the method StopCapturing().

Release Allocated Memory

delete router, router = NULL;
delete dirFetcher, dirFetcher = NULL;
delete listener, listener = NULL;
delete recv, recv = NULL;

Build and Run the Project Again

Please refer to Build and Run the Project.