Smart Document Engine Documentation

Smart Document Engine is a multi-platform, stand-alone SDK for recognition of structured documents with rigid and flexible forms, such as certificates, invoices, acts, payment documents, etc.

Workflow

The DocEngine 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 DocEngine instance:

C++

std::unique_ptr<se::doc::DocEngine> engine(se::doc::DocEngine::Create(  
    configuration_bundle_path));

Java

import com.smartengines.doc.*  
DocEngine engine = DocEngine.Create(configuration_bundle_path);

Parameters:

• configuration_bundle_path — the path to the onfiguration bundle file containing DocEngine settings (a .se file);
• boolean, enabling/disabling lazy configuration (true by default). Optional.

Each delivery includes one or more bundles — archives containing the settings required for creating objects and configuring Smart Document Engine.

Attention!

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

Creating a Recognition Session

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 an DocSessionSettings object using the configured DocEngine instance:

C++

std::unique_ptr<se::doc::DocSessionSettings> settings(engine->CreateSessionSettings());

Java

import com.smartengines.doc.*  
DocSessionSettings settings = engine.CreateSessionSettings();

Attention!

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

Enabling Document Types

The document type is a string that describes the physical document to be recognized.

Each document type transmitted to the system is mapped to all supported types. If a certain type is supported, it is added to the list of recognized documents.

Configure the types of recognized documents as shown in the example:

C++

settings->AddEnabledDocumentTypes("usa.forms.fed.ss4.type1"); //  Enables the form of the application for an employer identification number of the USA

Java

settings.AddEnabledDocumentTypes("usa.forms.fed.ss4.type1"); // Enables the form of the application for an employer identification number of the USA

Supported Document Types

Get the document types Smart Document Engine SDK can recognize:

C++

// Iterating through the found internal engines  
for (int i_engine = 0;  
     i_engine < settings->GetInternalEnginesCount();  
     ++i_engine) {  
    // Iterating through supported document types for this internal engine  
    for (int i_doc = 0;  
         i_doc < settings->GetSupportedDocumentTypesCount(i_engine);  
         ++i_doc) {  
        //  Getting supported the document type name   
        std::string doctype = settings->GetSupportedDocumentType(i_engine, i_doc);  
    }  
}

```Java  
// Iterating through the found internal engines  
for (int i_engine = 0;  
     i_engine < settings.GetInternalEnginesCount();  
     i_engine++) {  
    // Iterating through supported document types for this internal engine     
    for (int i_doc = 0;  
         i_doc < settings.GetSupportedDocumentTypesCount(i_engine);  
         i_doc++) {  
        // Getting supported the document type name   
        String doctype = settings.GetSupportedDocumentType(i_engine, i_doc);  
    }  
}

Attention!

In a single session you can only enable document types that belong to the same internal engine.

Wildcard Expressions

Since all documents in settings are enabled by default you can enable only those you need by using the AddEnabledDocumentTypes(...) method of the DocSessionSettings object:

C++

settings->AddEnabledDocumentTypes("usa.forms.fed.ss4.type1"); // Enables the type 1 form of the application for an employer identification number of the USA

Java

settings.AddEnabledDocumentTypes("usa.forms.fed.ss4.type1"); // Enables the type 1 form of the application for an employer identification number of the USA

To exclude document types from the recognition process, use the RemoveEnabledDocumentTypes(...) method.

When specifying document types, masks can be used. The masks are set using asterisks. Each document type transmitted to the system is mapped to all supported types. If a particular type is supported, it is added to the list of recognized types.

C++

settings->AddEnabledDocumentTypes("deu.*"); // Enables all supported documents of Germany

Java

settings.AddEnabledDocumentTypes("deu.*"); // Enables all supported documents of Germany

Attention!

You can only enable document types that belong to the same internal engine for a single session. If you do otherwise then an exception will be thrown during session spawning.

TIP

To reduce the processing time, specify the minimum number of recognized document types.

Setting Session Options

You can set a specific set of options for each recognition session using the methods of the DocSessionSettings class.

To get the parameter names and their values:

C++

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

Java

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

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

C++

settings->SetOption("common.extractTemplateImages", "true"); // Getting template images
settings->SetOption("common.sessionTimeout", "3.0");

Java

settings.SetOption("common.extractTemplateImages", "true"); //Getting template images
settings.SetOption("common.sessionTimeout", "3.0");

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 DocSession object):

C++

const char* signature = "... YOUR SIGNATURE HERE ..." // Your personal signature you use to start Smart Document Engine session
  
std::unique_ptr<se::doc::DocSession> session(engine->SpawnSession(*settings, signature));

Java

import com.smartengines.doc.*  
String signature = "... YOUR SIGNATURE HERE ..." // Your personal signature you use to start Smart Document Engine session
;  
DocSession session = engine.SpawnSession(settings, signature);

Creating a Processing Settings Object

Creating a processing settings object:

C++

std::unique_ptr<se::doc::DocProcessingSettings> proc_settings(session->CreateProcessingSettings());

Java

import com.smartengines.doc.*  
DocProcessingSettings proc_settings = session.CreateProcessingSettings();

Creating an Image Object

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.doc.*  
Image image = Image.FromFile(image_path); // Loading from a file

Attention!

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

Registering the Image in the Session

Registering the Image in the session as the source image:

C++

int image_id = session->RegisterImage(*image);  
proc_settings->SetCurrentSourceID(image_id);

Java

int image_id = session.RegisterImage(image);  
proc_settings.Process(proc_settings);

Recognition Process

Call the Process(...) method to process the document image:

C++

session->Process(*proc_settings);

Java

session.Process(proc_settings);

Multipage document recognition

Smart Document Engine supports multipage document recognition out-of-box. Run recognition of all the pages of the document in one session, sequentially calling the ProcessImage() method on them.

Each image should contain one page of the document and pages should be sorted in reading order (page 1, page 2, etc.) Smart Document Engine will create one instance of document for a multipage document to aggregate the recognized fields from all the pages.

Also note that if a page of arbitrary-filled document (or a document not supported by running session) will come, it will be classified as a page of the current multipage document and all the text it contains will be recognized.

Processing the Recognition Result

Getting the Current Result from the Session

Get the current result from the session:

C++

const se::doc::DocResult& result = session->GetCurrentResult();

Java

import com.smartengines.doc.*  
DocResult result = session.GetCurrentResult();

Getting the Recognition Result

Use the DocResult to get the recognition results:

C++

// Iterating the found documents  
for (auto doc_it = result.DocumentsBegin();  
     doc_it != result.DocumentsEnd();  
     ++doc_it) {  
    const se::doc::Document& doc = doc_it.GetDocument();  
     
    // Iterating the text fields
    for (auto it = doc.TextFieldsBegin();  
         it != doc.TextFieldsEnd();  
         ++it) {

        // Getting the text field value (UTF-8 string representation)  
        std::string field_value = it.GetField().GetOcrString().GetFirstString().GetCStr();  
    }  
}

Java

import com.smartengines.doc.*  
// Iterating the found documents  
for (DocumentsIterator doc_it = result.DocumentsBegin();  
     !doc_it.Equals(result.DocumentsEnd());  
     doc_it.Advance()) {  
    Document doc = doc_it.GetDocument();

    // Iterating the text fields  
    for (DocTextFieldsIterator it = doc.TextFieldsBegin();  
         !it.Equals(doc.TextFieldsEnd());  
         it.Advance()) {
        // Getting the text field value (UTF-8 string representation)  
        String field_value = it.GetField().GetOcrString().GetFirstString().GetCStr();  
    }  
}

Memory Deallocation

Some Smart Document Engine SDK classes have factory methods which return pointers to heap-allocated objects. Caller is responsible for deleting such objects.

TIP

• In C++:, for simple memory management and avoiding memory leaks, use smart pointers, such asstd::unique_ptr<T> or std::shared_ptr<T>
• In Java API use the .delete() method to remove garbage.

Library Interface

Common Classes

Common classes, such as 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 Engines
<secommon/se_exceptions_defs.h>	Contains the definition of exceptions used in Smart Engines librarieEngines
<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, etc.д.)
<secommon/se_string_iterator.h>	Contains the definition of string-targeted iterator
<secommon/se_serialization.h>	Contains auxiliary classes related to object serialization (not used in Smart Document Engine)
<secommon/se_common.h>	This is an auxiliary header which simply includes all of the above

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

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

Main Classes

The main Smart Document Engine classes are located in the se::doc namespace in the docengine directory:

Header	Description
<docengine/doc_document_info.h>	Provides information about the document type (textual document description)
<docengine/doc_engine.h>	Contains the DocEngine class definition
<docengine/doc_session_settings.h>	Contains the DocSessionSettings class definition
<docengine/doc_session.h>	Contains the DocSession class definition
<docengine/doc_processing_settings.h>	Contains the DocProcessingSettings class definition
<docengine/doc_result.h>	Contains the DocResult, DocTemplateDetectionResult и DocTemplateSegmentationResult class definition
<docengine/doc_document.h>	Contains the Document class definition
<docengine/doc_documents_iterator.h>	Contains the documents related iterators
<docengine/doc_fields.h>	Contains the Document class definition
<docengine/doc_fields_iterator.h>	Contains the fields iterators
<docengine/doc_feedback.h>	Contains the DocFeedback interface definition ant the related containers
<docengine/doc_document_field_info.h>	Contains the DocDocumentFieldInfo class definition
<docengine/doc_document_fields_info_iterator.h>	Contains DocDocumentFieldInfo-related iterators
<docengine/doc_basic_object.h>	Contains the DocBasicObject class definition
<docengine/doc_basic_objects_iterator.h>	Contains the itirators of the DocBasicObject class (basic document objects)
<docengine/doc_objects.h>	Contains definitions of graphical object classes
<docengine/doc_objects_collection.h>	Contains the DocObjectsCollection class definition
<docengine/doc_objects_collection_iterator.h>	Contains the DocObjectsCollection (document objects collection) related iterators
<docengine/doc_forward_declarations.h>	Service header containing forward declarations of all classes
<docengine/doc_physical_document.h>	Contains DocPhysicalDocument, DocPhysicalPage, and DocPageInfo class definitions
<docengine/doc_physical_document_iterators.h>	Contains DocPhysicalDocument-related iterators
<docengine/doc_scene_info.h>	Contains DocSceneInfo class definition

Deprecated headers (to be removed in future versions)

Header	Description
<docengine/doc_video_session.h>	Contains the DocVideoSession class definition
<docengine/doc_external_processor.h>	Contains the external document processing interface
<docengine/doc_graphical_structure.h>	Contains DocGraphicalStructure class definition
<docengine/doc_tags_collection.h>	Contains the DocTagsCollection class definition
<docengine/doc_view.h>	Contains the DocView class definition
<docengine/doc_views_iterator.h>	Contains the DocView (basic document objects) related iterators
<docengine/doc_views_collection.h>	Contains the DocViewsCollection class definition

The same classes in Java API are contained in com.smartengines.doc:

import com.smartengines.doc.*; // Import se::doc

Exceptions

The C++ API may throw se::common::BaseException subclasses exceptions when invalid input data is input, incorrect calls are made or if something else goes wrong.

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 are thrown, user-friendly messages are displayed by the e.what() method.

Attention!

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

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