Smart Text Engine SDK Overview

This is a collection of DEMO builds of Smart Text Engine SDK developed by Smart Engines. The SDK examples can be used to demonstrate the integration possibilities and understand the basic object recognition workflows.

• ⚠️ Personalized signature ⚠️
• Troubleshooting and help
• General Usage Workflow
• Smart Text Engine SDK Overview
  • Header files, namespaces, and modules
  • Code documentation
  • Exceptions
  • Factory methods and memory ownership
• Configuration bundles
• Specifying languages for TextSession
  • Supported languages
• Session options
• Java API Specifics
  • Object deallocation

⚠️ Personalized signature ⚠️

Users are required to use a personalized signature for starting a session. The signature is validated offline and locks to the copy of the native library, thus ensures that only an authorized client may use it. The signature is a string with 256 characters.

You will need to manually copy the signature string and pass it as an argument for the SpawnSession() method (see item 4 below). Do NOT keep the signature in any asset files, only inside code. If possible, clients are encouraged to keep the signature in a controlled server and load it into the application via a secure channel, to ensure that signature and the library are separated.

Troubleshooting and help

To resolve issue that you might be facing we recommend to do the following:

• Carefully read in-code documentation in API and samples and documentation in .pdf and .html, including this document
• Check out the code details / compilation flags etc. in the sample code and projects
• Read exception messages if exception is thrown - it might contain usable information

But remember:

• You are always welcome to ask for help at [email protected] (or your sales manager's email) no matter what

General Usage Workflow

1. Create TextEngine instance:

   // C++
   std::unique_ptr<se::text::TextEngine> engine(se::text::TextEngine::Create(
       configuration_bundle_path));

   // Java
   TextEngine engine = TextEngine.Create(configuration_bundle_path);

   Configuration process might take a while but it only needs to be performed once during the program lifetime. Configured TextEngine is used to spawn sessions which have actual recognition methods.

   The second parameter to the Create() method is a boolean flag for enabling lazy configuration (true by default). If lazy configuration is enabled, some of the internal structured will be allocated and initialized only when first needed. If you disable the lazy configuration, all the internal structures and components will be initialized in the Create() method.

   See more about configuration bundles in Configuration Bundles.

2. Create TextSessionSettings from configured TextEngine:

   // C++
   std::unique_ptr<se::text::TextSessionSettings> settings(
         engine->CreateSessionSettings());

   // Java
   TextSessionSettings settings = engine.CreateSessionSettings();

   Note, that TextEngine::CreateSessionSettings() is a factory method and returns an allocated pointer. You are responsible for deleting it.

3. Enable desired languages:

   // C++
   settings->AddEnabledLanguages("rus"); // Russian language

   // Java
   settings.AddEnabledLanguages("rus"); // Russian language

   See more about languages in Specifying languages for TextSession.

4. Spawn TextSession:

   // C++
   const char* signature = "... YOUR SIGNATURE HERE ...";
   std::unique_ptr<se::text::TextSession> session(
       engine->SpawnSession(*settings, signature));

   // Java
   String signature = "... YOUR SIGNATURE HERE ...";
   TextSession session = engine.SpawnSession(settings, signature); 

5. Create an Image object which will be used for processing:

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

   // Java
   Image image = Image.FromFile(image_path); // Loading from file

6. Call ProcessImage(...) method for processing the image:

   // C++
   session->ProcessImage(*image);

   // Java
   session.ProcessImage(image);

7. Obtain the current result from the session

   // C++
   const se::text::TextResult& result = session->GetCurrentResult();

   // Java
   TextResult result = session.GetCurrentResult();

8. Use GetCurrentScene() method to get information about current TextScene recognition results

   // C++
   const se::text::TextScene& scene = result.GetCurrentScene();

   // Java
   TextScene scene = result.GetCurrentScene();

9. Obtain TextIterator from TextScene to walk across the collection of recognized TextChunk instances

   //C++
   std::unique_ptr<se::text::TextIterator> chunk_iterator;
   chunk_iterator.reset(scene.CreateIterator("default"));
   for (; !chunk_iterator->Finished(); chunk_iterator->Advance()) {
     //Getting text chunk value (UTF-8 string representation)
     std::string chunk_str = chunk_iterator->GetTextChunk().GetOcrString().GetFirstString().GetCStr();
   }

   //Java
   TextIterator chunk_iterator = scene.CreateIterator("default");
   for (; !chunk_iterator.Finished(); chunk_iterator.Advance()) {
     //Getting text chunk value (UTF-8 string representation)
     String chunk_str = chunk_iterator.GetTextChunk().GetOcrString().GetFirstString().GetCStr();
   }

Smart Text Engine SDK Overview

Header files, namespaces, and modules

Common classes, such as Point, OcrString, Image, etc. are located within se::common namespace and are located within a secommon directory:

// C++
#include <secommon/se_export_defs.h>      // This header contains export-related definitions of Smart Engines libraries
#include <secommon/se_exceptions.h>       // This header contains the definition of exceptions used in Smart Engines libraries
#include <secommon/se_geometry.h>         // This header contains geometric classes and procedures (Point, Rectangle, etc.)
#include <secommon/se_image.h>            // This header contains the definition of the Image class 
#include <secommon/se_string.h>           // This header contains the string-related classes (MutableString, OcrString, etc.)
#include <secommon/se_strings_iterator.h> // This header contains the definition of string-targeted iterators
#include <secommon/se_serialization.h>    // This header contains auxiliary classes related to object serialization

#include <secommon/se_common.h>           // This is an auxiliary header which simply includes all of the above

The same common classes in Java API are located within com.smartengines.common module:

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

Main Smart Text Engine classes are located with se::text namespaces and are located with a textegnine directory:

// C++

#include <textengine/text_chunk.h> // Contains TextChunk class definition
#include <textengine/text_engine.h> // Contains TextEngine class definition
#include <textengine/text_feedback.h> // Contains the TextFeedback interface and associated container
#include <textengine/text_forward_declarations.h> // Service header containing forward declarations
#include <textengine/text_iterator.h> // Contains TextIterator class definition
#include <textengine/text_result.h> // Contains TextResult class definition
#include <textengine/text_scene.h> // Contains TextScene class definition
#include <textengine/text_session.h> // Contains TextSession class definition
#include <textengine/text_session_settings.h> // Contains TextSessionSettings class definition

The same classes in Java API are located within com.smartengines.text module:

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

Code documentation

All classes and functions have useful Doxygen comments. Other out-of-code documentation is available at doc folder of your delivery. For complete compilable and runnable sample usage code and build scripts please see samples folder.

Exceptions

Our C++ API may throw se::common::BaseException subclasses when user passes invalid input, makes bad state calls or if something else goes wrong. Most exceptions contain useful human-readable information. Please read e.what() message if exception is thrown. Note that se::common::BaseException is not a subclass of std::exception, an Smart Document Engine interface in general do not have any dependency on the STL.

The thrown exceptions are wrapped in general java.lang.Exception, so in Java API do catch those.

Factory methods and memory ownership

Several Smart Text Engine SDK classes have factory methods which return pointers to heap-allocated objects. Caller is responsible for deleting such objects (a caller is probably the one who is reading this right now). We recommend using std::unique_ptr<T> for simple memory management and avoiding memory leaks.

In Java API for the objects which are no longer needed it is recommended to use .delete() method to force the deallocation of the native heap memory.

Configuration bundles

Every delivery contains one or several configuration bundles – archives containing everything needed for Smart Text Engine to be created and configured. Usually they are named as bundle_something.se and located inside data-zip folder.

Specifying languages for TextSession

Assuming you already created the engine and session settings like this:

// C++
// create recognition engine with configuration bundle path
std::unique_ptr<se::text::TextEngine> engine(
    se::text::TextEngine::Create(configuration_bundle_path));

// create session settings with se::text::TextEngine factory method
std::unique_ptr<se::text::TextSessionSettings> settings(
    engine->CreateSessionSettings());

// Java
// create recognition engine with configuration bundle path
TextEngine engine = TextEngine.Create(configuration_bundle_path);

// create session settings with TextEngine factory method
TextSessionSettings settings = engine.CreateSessionSettings();

In order to call engine->SpawnSession(...) you are recommended to specify enabled languages for session to be spawned using TextSessionSettings methods. By default, all languages are disabled.

Supported languages

A language is simply string encoding real world language you want to recognize (usually using ISO 639-3 codes). We also have two service languages - digits and punct. Languages that Smart Text Engine SDK delivered to you can potentially recognize can be obtained using the following procedure:

// C++
// Iterating through supported languages
for (auto it = settings->SupportedLanguagesBegin();
     it != settings->SupportedLanguagesEnd();
     ++it) {
  //Getting language code
  std::string lang = it.GetValue();
  //Getting the string of characters
  std::string char_str = settings->GetLanguageAlphabet(lang); 
}

// Java
// Iterating through supported languages
for (StringSetIterator it = settings.SupportedLanguagesBegin();
     !it.Equals(settings.SupportedLanguagesEnd());
     it.Advance()) {
  //Getting language code
  String lang = it.GetValue();
  //Getting the string of characters
  String char_str = settings.GetLanguageAlphabet(lang);
}

To enable several languages you should combine their codes using colon, e.g. eng:digits.

Session options

Some configuration bundle options can be overriden in runtime using TextSessionSettings methods. You can obtain all currently set option names and their values using the following procedure:

// 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
}

You can change option values using the SetOption(...) method:

// C++
settings->SetOption("enableMultiThreading", "true");

// Java
settings.SetOption("enableMultiThreading", "true");

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

Common options

Option name	Value type	Default	Description
enableMultiThreading	"true" or "false"	true	Enables parallel execution of internal algorithms
enableSmallLetters	"true" or "false"	false	Enables case-sensitive recognition result (Russian language only)
mode	String with value standard, page, line, crop, or crop_advanced	standard	Mode of session.ProcessImage() method, page performs search of the paper sheet in the image, line return only one text line. crop and crop_advanced do not perform recognition, they produce a cropped image of page. crop_advanced detectes page orientation, i.e. if the page is upside down and rotate it.

Java API Specifics

Smart Text Engine SDK has Java API which is automatically generated from C++ interface by SWIG tool.

Java interface is the same as C++ except minor differences, please see the provided Java sample.

There are several drawbacks related to Java memory management that you need to consider.

Object deallocation

Even though garbage collection is present and works, it's strongly advised to manually call obj.delete() functions for our API objects because they are wrappers to the heap-allocated memory and their heap size is unknown to the garbage collector.

TextEngine engine = TextEngine.Create(config_path); // or any other object

// ...

engine.delete(); // forces and immediately guarantees wrapped C++ object deallocation

This is important because from garbage collector's point of view these objects occupy several bytes of Java memory while their actual heap-allocated size may be up to several dozens of megabytes. GC doesn't know that and decides to keep them in memory – several bytes won't hurt, right?

You don't want such objects to remain in your memory when they are no longer needed so call obj.delete() manually.