Smart Code Engine SDK Documentation

Smart Code Engine is a multiplatform, stand-alone SDK for recognizing linear and 2D codes, MRZ, bank card numbers and phone numbers, and other codified objects.

Workflow

The CodeEngine workflow consists of the following stages:

1. Creating a recognition engine.
2. Creating a recognition session.
3. Setting session options.
4. Creating an image object.
5. Recognition process.
6. Processing the recognition result.
7. Memory deallocation.

Creating a Recognition Engine

From System Description:

Recognition Engine is the object where all recognition tools are stored and initialized. It is created using the appropriate configuration bundle containing all possible settings: a list of documents supported by a specific SDK, their fields, a list of possible authentication checks, and so on.

INFO

In special cases, the bundle is not supplied separately, but as part of (inside) the library.

Initialize the engine in a single instance. One instance allows you to create multiple recognition sessions. However, creating multiple instances of the engine is also possible.

The initialization process is a resource-intensive operation (as is the image analysis itself), so perform it off the main UI thread.

Create a CodeEngine instance:

C++

std::unique_ptr<se::code::CodeEngine> engine(  
    se::code::CodeEngine::CreateFromEmbeddedBundle(true));

Java

import com.smartengines.code.*;  
CodeEngine engine = CodeEngine.CreateFromEmbeddedBundle(true);

Parameters:

• CreateFromEmbeddedBundle() is a boolean flag enabling/disabling lazy configuration (true by default). Optional.

Creating a Recognition Session

Creating CodeEngineSession

From System Description:

Session settings is an object storing:

• The list of the supported documents for recognition, grouped by internal engines. It is set in the configuration bundle with which the engine was created (read-only);
• Advanced information about documents, including links to PRADO (read-only, used in Smart ID Engine only);
• The list of documents submitted for recognition (* by default);
• The list of expected fields for recognition (all by default);
• The list of document sets (the mode parameter, default by default);
• The special session options: the number of recognition threads, the expansion of the field list, the session timeout, and so on. You can find the full list of the options in our documentation.

Create a CodeEngineSessionSettings object using the configured CodeEngine instance:

C++

std::unique_ptr<se::code::CodeEngineSessionSettings> settings(engine->GetDefaultSessionSettings());

Java

import com.smartengines.code.*;  
CodeEngineSessionSettings settings = engine.GetDefaultSessionSettings();

Attention! CodeEngine::GetDefaultSessionSettings() is a factory method and returns an allocated pointer. The caller is responsible for deleting it.

Setting Session Options

The engine recognizes barcodes in a specific set of frames. This feature is disabled by default.

To enable it, set the appropriate session options:

C++

settings->SetOption("barcode.enabled", "true"); // Enabling the common barcode symbologies recognition in this session

Java

settings.SetOption("barcode.enabled", "true"); //  Enabling the common barcode symbologies recognition in this session

Setting Session Additional Options

An optional stage.
Set additional session options if necessary:

C++

settings->SetOption("barcode.COMMON.enabled", "true"); // Enabling the common barcode symbologies recognition in this session

Java

settings.SetOption("barcode.COMMON.enabled", "true"); // ВEnabling the common barcode symbologies recognition in this session

Setting Barcode Symboligies Recognition

By default, all barcode symbols are disabled.

To enable barcodes, set the following parameter values:

C++

settings->SetOption("barcode.<symbology>.enabled", "true");

Java

settings.SetOption("barcode.<symbology>.enabled", "true");

The supported barcode symbologies are shown in the table:

Name	Barcode Symbology	Description
COMMON	AZTEC; QR_CODE; DATA_MATRIX; PDF_417; CODABAR; CODE_128; EAN_8; EAN_13_UPC_A; ITF; UPC_E; CODE_39; CODE_93	The most commonly used symbols. They can be connected individually
ALL	AZTEC; QR_CODE; MICRO_QR; RMQR; DATA_MATRIX; PDF_417; MICRO_PDF_417; CODABAR; CODE_128; EAN_8; EAN_13_UPC_A; ITF; UPC_E; CODE_39; CODE_93	All supported symbols. They can be connected individually
ALL_1D	CODE_128; EAN_8; EAN_13_UPC_A; ITF; UPC_E; CODE_39; CODE_93	One-dimensional barcodes. They can be connected individually
ALL_2D	AZTEC; QR_CODE; MICRO_QR; RMQR; DATA_MATRIX; PDF_417; MICRO_PDF_417	Two-dimensional barcodes. They can be connected individually

Enable the COMMON set of barcodes in the recognition process:

C++

settings->SetOption("barcode.COMMON.enabled", "true");

Java

settings.SetOption("barcode.COMMON.enabled", "true");

Enable the ALL set of barcodes:

C++

settings->SetOption("barcode.ALL.enabled", "true");

Java

settings->SetOption("barcode.ALL.enabled", "true");

Attention!

We recommend to enable only the required symbologies to improve performance.

The recognition result contains two fields:

• bytes is the data field in the base64 format;
• value is the data field in a human readable format or (if it is impossible) is a copy of the bytes data field. Encoding of this field specifies which type of content it has. The common value is utf8 or base64.

There are three main scenarios for barcode recognition:

• focused — processing barcodes using handheld camera recognition in video stream when the code occupies the significant area of the source image;
• anywhere — processing barcodes on any image in any location. A resource consuming operation. It can be used to process any image from the gallery. It is recommended to use this scenario for recognizing images from the gallery;
• dummy — mainly used when the location of the barcode is predefined.

Attention!

For payment barcodes, it is recommended to set the following options:

• QR, Aztec and DataMatrix barcode symbologies enabled;
• focused recognition mode;
• maxAllowedCodesPerFrame=1 — restricting the maximum number of recognized barcodes to one.

To enable the required mode, set the session option:

C++

settings->SetOption("barcode.roiDetectionMode", "focused");

Java

settings.SetOption("barcode.roiDetectionMode", "focused");

By default, the barcode feed mode is set to single:barcode recognition stops after one barcode is found.

To recognize several barcodes, set feedmode to sequence.

C++

settings->SetOption("barcode.feedMode", "sequence");

Java

settings.SetOption("barcode.feedMode", "sequence");

There is a set of structured text messages commonly encoded using barcodes. You can provide a hint which structured message you expect to meet in your session. This hint is called preset and implies a set of fields. By default, no preset is enabled.

To enable a preset, set the special session option:

C++

settings->SetOption("barcode.preset", "AAMVA");

Java

settings.SetOption("barcode.preset", "AAMVA");

You can specify a complex preset:

C++

settings->SetOption("barcode.preset", "URL|PAYMENT");

Java

settings.SetOption("barcode.preset", "URL|PAYMENT");

where the option value contains a set of presets separated by "|"".

If a preset is configured correctly, CodeField message_type containing the preset's name is added to the result as well as the corresponding list of CodeFields.

The full list of supported presets: AAMVA, GS1, URL, EMAIL, VCARD, ICALENDAR, PHONE, SMS, ISBN, WIFI, GEO, PAYMENT.

Every preset contains its own set of fields:

Preset	Fields
AAMVA	In accordance with the AAMVA, specification, e.g. "AAMVA_VERSION", "ANSI", "DAC", etc.
GS1	"BATCH/LOT", "EXPIRY", "GTIN", "SERIAL", "SSCC/SSCI", etc.
URL	"URL"
EMAIL	"Body", "Recipients", "Subject", "URL mailto", "Carbon copy", etc.
VCARD	"vCard version", "ADR", "AGENT", "BDAY", "CATEGORIES", "CLASS", "LABEL", "EMAIL", etc.
ICALENDAR	"EVENT0", "EVENT1", etc.
PHONE	"Phone"
SMS	"SMS_number", "Body"
ISBN	"ISBN", "ISBN type", "Prefix", "Registration group"
WIFI	"Authentication type", "Password", "SSID", etc.
GEO	"Latitude", "Longitude", "Query"
PAYMENT	"BIC", "BankName", "CorrespAcc", "Name", "PersonalAcc", etc.

The barcode related options are presented in the table.

Option name	Value type	Default	Description
barcode.enabled	"true" or "false"	"false"	Enables barcode recognition
barcode.ALL.enabled	"true" or "false"	"false"	Enables all barcode symbologies
barcode.COMMON.enabled	"true" or "false"	"false"	Enables common barcode symbologies
barcode.maxAllowedCodesPerFrame	integer	“1”	Specifies the max number of recognized codes
barcode.roiDetectionMode	"focused", "anywhere" or "dummy"	“focused”	Specifies the ROI detection mode
barcode.feedMode	"sequence" or "single"	“single”	Specifies the feed mode of barcode session
barcode.effortLevel	"low", "normal" or "high"	“normal”	Specifies the recognition effort level
barcode.<symbology>.enabled	"true" or "false"	"false"	Enables/disables specified symbology
barcode.<symbology>.minMsgLen	integer	“1”	The minimum length of barcode message
barcode.<symbology>.maxMsgLen	integer	“999”	The maximum length of barcode message
barcode.<symbology>.checkSumPresence	integer	“0”	Specifies the presence of checksum (for 1d codes)
barcode.<symbology>.extendedMode	"true" or "false"	"false"	Specifies the extended mode (for 1d codes)
barcode.<symbology>.barcodeColour	"black", "white" or "unknown"	"unknown"	Specifies the expected module color
barcode.preset	preset name	—	Specifies the preset for the decoded barcode content interpretation
barcode.preset.PAYMENT.strictSpecCompliance	"true" or "false"	"false"	Specifies if the PAYMENT preset strictly follows the corresponding specification
barcode.smartPaymentBarDecoding	"true" or "false"	"false"	Enables smart encoding detection for payment barcodes

To enable smart recognition of payment barcode encodings that do not meet the specification, set the parameters:

C++

settings->SetOption("barcode.smartPaymentBarDecoding", "true");

Java

settings.SetOption("barcode.smartPaymentBarDecoding", "true");

The CodeField smart_payment_bar_decoding_result objects containing the encoding name will be created. You can use this object in the PAYMENT preset instead of the specification. The supported encodings: UTF8, CP1251, KOI8_R, ISO8859_5, CP932.

Setting Bank Card Recognition

The bank_card engine recognizes bank cards on the given set of frames. By default it is disabled. To enable it, set the corresponding session option:

C++

settings->SetOption("bank_card.enabled", "true");

Java

settings.SetOption("bank_card.enabled", "true");

Three types of bank cards are supported:

• embossed — bank cards with an embossed data pattern;
• indent — bank cards with an intent-printed data pattern;
• freeform — bank cards with a flat-designed data pattern, where data of interest may be located anywhere in the card.

All types are enabled by default. You can explicitly enable bank card recognition setting the options:

C++

settings->SetOption("bank_card.embossed.enabled", "true");

Java

settings.SetOption("bank_card.embossed.enabled", "true");

For embossed and indent bank cards the recognition result may contain the following list of fields:

Field	Description
number	the bank card number (mandatory)
name	the cardholder's name
expiry_date	the expiry date in format MM/YY
optional_data_0	additional data line of any format
optional_data_1	additional data line of any format
optional_data_2	additional data line of any format

For freeform bank cards the recognition result may contain the following list of field:

Field	Description
number	the bank card number (mandatory)
name	the cardholder's name
expiry_date	the expiry date in format MM/YY
iban	IBAN (ISO 13616)
secret code	the VC/CVV code

The capture mode determines where to find the bank card. For this engine, there are two supported capture modes:

• mobile is suitable for handheld camera recognition in video stream;
• anywhere is suitable for scanned images, webcam images, and arbitrary placed bank cards. It is recommended to use this mode for recognizing cards and images from the device gallery.

By default the mobile mode is enabled.

The bank card recognition options:

Option	Value type	Default	Description
bank_card.enabled	"true" or "false"	"false"	Enables/disables bank card recognition
bank_card.captureMode	"mobile" or "anywhere"	"mobile"	Specifies bank card detection mode
bank_card.enableStoppers	"true" or "false"	"true"	Enables the smart text fields stoppers
bank_card.extractBankCardImages	"true" or "false"	"false"	Extracts the rectified bank card image and stores it in the relevant CodeObject

Setting MRZ Recognition

The MRZ engine recognizes machine-readable zones on a specific set of frames according to the specification [ICAO] (https://www.icao.int/publications/pages/publication.aspx?docnum=9303). This feature is disabled by default. To enable it, set the appropriate session options.

C++

settings->SetOption("mrz.enabled", "true");

Java

settings.SetOption("mrz.enabled", "true");

The recognition result is contained in the full_mrz object field. This object also contains a set of separated fields, the names of which depend on the MRZ type.

The engine supports the following MRZ types:

MRZ type	Document	Description
ICAO 9303 MRZ MRP (TD3) subtype	Machine readable passport	2 lines of 44 chatacters each
ICAO 9303 MRZ MRVA subtype	Machine readable visa	Type A, 2 lines of 44 chatacters each
ICAO 9303 MRZ MRVB subtype	Machine readable visa	Type B, 2 lines of 36 chatacters each
ICAO 9303 MRZ TD1 subtype	Machine readable travel document	Type 1, 3 lines of 30 chatacters each
ICAO 9303 MRZ TD2 subtype	Machine readable travel document	Type 2, 2 lines of 36 chatacters each
MRZ-like zone	Bulgarian vehicle registration certificates	3 lines of 30 chatacters each
MRZ-like zone	Swiss driver's license	3 lines: 9 chatacters in the first, 30 chatacters in the second and 30 chatacters in the third line
MRZ-like zone	Ecuador identity card	3 lines of 30 chatacters each
MRZ-like zone	France identity card	2 lines of 36 chatacters each
MRZ-like zone	Kenya identity card	3 lines of 30 chatacters each
MRZ-like zone	Russian national passport	2 lines of 44 chatacters each
MRZ-like zone	Russian visa	2 lines of 44 chatacters each

Depending on the MRZ type, the recognition result contains a subset of fields with the following names:

Field name	Description
mrz_doc_type_code	Document type code
mrz_number	Document number
mrz_issuer	Issuer
mrz_proprietor	Proprietor
mrz_vehicle_number	Vehicle type
mrz_line1	Line 1
mrz_line2	Line 2
mrz_line3	Line 3
full_mrz	Full MRZ
mrz_vin	VIN (The vehicle identification number)
mrz_id_number	ID
mrz_cd_number	Check digits of the number
mrz_cd_bgrvrd_1	The 1-st check number of the Bulgarian vehicle registration certificate
mrz_cd_bgrvrd_2	The 2-nd check number of the Bulgarian vehicle registration certificate
mrz_birth_date	Birth date
mrz_name	Name
mrz_nationality	Nationality
mrz_opt_data_1	Personal number or other optional data of line 1
mrz_opt_data_2	Personal number or other optional data of line 2
mrz_last_name	Last name
mrz_gender	Gender
mrz_expiry_date	Expiry date
mrz_issue_date	Issue date
photo	Photo
mrz_cd_birth_date	Check digits of the birth date
mrz_cd_composite	Composite control number
mrz_cd_expiry_date	Check digits of the expiry date
mrz_cd_opt_data_2	Check digits of the optional data of line 2
mrz_authority_code	Authority code
mrz_id_visa	Visa ID
mrz_invitation_number	Invitation number
mrz_cd_name	Check digits of the name
mrz_cd_invitation_number	Check digits of the nvitation number
mrz_cd_id_visa	Check digits of the visa ID
mrz_first_name	First name
mrz_cd_issue_date	Check digits of the issue date

Setting Codified Text Line Recognition

The code_text_line engine recognizes codified text lines. To enable it, set the corresponding session option:

C++

settings->SetOption("code_text_line.enabled", "true");

Java

settings.SetOption("code_text_line.enabled", "true");

There are two types of supported codified text lines: phone_number and card_number. By default the both types are disabled.

Attention!

The phone_number and card_number types are mutually exclusive.

The type of a codified text line must be explicitly specified by using the corresponding session option:

C++

settings->SetOption("code_text_line.card_number.enabled", "true");

Java

settings.SetOption("code_text_line.card_number.enabled", "true");

The code_text_line engine can recognize both printed and handwritten text lines.

Attention!

The text line area should occupy at least one third of the specified region area.
The following phone number formats are supported:

• 11 digits — phone numbers starting with 7 or 8 and with codes 3XX, 4XX, 7XX, 8XX, 9XX;
• 10 digits — phone numbers starting with 9 (abbreviation of mobile numbers)

Setting Payment Details Recognition

The payment_details engine recognizes payment details presented in the text form required to make a payment in the financial system of the Russian Federation. By default it is disabled. To enable it, set the corresponding session option:

C++

settings->SetOption("payment_details.enabled", "true");

Java

settings.SetOption("payment_details.enabled", "true");

To enable recognition of a specific type of payment details, set the corresponding session option:

C++

settings->SetOption("payment_details.<type>.enabled", "true");

Java

settings.SetOption("payment_details.<type>.enabled", "true");

The full list of supported types is the followin: inn, kpp, rcbic, rus_bank_account, personal_account.

Attention!

Attention! By default all supported types of payment details are enabled.

The Universal Pay technology used in Code Engine allows you to recognize objects in a payment document without specifying the type.

Supported objects:

• Payment barcode according to the GOST R 56042-2014 standard: QR Code, Aztec сode, Data Matrix;
• Bank cards;
• Phone number;
• Bankcard number.

The client provides a sequence of images as input, and the session recognizes and puts into the result only those objects for which payment can be made (i.e., other two-dimensional barcodes not in accordance with GOST will be ignored).

One payment object is recognized within one session. After detecting a payment object in a sequence of frames, the session is terminated. One frame is enough for barcodes; for other types of objects, several frames are required. Examples of the Universal Pay settings:

C++

settings->SetOption("global.workflow", "universalPay");  
settings->SetOption("barcode.enabled", "true");  
settings->SetOption("barcode.QR_CODE.enabled", "true");  
settings->SetOption("barcode.AZTEC.enabled", "true");  
settings->SetOption("barcode.DATA_MATRIX.enabled", "true");  
settings->SetOption("barcode.preset", "PAYMENT");  
settings->SetOption("barcode.feedMode", "sequence");  
settings->SetOption("bank_card.enabled", "true");  
settings->SetOption("code_text_line.enabled", "true");  
settings->SetOption("code_text_line.phone_number.enabled", "true");  
settings->SetOption("code_text_line.card_number.enabled", "true");

Java

settings.SetOption("global.workflow", "universalPay");  
settings.SetOption("barcode.enabled", "true");  
settings.SetOption("barcode.QR_CODE.enabled", "true");  
settings.SetOption("barcode.AZTEC.enabled", "true");  
settings.SetOption("barcode.DATA_MATRIX.enabled", "true");  
settings.SetOption("barcode.preset", "PAYMENT");  
settings.SetOption("barcode.feedMode", "sequence");  
settings.SetOption("bank_card.enabled", "true");  
settings.SetOption("code_text_line.enabled", "true");  
settings.SetOption("code_text_line.phone_number.enabled", "true");  
settings.SetOption("code_text_line.card_number.enabled", "true");

Session Options

You can specify some configuration bundle options in runtime by using the CodeEngineSessionSettings class methods.
To obtain all currently set option names and their values, use the following procedur:

C++

for (auto it = settings->Begin(); it != settings->End(); ++it) {  
    // it.GetKey()  returns the option name  
    // it.GetValue() returns the option value  
}

Java

for (StringsMapIterator it = settings.Begin();  
     !it.Equals(settings.OptionsEnd());  
     it.Advance()) {  
    // it.GetKey() returns the option name  
    // it.GetValue() returns the option value  
}

To change option values, use the SetOption(...) method:

C++

settings->SetOption("barcode.enabled", "true");  
settings->SetOption("barcode.COMMON.enabled", "true");

Java

settings.SetOption("barcode.enabled", "true");  
settings.SetOption("barcode.COMMON.enabled", "true");

Option values are always represented as strings, so if you want to pass an integer or boolean convert it to string first.

Global options:

Option	Value type	Default	Description
global.workflow	String I	"common"	Defined recognition mode
global.enableMultiThreading	"true" или "false"	"true"	Enables parallel execution of internal algorithms
global.rgbPixelFormat	String of characters R, G, B, и A	“RGB” for 3-channel images, “BGRA” for 4-channel images
Sequence of color channels for session.ProcessSnapshot() method image interpretation
global.sessionTimeout	Double	“0.0” for server bundles, “5.0” for mobile bundles	Session timeout in seconds

Spawning a Session

From System Description:

A personal signature is provided to the customer with the product. It is contained in the README.html file in the /doc directory.

Each time an instance of the recognition session is created, the signature must be passed as one of the arguments. This confirms the caller's right to use the library and unlocks it.

Signature is verified offline. The library does not access any external resources.

Spawn a session (the CodeEngineSession object):

C++

const char* signature = "... YOUR SIGNATURE HERE ..."; //Your personal signature you use to start Smart Code Engine session
std::unique_ptr<se::code::CodeEngineSession> session(engine->SpawnSession(*settings, signature, &my_workflow_feedback, &my_visualization_feedback));

Java

import com.smartengines.code.*;  
String signature = "... YOUR SIGNATURE HERE ..."; ///Your personal signature you use to start Smart Code Engine session  
CodeEngineSession session = engine.SpawnSession(settings, signature, my_workflow_feedback, my_visualization_feedback);

Attention!

CodeEngine::SpawnSession() is a factory method and returns an allocated pointer. The caller responsible for deleting it.

Creating an Image Object

From System Description:

Pass an image of the special class se.common.image to the system for recognition. You can create it using the following image formats:

• jpeg, png;
• tiff (✔️TIFF_LZW, ✔️TIFF_PACKBITS,✔️TIFF_CCITT);
• base64 (above mentioned formats);
• file buffer with a preliminary indication of the color scheme, width\height\number of channels.

The maximum allowed image size by default is 15000x15000px. You can change the maximum image size.

Handling a HEIC file

A HEIC file in the mobile SDK are handled similarly to other image formats. The HEIC is read using system tools.

In the server SDK, open the HEIC format using external tools and convert it either to one of the formats we support, or transfer the raw pixels directly as an RGB buffer (this is recommended).

Create an Image object for further processing:

C++

std::unique_ptr<se::common::Image> image(se::common::Image::FromFile(image_path)); // Loading from a file

Java

import com.smartengines.code.*;  
Image image = Image.FromFile(image_path); //Loading from a file

Attention!

Image::FromFile() is a factory method and returns an allocated pointer. The caller is responsible for deleting it.

Recognitiion Process

Call the Process(...) method for processing the image:

C++

const se::code::CodeEngineResult& result = session->Process(*image);

Java

import com.smartengines.code.*;  
CodeEngineResult result = session.Process(image);

Attention!

CodeEngineResult::Process() is not a factory method. The returned CodeEngineResult object is not independent, its lifetime does not exceed the CodeEngineSession object lifetime.

Processing the Recognition Result

From System Description:

Recognition result is an interface object that contains all the available information about the recognition result. Each parameter is output using a separate method, which allows you to use only the required data in integration. The set of the object fields depends on the type of the session in which recognition was performed, and this depends on the functionality of the product used.

The CodeEngineResult object fields contain information about the recognition results:

C++

for (auto it_obj = result.ObjectsBegin(); it_obj != result.ObjectsEnd(); ++it_obj) {  
    const se::code::CodeObject& code_object = it_obj.GetValue();

    std::string object_type = code_object.GetTypeStr(); // The object type in string format   
    bool is_accepted = code_object.IsAccepted(); // Getting the is_accepted value

    for (auto it_field = code_object.FieldsBegin();  
         it_field != code_object.FieldsEnd(); ++it_field) {  
        const se::code::CodeField &code_field = it_field.GetValue();

        std::string code_field_name = code_field.Name(); // The field name  
        if (code_field.HasOcrStringRepresentation())  
            std::string ocr_string = code_field.GetOcrString()  
                .GetFirstString()  
                .GetCStr(); // Getting a field recognition result as a UTF-8 encoded string

    }  
}

Java

import com.smartengines.code.*;  
for (CodeObjectsMapIterator it_obj = result.ObjectsBegin();  
     !it_obj.Equals(result.ObjectsEnd()); it_obj.Advance()) {  
    CodeObject code_object = it_obj.GetValue();

    String object_type = code_object.GetTypeStr(); // The object type in string format   
    boolean is_accepted = code_object.IsAccepted(); // Getting the is_accepted value
     }

     
    for (CodeFieldsMapIterator it_field = code_object.FieldsBegin();  
         !it_field.Equals(code_object.FieldsEnd()); it_field.Advance()) {  
        CodeField code_field = it_field.GetValue();

        String code_field_name = code_field.Name(); // The field name  
        if (code_field.HasOcrStringRepresentation())  
            String ocr_string = code_field.GetOcrString().GetFirstString().GetCStr(); // ПGetting a field recognition result as a UTF-8 encoded string

}

Callbacks

From System Description:

Recognition in video stream is a complex and often not quick process that requires user interaction. Providing information about the progress of recognition on the screen during operation, we help the user to understand the system operation stages better. For this purpose machine vision technologies are often complemented by augmented reality elements, what enhances the user experience and makes interaction more intuitive.

The recognition result object contains information about the coordinates of the quadrilateral of the document template (document borders) and the coordinates of the quadrilaterals of the document field templates. For example, using these coordinates, you can draw the found document borders on the screen using your camera preview.

Smart Code Engine SDK supports additional callbacks during the analysis of objects before their processing, the Process(...)method, is completed. This allows the user to get more information about the basic recognition process, and also helps to create an interactive graphical interface. To implement callbacks, use the CodeEngineWorkflowFeedback and CodeEngineVisualizationFeedbackclasses and the following methods:

C++

class MyWorkflowFeedback : public se::code::CodeEngineWorkflowFeedback {/* callbacks */ };  
class MyVisualizationFeedback : public se::code::CodeEngineVisualizationFeedback { /* callbacks */ };

// ...

MyWorkflowFeedback my_workflow_feedback;  
MyVisualizationFeedback my_visualization_feedback;

Java

import com.smartengines.code.*;  
class MyWorkflowFeedback extends CodeEngineWorkflowFeedback { /* callbacks */ }  
class MyVisualizationFeedback extends CodeEngineVisualizationFeedback { /* callbacks */ }

// ...

MyWorkflowFeedback my_workflow_feedback = new MyWorkflowFeedback();  
MyVisualizationFeedback my_visualization_feedback = new MyVisualizationFeedback();

CodeEngineSession session = engine.SpawnSession(settings, signature, my_workflow_feedback, my_visualization_feedback);

Memory Deallocation

Despite the fact that garbage collection is implemented and working, it is recommended to call the obj.delete() method for our API objects manually, since they are wrappers of memory allocated on the heap. The size of their heap is unknown to the garbage collector, which can lead to a delay in deleting objects and, consequently, high overall memory consumption.

CodeEngine engine = CodeEngine.Create(config_path); // or any other object
// ...
engine.delete(); // Forces and immediately guarantees wrapped C++ object deallocation

Some Smart Code Engine SDK classes contain factory methods that return pointers to objects allocated on the heap.Such objects must be deleted.

TIP

• In C++ for easy memory management and prevention of memory leaks, use smart pointers std::unique_ptr<T> or std::shared_ptr<T>.

• In Java API remove garbage using the .delete() method.

Library Interface

Common Classes

Common classes, for example, Point, OcrString, Image etc., are located in the se::common namespace in the secommon directory.
These are the following C++ headers:

Header	Description
<secommon/se_export_defs.h>	Contains export-related definitions of Smart Engines libraries
<secommon/se_exceptions_defs.h>	Contains the definition of exceptions used in Smart Engines libraries
<secommon/se_geometry.h>	Contains geometric classes and procedures (Point, Rectangle, etc.)
<secommon/se_image.h>	Contains the definition of the Image class
<secommon/se_string.h>	Contains the string-related classes (MutableString, OcrString, и т.д.)
<secommon/se_string_iterator.h>	Contains the definition of string iterators строк
<secommon/se_serialization.h>	Contains auxiliary classes related to object serialization (not used in Smart Code Engine)
<secommon/se_common.h>	an auxiliary header which includes all of the above.

The same Java API classes are contained in the com.smartengines.common module:

import com.smartengines.common.*; // Import se::common classes

Main Classes

The main Smart Code Engine classes are located within these::code namespace in codeengine the directory:

Header	Description
<codeengine/code_engine.h>	Contains the CodeEngine class definition
<codeengine/code_engine_session.h>	Contains the CodeEngineSession class definition
<codeengine/code_engine_session_settings.h>	Contains the CodeEngineSessionSettings class definition
<codeengine/code_engine_result.h>	Contains the CodeEngineResult class definition
<codeengine/code_engine_feedback.h>	Contains the CodeEngineWorkflowFeedback и CodeEngineVisualizationFeedback classes definition and related containers
<codeengine/code_object_field.h>	Contains the CodeField class definition
<codeengine/code_object.h>	Contains the CodeObject class definition

The same Java API classes are contained in the com.smartengines.code module:

import com.smartengines.codeengine.*; // Import of the se::code classes

Exceptions

The C++ API may throw se::common::BaseException exceptions in case of incorrect data entry, incorrect calls, and other errors. The following exception subclasses are supported:

Exception	Description
FileSystemException	Thrown if attempt to read data from a non-existent file is mane
InternalException	Thrown in case of an unknown error of an internal system component
InvalidArgumentException	Thrown if a method with invalid input parameters is called
InvalidKeyException	Thrown in case of access the container using an invalid or a non-existent key, or in case of access to a list using an invalid or out-of-range index
InvalidStateException	Thrown if a system error occurs due to an invalid state of the system objects
MemoryException	Thrown if an allocation is attempted with insufficient RAM
NotSupportedException	Thrown when trying to access a method which is not supported in the current library version or is not supported at all
Uninitialized Object Exception	Thrown in case of an attempt to access a non-existent or non-initialized object

If exceptions occur, user-friendly messages are displayed using the e.what() method.

TIP

se::common::BaseException  is not a subclass of std::exception. interface does not have any dependency on the STL.

The Java API exceptions are wrapped in common class java.lang.Exception. Тhe exception type is included in the corresponding message text.