Smart Engines 2021: Международная награда в ИТ-инновациях

Smart ID Engine SDK Overview

About Smart ID Engine

Smart ID Engine is a multi-platform, stand-alone SDK for recognizing and identifying text fields of passports, visas and other identification documents.

Supported operating systems

The following operating systems are supported:

  • MS Windows;
  • Linux-based systems;
  • Mac OS;
  • iOS;
  • Android.

Workflow

General workflow includes the following stages:

  1. creation of an IdEngine instance, see Creating an IdEngine instance;
  2. setting up a recognition session:
  1. optional implementation of callbacks, see Callbacks;
  2. creation of an image object, see Creating an Image;
  3. processing the image, see Processing the image;
  4. getting the recognition result, see Recognition result.

Creating an IdEngine instance

Create IdEngine instance as follows:

// C++
std::unique_ptr<se::id::IdEngine> engine(se::id::IdEngine::Create(
configuration_bundle_path));

// Java
import com.smartengines.id.*;
IdEngine engine = IdEngine.Create(configuration_bundle_path);

Parameters:

  • configuration_bundle_path is a path to provided configuration file (usually a file with extension .se);
  • a boolean flag for enabling lazy configuration (true by default). It is an optional parameter. 
    • If lazy configuration is enabled, some of the internal structures will be allocated and initialized only when first needed. 
    • If you disable the lazy configuration, all the internal structures and components will be initialized  during IdEngine instance creation.

TIP

 Disable lazy configuration for:
• server applications for which the first recognition response time is more important than the total memory consumption;
• measuring the maximum memory consumed by an application

Configuration process may take a while but it only needs to be performed once during the program lifetime. 

Configured IdEngine is used to spawn recognition session – instances of IdSession, which has actual recognition methods.

ATTENTION!

IdEngine::Create() is a factory method and returns an allocated pointer. You are responsible for deleting it.

See more about configuration bundles in Configuration Bundles.

Setting up a recognition session

Creating a session setting object

Create IdSessionSettings from configured IdEngine:

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

// Java
import com.smartengines.id.*;

IdSessionSettings settings = engine.CreateSessionSettings();

ATTENTION!

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

Enabling document types

Enable required document types as shown in the following examples:

// C++
settings->AddEnabledDocumentTypes("deu.id.*"); // Enabling German ID cards in this session

// Java
settings.AddEnabledDocumentTypes("deu.id.*"); // Enabling German ID cards in this session

See more about document types in Supported document types.

Specifying additional session options 

This step is not required.

To set additional session options:

// C++
settings->SetOption("common.extractTemplateImages", "true"); // Forcing to acquire full template images

// Java
settings.SetOption("common.extractTemplateImages", "true"); // Forcing to acquire full template images

The possible session options are listed in the Session options section.

Spawning  an IdSession

A personal signature is provided to the customer when the Smart ID Engine product is delivered. This signature is located in the README.html file in the /doc directory. 

Each time a recognition Id Engine session instance is created, the signature must be passed as one of the arguments to the session creation function. It confirms that the caller is authorized to use the library and unlocks the library. 

Functionality is checked offline, the library does not access any external resources.

Spawn an IdSession:

// C++
const char* signature = "... YOUR SIGNATURE HERE ..."; // Your personal signature you use to start Smart ID Engine session
std::unique_ptr<se::id::IdSession> session(
engine->SpawnSession(*settings, signature, &my_feedback));

// Java
import com.smartengines.id.*;
String signature = "... YOUR SIGNATURE HERE ..."; //Your personal signature you use to start Smart ID Engine session
IdSession session = engine.SpawnSession(settings, signature, my_feedback);

ATTENTION!

IdEngine::SpawnSession() is a factory method and returns an allocated pointer. You are responsible for deleting it.

Callbacks

Optionally, you may implement callbacks by using the IdFeedback subclass:

// C++
class MyFeedback : public se::id::IdFeedback { /* callbacks */ };
// ...
MyFeedback my_feedback;

// Java
import com.smartengines.id.*;
class MyFeedback extends IdFeedback { /* callbacks */ }
// ...
MyFeedback my_feedback = new MyFeedback();

See more about callbacks in Processing Feedback.

Creating an Image

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
import com.smartengines.common.*;
Image image = Image.FromFile(image_path);

ATTENTION!

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

Processing the image 

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

// C++
const se::id::IdResult& result = session->Process(*image);

// Java
import com.smartengines.id.*;
IdResult result = session.Process(image);

ATTENTION!

IdResult::Process() is not a factory method, but the returned result object is not independent. The result object lifetime does not exceed the session lifetime.

Recognition result

To perform recognition in a video stream, process the frames sequentially within the same session. The processing time is unlimited, but the best practice is  processing frames coming from the stream until result.GetIsTerminal() is true.

Use IdResult fields to extract recognized information:

// C++
for (auto it = result.TextFieldsBegin(); it != result.TextFieldsEnd(); ++it) {
    const se::id::IdTextField& field = it.GetValue();
    bool is_accepted = field.GetBaseFieldInfo().GetIsAccepted(); // Accept flag value
    std::string field_value = field.GetValue().GetFirstString().GetCStr(); // UTF-8 string representation of the recognized result

}

// Java
import com.smartengines.id.*;
for (IdTextFieldsMapIterator it = result.TextFieldsBegin();
     !it.Equals(result.TextFieldsEnd());
     it.Advance()) {
    IdTextField field = it.GetValue();
    boolean is_accepted = field.GetBaseFieldInfo().GetIsAccepted(); // Accept flag value
    String field_value = field.GetValue().GetFirstString().GetCStr(); // UTF-8 string representation of the recognized result
}

Apart from the text fields there also are image fields and other types of fields:

// C++
for (auto it = result.ImageFieldsBegin(); it != result.ImageFieldsEnd(); ++it) {
    const se::id::IdImageField& field = it.GetValue();
    const se::common::Image& image = field.GetValue();
}

// Java
import com.smartengines.id.*;
for (IdImageFieldsMapIterator it = result.ImageFieldsBegin();
    !it.Equals(result.ImageFieldsEnd());
     it.Advance()) {
    IdImageField field = it.GetValue();
    Image image = field.GetValue();
}

SDK Overview

This section describes examples of the delivery package, header files, namespaces, and modules and their usage.

Delivery package structure

The basic Smart ID Engine delivery package includes: 

  • C++ prebuilt library;
  • documentation;
  • usage examples;
  • prebuilt wrappers for C#/Java/Python/PHP;
  • obj-C/React/Flutter wrapper source code for mobile platform;
  • the wrapper auto generators to build the wrappers for the client’s product environment (If the auto generator fails to start, use the client’s exact version of Python 3 or PHP).

The files are arranged in directories as shown in the table below:

Directory Contents Description
secommon C++ se::common namespace files Common classes, such as Point, OcrString, Image, etc.
See Common classes
Files of integration, for example,
Java com.smartengines.common module (one compiled file)
idengine C++ se::id namespaces  Main classes of Smart ID Engine.
See Main classes
Files , files of integration, for example
Java com.smartengines.id module (one compiled file)
doc Documentation See Code documentation
samples Complete compilable and runnable usage examples  
data-zip  Bundle files in format:
bundle_something.se 
Configuration files
See Configuration bundles

Common classes

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

For C++ these are such header as:

Header Description
#include <secommon/se_export_defs.h>   Contains export-related definitions of Smart Engines libraries
#include <secommon/se_exceptions_defs.h>   Contains the definition of exceptions used in Smart Engines libraries
#include <secommon/se_geometry.h>   Contains geometric classes and procedures (Point, Rectangle, etc.)
#include <secommon/se_image.h>   Contains the definition of the Image class 
#include <secommon/se_string.h>   Contains the string-related classes (MutableString, OcrString, etc.)
#include <secommon/se_string_iterator.h>   Contains the definition of string-targeted iterators
#include <secommon/se_serialization.h>   Contains auxiliary classes related to object serialization (not used in Smart ID Engine)
#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 classes

The main Smart ID Engine classes are located within se::id namespaces and are located within an idengine directory:

Header Description
#include <idengine/id_document_info.h> Provides information about the document type (textual document description)
#include <idengine/id_engine.h>   Contains IdEngine class definition
#include <idengine/id_session_settings.h>  Contains IdSessionSettings class definition
#include <idengine/id_session.h>   Contains IdSession class definition
#include <idengine/id_result.h>   Contains IdResult class definition, as well as IdTemplateDetectionResult and IdTemplateSegmentationResult
#include <idengine/id_fields.h>   Contains the definitions of classes representing Smart ID Engine fields
#include <idengine/id_feedback.h>   Contains the IdFeedback interface and associated containers
#include <idengine/id_face_feedback.h>   Contains the IdFaceFeedback interface
#include <idengine/id_face_session_settings.h>   Contains IdFaceSessionSettings class definition
#include <idengine/id_face_session.h>   Contains IdFaceSession class definition
#include <idengine/id_face_result.h>   Contains classes representing the Face matching result-related objects
   
#include <idengine/id_field_processing_session_settings.h>   Contains IdFieldProcessingSessionSettings class definition
#include <idengine/id_field_processing_session.h>   Contains the definition of the session for auxiliary fields processing
#include <idengine/id_file_analysis_session.h> Session checking the image for anomalies
#include <idengine/id_file_analysis_session_settings.h> Setting session checking the image for anomalies

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

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

Documentation

All the classes, their methods, the methods options and options values are described both in comments that are converted into idengine.pdf included into the documentation directory. 

The documentation is available at doc directory. The doc directory structure:

  • DOCUMENTS_REFERENCE.html – contains the list of the countries whose documents are supported, of the supported document types and their description;
  • README.html – brief description of Smart ID Engine SDK;
  • best_practices.html – recommendations on product usage;
  • idengine.pdf – description of the classes, their methods etc.;
  • NOTICE.txt – contains information about the used external software;
  • WHATSNEW.txt – contains information about updates.

Exceptions

The C++ API may throw se::common::BaseException subclasses when the user passes invalid input, makes bad state calls or if something else goes wrong. 

The following exception (se::common::BaseException) subclasses are implemented:

Exception name Description
FileSystemException Thrown if an attempt is made to read from a non-existent file, or other file-system related IO error
InternalException Thrown if an unknown error occurs or if the error occurs within internal system components
InvalidArgumentException Thrown if a method is called with invalid input parameters
InvalidKeyException Thrown if to an associative container the access is performed with an invalid or a non-existent key, or if the access to a list is performed with an invalid or out-of-range index
InvalidStateException Thrown if an error occurs within the system in relation to an incorrect internal state of the system objects
MemoryException Thrown if an allocation is attempted with insufficient RAM
NotSupportedException Thrown when trying to access a method which given the current state or given the passed arguments is not supported in the current version of the library or is not supported at all by design
Uninitialized Object Exception Thrown if an attempt is made to access a non-existent or non-initialized object

Exceptions contain useful human-readable information. Please read e.what() message if exception is thrown. 

Note

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

The thrown exceptions are wrapped in general java.lang.Exception. In Java, the exception type is included in the corresponding message text.

If you face a problem, or contact us at sales@smartengines.com or support@smartengines.com.

Factory methods and memory ownership

Several Smart ID 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)

TIP

In C++:
For simple memory management and avoiding memory leaks, use smart pointers, such as std::unique_ptr<T> or std::shared_ptr<T>.

In Java API:
For the objects which are no longer needed, use the .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 ID Engine to be created and configured. Usually they are named as bundle_something.se and located inside data-zip directory.

Supported document types

document type is simply a string encoding a real document type you want to recognize, for example, are.passport.type1 or deu.id.type1

Document types that Smart ID Engine SDK can potentially recognize can be obtained using the following procedure:

// C++
// Iterating through internal engines
for (auto engine_it = settings->InternalEngineNamesBegin();
     engine_it != settings->InternalEngineNamesEnd();
     ++engine_it) {
    // Iterating through supported document types for this internal engine
    for (auto it = settings->SupportedDocumentTypesBegin(engine_it.GeValue());
         it != settings->SupportedDocumentTypesEnd(engine_it.GetValue());
         ++it) {
        // it.GetValue() returns the supported document type within the
        // internal engine with name engine_it.GetValue()
    }
}

// Java
// Iterating through internal engines
for (StringsSetIterator engine_it = settings.InternalEngineNamesBegin();
     !engine_it.Equals(settings.InternalEngineNamesEnd());
     engine_it.Advance()) {
    // Iterating through supported document types for this internal engine
    for (StringsSetIterator it = settings.SupportedDocumentTypesBegin(engine_it.GeValue());
         !it.Equals(settings.SupportedDocumentTypesEnd(engine_it.GetValue()));
         it.Advance()) {
        // it.GetValue() returns the supported document type within the
        // internal engine with name engine_it.GetValue()
    }
}

ATTENTION!

In a single session you can specify only document types that belong to the same internal engine. Otherwise, an exception will be thrown

Since all documents in settings are disabled by default, you need to enable some of them. 

To do it, you may use AddEnabledDocumentTypes(…) method of IdSessionSettings class:

// C++
settings->AddEnabledDocumentTypes("deu.id.type1"); // Enables German ID card of the 1st type

// Java
settings.AddEnabledDocumentTypes("deu.id.type1"); // Enables German ID card of the 1st type

You may also use RemoveEnabledDocumentTypes(…) method to remove already enabled document types.

Wildcard expressions

For convenience it’s possible to use wildcards (using asterisk symbol) for enabling or disabling document types. 

When using document types related methods, each passed document type is matched against all supported document types. All matches in supported document types are added to the enabled document types list. 

For example, document type deu.passport.type1 can be matched with deu.*, *passport* and of course a single asterisk *.

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

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

TIP

Enable the minimum number of document types as possible to increase recognition quality 

Session modes

Based on the list of supported document types in the configuration bundle, and on the document masks, the engine is determining which internal engine to use in the created session. 

However, what if there have to be multiple engines which support a certain document type? For example, a USA Passport (usa.passport.*) can be recognized both in the internal engine for recognition of all USA documents, and in the internal engine for recognition of all international passports. To sort this out there is a concept of session modes.

To get the list of available session modes in the provided configuration bundle, you can use the corresponding method of the IdSessionSettings:

// C++
for (auto it = settings->SupportedModesBegin();
     it != settings->SupportedModesEnd();
     ++it) {
    // it.GetValue() is a name of a supported mode
}

// Java
for (StringsSetIterator it = settings.SupportedModesBegin();
     !it.Equals(settings.SupportedModesEnd());
     it.Advance()) {
    // it.GetValue() is a name of a supported mode
}

By default, the default mode is enabled. 

To get the currently enabled mode and to set a new one, use the following methods:

// C++
std::string current_mode = settings->GetCurrentMode();
settings->SetCurrentMode("anypassport"); // Setting a current mode to AnyPassport
settings->AddEnabledDocumentTypes("*");  // Setting a document type mask _within a mode_

// Java
String current_mode = settings.GetCurrentMode();
settings.SetCurrentMode("anypassport"); // Setting a current mode to AnyPassport
settings.AddEnabledDocumentTypes("*"); // Setting a document type mask _within a mode_

The following modes are usually applied:

Session mode Recognized document types
anydoc all identity documents
anypassport international passports of all countries
anyid ID cards of all countries
anydrvlic driving licenses of all countries

Session options

You can specify some options in runtime by using IdSessionSettings methods. 

To obtain all currently set option names and their values. use 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
}

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

// C++
settings->SetOption("common.extractTemplateImages", "true");
settings->SetOption("common.sessionTimeout", "3.0");

// Java
settings.SetOption("common.extractTemplateImages", "true");
settings.SetOption("common.sessionTimeout", "3.0");

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

Option name Value type Default Description
Common options
common.enableMultiThreading “true” or “false” “true” Enables parallel execution of internal algorithms
common.extractRawFields “true” or “false” “false” Enables output of raw physical field recognition results (without integration or postprocessing) in the RecognitionResult
common.extractTemplateImages “true” or “false” “false” Extracts rectified template images (document pages) in the ImageFields section of the RecognitionResult
common.rgbPixelFormat String of characters R, G, B, and A “RGB” for 3-channel images, “BGRA” for 4-channel images Sequence of color channels for session.ProcessSnapshot() method image interpretation
common.sessionTimeout Double value “0.0” for server bundles, “5.0” for mobile bundles Session timeout in seconds
common.extractImageFieldsInSourceResolution “true” or “false” “false” Extracts ImageFields (such as photo or signature) in the resolution closest to the input image. If disabled, the resolution corresponds to the default internal template dimensions.
common.enableStoppers “true” or “false” “true” Enables smart text fields stoppers
common.constrainMultiThreading Integer number “0” Restricts the number of threads. Unlimited by default
common.currentDate DD.MM.YYYY n/a Current date required for dates verification
common.forceRawFieldsSourceExtraction “true” or “false” “false” Forces cropping of raw field images from source image
common.anyPassportMrzRequired “true” or “false” “false” Enables “light” mode of the AnyPassport module, with a hard restriction that MRZ is required
Barcode, MRZ, bank card options
common.barcodeAllowedSymbologies String mask, separated with ‘ | ‘ “ALL” The list of allowed barcode symbologies. Valid values:
  • ALL includes all the valid character sets: 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, each can be connected separately.
Additionally, there are parameter groups:
  • COMMON – the most common set. Includes the charsets: AZTEC | QR_CODE | DATA_MATRIX | PDF_417 | CODABAR | CODE_128 | EAN_8 | EAN_13_UPC_A | ITF | UPC_E | CODE_39 | CODE_93;
  • ALL_1D, includes the charset: CODABAR | CODE_128 | EAN_8 | EAN_13_UPC_A | ITF | UPC_E | CODE_39 | CODE_93;
  • ALL_2D, includes the charset: AZTEC | QR_CODE | MICRO_QR | RMQR | DATA_MATRIX | PDF_417 | MICRO_PDF_417
common.barcodeMaxNumberPerFrame Integer number “1” Maximum number of barcodes searched in any given frame
common.barcodeRoiDetectionMode “focused”, “anywhere” or “dummy” “focused” Barcode ROI detection mode
common.barcodeFeedMode “sequence” or “single” “single” Mode of internal barcode detection and temporal integration.
  • single – individual frames are recognized. All found and read barcodes on the frame are returned;
  • sequence – recognition continues until it is explicitly canceled by the user. All barcodes found and read during the session are returned
common.barcodeInterpretation String mask, separated with ‘|’ “” Mask for decoding and interpreting barcodes (AAMVA, GS1, etc.)
common.barcodeEffortLevel “low”, “normal” or “high” “normal” Effort level for detecting barcodes
common.useMrzControlDigitPostprocessing “true” or “false” “false” Assumes valid MRZ checksums and uses this assumption for statistical language model postprocessing
common.useLuhnCodeCheck “true” or “false” “true” Enables Luhn code validity assumption in bank card number statistical post-processing

Processing Feedback

Smart ID Engine SDK supports optional callbacks during document analysis and recognition process before the Process(…) method is finished. It allows the user to be more informed about the underlying recognition process and also helps create more interactive GUI.

To support callbacks, you need to subclass IdFeedback class and implement desirable callback methods:

// C++
class MyFeedback : public se::id::IdFeedback {
public:
  virtual ~OptionalFeedback() override = default;
public:
  virtual void FeedbackReceived(
      const se::id::IdFeedbackContainer& /*feedback_container*/) override { }
  virtual void TemplateDetectionResultReceived(
      const se::id::IdTemplateDetectionResult& result) override { }
  virtual void TemplateSegmentationResultReceived(
      const se::id::IdTemplateSegmentationResult& /*result*/) override { }
  virtual void ResultReceived(const se::id::IdResult& result) override { }
  virtual void SessionEnded() override { }
};

// Java
import com.smartengines.id.*;
class MyFeedback extends IdFeedback {
  public void FeedbackReceived(IdFeedbackContainer feedback_container) { }
  public void TemplateDetectionResultReceived(IdTemplateDetectionResult result) { }
  public void TemplateSegmentationResultReceived(IdTemplateSegmentationResult result) { }
  public void ResultReceived(IdResult result) { }
  public void SessionEnded() { }
}

Methods TemplateDetectionResultReceived(…) and TemplateSegmentationResultReceived(…) are used to display document zones and fields bounds in GUI during live video stream recognition.

You also need to create an instance of MyFeedback somewhere in the code and pass it when you spawn the session:

// C++
MyFeedback my_feedback;
std::unique_ptr<se::id::IdSession> session(
    engine->SpawnSession(*settings, signature, &my_feedback));

// Java
import com.smartengines.id.*;
>MyFeedback my_feedback = new MyFeedback();
>IdSession session = engine.SpawnSession(settings, signature, my_feedback);

ATTENTION!

Do not delete IdFeedback subclass instances while IdSession is alive. It is recommended to place them in the same scope.

Java API Specifics

Smart ID Engine SDK implies Java API which is automatically generated from C++ interface using the SWIG tool.

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

Object deallocation

Even though garbage collection is present and works, it’s strongly advised to call obj.delete() functions for our API objects manually because they are wrappers to the heap-allocated memory and their heap size is unknown to the garbage collector, which may result in delayed deletion of objects and thus in high overall memory consumption.

import com.smartengines.id.*;
IdEngine engine = IdEngine.Create(config_path); // or any other object
// ...
engine.delete(); // forces and immediately guarantees wrapped C++ object deallocation

Feedback scope

ATTENTION!

When using optional callbacks by subclassing IdFeedback please make sure that its instance has the same scope as IdSession. The reason for this is that our API does not own the pointer to the feedback instance which cause premature garbage collection resulting in crash

// Java
// BAD: may cause premature garbage collection of the feedback instance
class MyDocumentRecognizer {
    private IdEngine engine;
    private IdSession session;
    private void InitializeSmartIdEngine() {
        // ...
        session = engine.SpawnSession(settings, signature, new MyFeedback());
        // feedback object might be garbage collected there because session doesn't own it
    }
}

// Java
// GOOD: reporter have at least the scope of recognition session
class MyDocumentRecognizer {
    private IdEngine engine;
    private IdSession session;
    private MyGeedback feedback; // feedback has session's scope
    private void InitializeSmartIdEngine() {
        // ...
        feedback = new MyFeedback();
        session = engine.SpawnSession(settings, signature, feedback);
    }
}

FAQ

  • How can I test the system?

    You can install demo apps from Apple Store and Google Play from the links below:

    Google Play

    Apple Store

  • Which sample do I need?

    You need samples from idengine_sample* directory. smartid_sample* uses the legacy interface and is presented only for testing backward compatibility.

  • How can I install and test your library?

    We provide the classic SDK as a library and its integration samples, you need to install one of the examples (you can find it in the /samples directory).

  • What file formats are supported?

    Supported formats:

    • jpeg, tiff (except TIFF_ZIP and TIFF_JPEG), png, bmp;
    • base64 (the formats from the paragraph above);
    • a file buffer with preliminary indication of the color scheme, width\height\stride\number of channels.
  • What should I do if I need to recognize an image in PDF format?

    We do not support PDF and recommend rasterizing it (converting it to a supported format) on our side before recognition.

  • Is there any API in your engine to help us identify the country of the passport?

    There are special engines in our system which are able to recognize documents by type, e.g. all passports (anypassport), EU ID’s, etc., to use this engine you need to make sure that you have this engine (you could list all supported modes and engines, see provided samples from /samples) or contact us at sales@smartengines.com or support@smartengines.com.

  • How can I update to the new version?

    You need to replace the libraries from /bin, bindings (from /bindings respectively) and configuration bundle (*.se file from /data-zip) You can find it in the provided SDK.

  • How can I find out what documents and engines are available to me?

    Inside our library all documents are sorted by engines, and engines sorted by modes, you can find the list of available modes, engines and documents using methods from IdSessionSettings. (see provided samples from /samples).

  • I have the SDK version for Windows, but our production system will use any OS from the Linux family. How do I run in a Linux-based docker container?

    Our SDK is platform-dependent, so please contact us at sales@smartengines.com or support@smartengines.com and we will provide you with the required SDK.

  • I have an SDK for Centos 7 and try to run it on Ubuntu/Debian/Alpine. I have a lot of “undefined symbol” errors.

    Please don’t run SDK for operating systems not intended for it and contact us at sales@smartengines.com or support@smartengines.com to provide you with the required SDK.

Common Errors

  1. Failed to verify static auth.

    Maybe, the signature you have specified is invalid.

  2. Found no single engine that supports settings-enabled document types.

    The bundle does not contain the specified documents mask or the specified mask matched with documents from multiple internal engines in the current mode. See Configuration bundles.

  3. Failed to initialize IdEngine: mismatching engine version in config.

    You cannot use a bundle version different from the library version. The files from the same SDK should be used.

  4. libidengine.so:cannot open shared object file:no such file or directory.

    Many integrations require additional assembly of the wrapper to work with the C++ library. This error occurs when the wrapper cannot find the main library at the specified path. It must either be placed in the scope of the code through environment variables, or the wrapper must be compiled with the correct paths to the library.

  5. for PYTHON and PHP:libpython3.x.x:cannot open shared object file: No such file or directory.

    The module you are using is built for a different version of python, /samples/idengine_sample_*/ contains a script for building the module on your side. Don’t forget that you must have the dev packages installed for your language.

  6. Smart ID Engine: best practices

    1. On mobile platforms, a common example of a recognition screen interface is a document drawing overlaid on top of the camera preview – this helps the user align the document with the camera. We do not recommend cropping the image according to your drawing, especially for barcodes and bank cards, since the search algorithm for this type of document works very quickly and the object can be recognized before the user places it in the required area. Give a full image for recognition, cropping is applied for UX.
    2. In mobile SDKs, we recommend placing the “Scan” button on the camera preview screen – this will allow the user to align the document better, wait for focusing and initialization of the engine before starting OCR. This trick allows you to speed up the capture process, since the engine will process fewer empty initial frames.
    3. We recommend judging the quality of recognition by the isAccepted field attribute. If you need a more precise understanding of the quality of the recognition result, you can focus on the Confidence attribute, also available for each text field.
    4. On mobile platforms, initialize the recognition engine asynchronously before making the document scanning button available. In this case, the user will not have to wait for the engine to initialize when it is time to scan the document.
    5. Do not store your personalized signature in a readable form (i.e. in resources), always store it either encoded in the application binary or load it remotely.
    6. The bundle is located separately from the library, so to minimize the size of the application, it can be downloaded from your servers on demand if necessary. 
    7. On mobile platforms, initialization of the library (calling the Create() method) must be carried out strictly in one instance.This process is the most difficult operation (like the image analysis itself), so it should always be done outside the UI thread. Based on one instance, many recognition sessions can be generated. Sessions can be run in parallel and will not affect each other.
    8. All features of our SDK are described in the idengine.pdf document – the main C++ library reference.
    9. On mobile platforms, it is advisable to enable lazy initialization. In server versions, where the library is initialized once at application startup, we recommend disabling the lazy initialization.
    10. If you are downloading images from a file, make sure that the downloaded files are located on a high-performance disk device. On some devices, the time it takes to load an image from a file may be longer than the time of recognition itself.
    11. Avoid pre-processing any input images. Our products work best with images taken directly from the capture device (a camera or a scanner).
    12. Avoid extremely large images. Sometimes high image resolution does not increase quality, but only increases recognition time. 
    13. It is always better to specify the minimum set of documents that you intend to recognize. The library will spend less time searching.

Send Request

Please fill out the form to get more information about the products,pricing and trial SDK for Android, iOS, Linux, Windows.

    Our customers

    SignD

    SignD Unified Onboarding Platform uses Smart Engines AI-solution to OCR credit cards

    Smaregi

    Japanese provider of IT services Smaregi has adopted mobile OCR by Smart Engines

    Turkish Airlines

    Turkish Airlines uses Smart Engines’ ID scanning software

    2e Systems

    2e Systems use Smart Engines technologies in solutions for the airline industry.

    Send Request

    Please fill out the form to get more information about the products,pricing and trial SDK for Android, iOS, Linux, Windows.