Smart ID Engine is a multi-platform, stand-alone SDK for recognizing and identifying text fields of passports, visas and other identification documents.
The following operating systems are supported:
General workflow includes the following stages:
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:
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.
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.
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.
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.
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.
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.
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.
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.
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();
}
This section describes examples of the delivery package, header files, namespaces, and modules and their usage.
The basic Smart ID Engine delivery package includes:
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, 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;
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;
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:
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.
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
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.
A 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.
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
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 |
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:
|
| 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.
|
| 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 |
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.
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.
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
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);
}
}
You can install demo apps from Apple Store and Google Play from the links below:
You need samples from idengine_sample* directory. smartid_sample* uses the legacy interface and is presented only for testing backward compatibility.
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).
Supported formats:
We do not support PDF and recommend rasterizing it (converting it to a supported format) on our side before recognition.
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.
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.
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).
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.
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.
Maybe, the signature you have specified is invalid.
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.
You cannot use a bundle version different from the library version. The files from the same SDK should be used.
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.
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.
Send Request
Please fill out the form to get more information about the products,
pricing and trial SDK for Android, iOS, Linux, Windows.