class CLabelRecognizer

class dynamsoft::dlr::CLabelRecognizer

Initialization Methods Summary

Method	Description
`CLabelRecognizer`	Initialization of `CLabelRecognizer` object.

Settings Methods Summary

Method	Description
`SetCharacterModelDefaultPath`	Set default directory path of the character models.
`GetRuntimeSettings`	Gets the current settings and saves it into a struct.
`UpdateRuntimeSettings`	Updates runtime settings with a given struct.
`ResetRuntimeSettings`	Resets the runtime settings.
`InitRuntimeSettings`	Initializes a new setting to the current label recognizer instance via template string.
`InitRuntimeSettingsFromFile`	Initializes a new setting to the current label recognizer instance via template file.
`OutputRuntimeSettings`	Output runtime settings to a string.
`OutputRuntimeSettingsToFile`	Outputs LabelRecognizerParameter settings into a file (JSON file).
`UpdateReferenceRegionFromBarcodeResults`	Updates reference region which is defined with source type LST_BARCODE.
`GetModeArgument`	Get argument value for the specified mode parameter.
`SetModeArgument`	Set argument value for the specified mode parameter.

Recognizing Methods Summary

Method	Description
`RecognizeBuffer`	Recognizes text from memory buffer containing image pixels in defined format.
`RecognizeFile`	Recognizes text from a specified image file.
`RecognizeFileInMemory`	Recognizes text from an image file in memory.

Result Methods Summary

Method	Description
`GetAllResults`	Gets all recognized results.
`FreeResults`	Frees memory allocated for recognized results.

General Methods Summary

Method	Description
`GetErrorString`	Returns the error string.
`GetVersion`	Returns the version number string for the SDK.
`FreeString`	Free the allocated string memory.

Initialization Methods Details

CLabelRecognizer

Initialization of CLabelRecognizer object.

CLabelRecognizer()

Code Snippet

CLabelRecognizer* recognizer = new CLabelRecognizer();
delete recognizer;

Settings Methods Details

SetCharacterModelDefaultPath

Set default directory path of the character models.

int SetCharacterModelDefaultPath (const char* modelPath, char errorMsgBuffer[], const int errorMsgBufferLen)

Parameters [in] modelPath The full directory path of character models.
[in,out] errorMsgBuffer The buffer is allocated by caller and the recommending length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen The length of allocated buffer.

Return Value
Returns error code (returns 0 if the function operates successfully). You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
int errorCode = recognizer->SetCharacterModelDefaultPath("C:\\CharacterModel", errorMessage, 256);
delete recognizer;

GetRuntimeSettings

Get current settings and save them into a DLR_RuntimeSettings struct.

int GetRuntimeSettings (DLR_RuntimeSettings* settings)

Parameters

[in,out] settings The struct of runtime settings.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
DLR_RuntimeSettings settings;
int errorCode = recognizer->GetRuntimeSettings(&settings);
delete recognizer;

UpdateRuntimeSettings

Update runtime settings with a given DLR_RuntimeSettings struct.

int UpdateRuntimeSettings (DLR_RuntimeSettings* settings, char errorMsgBuffer[] = NULL, const int errorMsgBufferLen = 0)

Parameters

[in] settings The struct of runtime settings.
[in,out] errorMsgBuffer _Optional The buffer is allocated by caller and the recommended length is 256.The error message will be copied to the buffer.
[in] errorMsgBufferLen _Optional The length of the allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully). You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
DLR_RuntimeSettings settings;
int errorCode = recognizer->GetRuntimeSettings(&settings);
settings.maxThreadCount = 4;
recognizer->UpdateRuntimeSettings(&settings, errorMessage, 256);
delete recognizer;

ResetRuntimeSettings

Reset all runtime settings to default values.

int ResetRuntimeSettings ()

Return value

Returns error code (returns 0 if the function operates successfully). You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
DLR_RuntimeSettings settings;
int errorCode = recognizer->GetRuntimeSettings(&settings);
settings.maxThreadCount = 4;
recognizer->UpdateRuntimeSettings(&settings);
recognizer->ResetRuntimeSettings();
delete recognizer;

InitRuntimeSettings

Initializes a new setting to the current label recognizer instance via template string.

int InitRuntimeSettings(const char* content, char errorMsgBuffer[] = NULL, const int errorMsgBufferLen = 0)

Parameters

[in] content A JSON string that represents the content of the settings. [in,out] errorMsgBuffer _Optional The buffer is allocated by caller and the recommending length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen _Optional The length of allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully). You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
recognizer->InitRuntimeSettings("{\"LabelRecognizerParameter\":{\"Name\":\"P1\", \"RegionPredetectionModes\":[{\"Mode\":\"RPM_GENERAL_HSV_CONTRAST\"}], \"ReferenceRegionNameArray\": [\"R1\"]},\"ReferenceRegion\":{\"Name\":\"R1\",\"Localization\":{\"SourceType\":\"LST_PREDETECTED_REGION\",\"RegionPredetectionModesIndex\":0},\"TextAreaNameArray\":[\"T1\"]},\"TextArea\":{\"Name\":\"T1\",\"CharacterModelName\":\"Number\"}}", errorMessage, 256);
delete recognizer;

InitRuntimeSettingsFromFile

Initializes a new setting to the current label recognizer instance via template file.

int InitRuntimeSettingsFromFile (const char* filePath, char errorMsgBuffer[] = NULL, const int errorMsgBufferLen = 0)

Parameters

[in] filePath The settings file path. [in,out] errorMsgBuffer _Optional The buffer is allocated by caller and the recommending length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen _Optional The length of allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
recognizer->InitRuntimeSettingsFromFile("your file path", errorMessage, 256);
delete recognizer;

OutputRuntimeSettingsToFile

Outputs runtime settings and save them into a settings file (JSON file).

int OutputRuntimeSettingsToFile(const char* templateName, const char* filePath)

Parameters

[in] templateName A unique name for declaring current runtime settings.
[in] filePath The path of the output file which stores current settings.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
recognizer->InitRuntimeSettings("{\"LabelRecognizerParameter\":{\"Name\":\"P1\", \"RegionPredetectionModes\":[{\"Mode\":\"RPM_GENERAL_HSV_CONTRAST\"}], \"ReferenceRegionNameArray\": [\"R1\"]},\"ReferenceRegion\":{\"Name\":\"R1\",\"Localization\":{\"SourceType\":\"LST_PREDETECTED_REGION\",\"RegionPredetectionModesIndex\":0},\"TextAreaNameArray\":[\"T1\"]},\"TextArea\":{\"Name\":\"T1\",\"CharacterModelName\":\"Number\"}}", errorMessage, 256);
recognizer->OutputRuntimeSettingsToFile("P1","C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Templates\\CurrentRuntimeSettings.json");
delete recognizer;

OutputRuntimeSettings

Outputs runtime settings and save them into a settings file (JSON file).

int OutputRuntimeSettings(const char* pSettingsName, char** content)

Parameters [in] pSettingsName A unique name for declaring current runtime settings.
[in,out] content The output string which stores the contents of current settings.If not needed, it should be freed via FreeString.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer;
char *content = NULL;
recognizer->OutputRuntimeSettings("", &content);
CLabelRecognizer::FreeString(&content);
delete recognizer;

UpdateReferenceRegionFromBarcodeResults

Updates reference region which is defined with source type LST_BARCODE.

int UpdateReferenceRegionFromBarcodeResults (const BarcodeResultArray* barcodeResults, const char* templateName)

Parameters

[in] barcodeResults The barcode results used to localize reference region. See also BarcodeResultArray. [in] templateName The template name. A template name is the value of key LabelRecognizerParameter.Name defined in JSON formatted settings. If no template name is specified, current runtime settings will be used.

Return value

Returns error code (returns 0 if the function operates successfully). You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
recognizer->AppendSettingsFromString("{\"LabelRecognizerParameter\":{\"Name\":\"P1\", \"RegionPredetectionModes\":[{\"Mode\":\"RPM_GENERAL_HSV_CONTRAST\"}], \"ReferenceRegionNameArray\": [\"R1\"]},\"ReferenceRegion\":{\"Name\":\"R1\",\"Localization\":{\"SourceType\":\"LST_BARCODE\"},\"TextAreaNameArray\":[\"T1\"]},\"TextArea\":{\"Name\":\"T1\",\"CharacterModelName\":\"Number\"}}", errorMessage, 256);
//Get barcodeResults from Dynamsoft Barcode Reader SDK
recognizer->UpdateReferenceRegionFromBarcodeResults(barcodeResults, "P1");
delete recognizer;

SetModeArgument

Set argument value for the specified mode parameter.

int SetModeArgument (const char* modesName, const int index, const char* argumentName, const char* argumentValue, char errorMsgBuffer[] = NULL,  const int errorMsgBufferLen = 0) 

Parameters

[in] modesName The mode parameter name to set argument.
[in] index The array index of mode parameter to indicate a specific mode.
[in] argumentName The name of the argument to set.
[in] argumentValue The value of the argument to set.
[in,out] errorMsgBuffer_Optional The buffer is allocated by the caller and the recommended length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen_Optional The length of the allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call GetErrorString to get detailed error message.

Remark

Check follow link for available modes and arguments:

RegionPredetectionModes

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
DLR_RuntimeSettings settings;
int errorCode = recognizer->GetRuntimeSettings(&settings);
settings.furtherModes.regionPredetectionModes[0] = RPM_GENERAL_RGB_CONTRAST;
recognizer->UpdateRuntimeSettings(&settings, errorMessage, 256);
recognizer->SetModeArgument("RegionPredetectionModes", 0, "AspectRatioRange", "100", errorMessage, 256);
delete recognizer;

GetModeArgument

Get argument value for the specified mode parameter.

int GetModeArgument (const char* modesName, const int index, const char* argumentName, char valueBuffer[], const int valueBufferLen, char errorMsgBuffer[] = NULL, const int errorMsgBufferLen = 0) 

Parameters

[in] modesName The mode parameter name to get argument.
[in] index The array index of mode parameter to indicate a specific mode.
[in] argumentName The name of the argument to get.
[in,out] valueBuffer The buffer is allocated by caller and the recommended length is 480. The argument value would be copied to the buffer.
[in] valueBufferLen The length of allocated buffer.
[in,out] errorMsgBuffer_Optional The buffer is allocated by the caller and the recommended length is 256. The error message will be copied to the buffer.
[in] errorMsgBufferLen_Optional The length of the allocated buffer.

Return value

Returns error code (returns 0 if the function operates successfully).
You can call GetErrorString to get detailed error message.

Remark

Check follow link for available modes and arguments:

RegionPredetectionModes

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
DLR_RuntimeSettings settings;
int errorCode = recognizer->GetRuntimeSettings(&settings);
settings.furtherModes.regionPredetectionModes[0] = RPM_GENERAL_RGB_CONTRAST;
char argumentValue[480];
recognizer->UpdateRuntimeSettings(&settings, errorMessage, 256);
recognizer->SetModeArgument("RegionPredetectionModes", 0, "AspectRatioRange", "100", errorMessage, 256);
recognizer->GetModeArgument("RegionPredetectionModes", 0, "AspectRatioRange", argumentValue, 480, errorMessage, 256);
delete recognizer;

Recognition Methods

RecognizeBuffer

Recognizes text from the memory buffer containing image pixels in defined format.

int RecognizeBuffer(const CImageData* imageData, const char* templateName)

Parameters

[in] imageData An instance of CImageData that represents an image.
[in] templateName The template name. A template name is the value of key LabelRecognizerParameter.Name defined in JSON formatted settings. If no template name is specified, current runtime settings will be used.

Return value

Returns error code (returns 0 if the function operates successfully). You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();

//Generate imageData from somewhere else
int errorCode = recognizer->RecognizeBuffer(imageData, "");
delete recognizer;

RecognizeFile

Recognizes text from a specified image file.

int RecognizeFile (const char* fileName, const char* templateName) 

Parameters

[in] fileName A string defining the file name.
[in] templateName The template name. A template name is the value of key LabelRecognizerParameter.Name defined in JSON formatted settings. If no template name is specified, current runtime settings will be used.

Return value

Returns error code (returns 0 if the function operates successfully). You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
int errorCode = recognizer->RecognizeFile("C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Images\\AllSupportedBarcodeTypes.tif", "");
delete recognizer;

RecognizeFileInMemory

Recognizes text from a specified image file in memory.

int RecognizeFileInMemory (const unsigned char* pFileBytes, const int fileSize, const char* pTemplateName) 

Parameters
[in] pFileBytes The image file bytes in memory.
[in] fileSize The length of the file bytes in memory.
[in] pTemplateName The template name.

Return Value
Returns error code (returns 0 if the function operates successfully). You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();

unsigned char* pFileBytes;
int nFileSize = 0;
GetFileStream("C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Images\\AllSupportedBarcodeTypes.tif", &pFileBytes, &nFileSize);

int errorCode = recognizer->RecognizeFileInMemory(pFileBytes, nFileSize, "");
delete recognizer;

Result Methods Details

GetAllResults

Get all recognized results.

int GetAllResults (DLR_ResultArray** results) 

Parameters

[out] results Recognized results returned by last calling function RecognizeBuffer / RecognizeFile. The results is allocated by SDK and should be freed by calling function FreeResults.

Return value

Returns error code (returns 0 if the function operates successfully). You can call GetErrorString to get detailed error message.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
DLR_ResultArray * results;
int errorCode = recognizer->RecognizeFile("C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Images\\AllSupportedBarcodeTypes.tif", "");
recognizer->GetAllResults(&results);
CLabelRecognizer::FreeResults(&results);
delete recognizer;

FreeResults

Free memory allocated for text results.

static void FreeResults (DLR_ResultArray ** results) 

Parameters

[in] results Recognized results.

Code Snippet

char errorMessage[256];
CLicenseManager::InitLicense("t0260NwAAAHV***************", errorMessage, 256);

CLabelRecognizer* recognizer = new CLabelRecognizer();
DLR_ResultArray * results;
int errorCode = recognizer->RecognizeFile("C:\\Program Files (x86)\\Dynamsoft\\{Version number}\\Images\\AllSupportedBarcodeTypes.tif", "");
recognizer->GetAllResults(&results);
CLabelRecognizer::FreeResults(&results);
delete recognizer;

General Methods Details

GetErrorString

Get error message by error code.

static const char* GetErrorString (const int errorCode) 

Parameters

[in] errorCode The error code.

Return value

The error message.

Code Snippet

const char* errorString = GetErrorString(errorCode);

GetVersion

Get version information of SDK.

static const char* GetVersion ()

Return value

The version information string.

Code Snippet

const char* versionInfo = GetVersion();

FreeString

Free the allocated string memory.

static void FreeString(char** str)

Parameters

[in] str The allocated string memory.

Code Snippet

CLabelRecognizer* recognizer = new CLabelRecognizer();
char *content = NULL;
recognizer->OutputRuntimeSettings("", &content);
CLabelRecognizer::FreeString(&content);
delete recognizer;