Аналитический отчет: "Исследование актуальных угроз мошенничества с использованием поддельных документов"

Описание Smart ID Engine SDK

Описание ID Engine

Smart ID Engine — это многоплатформенный автономный SDK для распознавания и идентификации текстовых полей паспортов, виз и других документов, удостоверяющих личность.

Поддерживается 2787 типов удостоверяющих документов 235 юрисдикций мира и 4467 шаблонов.

Поддерживаемые операционные системы

Поддерживаются следующие операционные системы:

  • Windows;
  • Linux (включая РЕД ОС, OS ALT Linux, OS Astra Linux );
  • Mac OS;
  • ОС “Эльбрус”.
  • iOS;
  • Android;
  • OS Astra Linux;
  • ОС Аврора.

Жизненный цикл

Жизненный цикл IdEngine состоит из следующих этапов:

  1. создание экземпляра IdEngine, см. Создание экземпляра IdEngine;
  2. настройка сессии распознавания:
  1. опционально — реализация обратной связи, см. Обратная связь;
  2. создание объекта Image (изображения документа), см. Создание объекта Image;
  3. обработка  изображения, см. Обработка  изображения;
  4. парсинг результата распознавания, см. Парсинг результата распознавания.

Создание экземпляра IdEngine

Создайте экземпляр IdEngine:

// 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);

Параметры:

  • configuration_bundle_path — путь к конфигурационному бандлу-файлу, в котором прописаны настройки idEngine (файл с расширением .se);
  • булевое значение, активация “ленивой” конфигурации (true по умолчанию). Необязательный параметр. 
    • если активирована “ленивая” конфигурация, некоторые внутренние структуры будут инициализироваться только по мере необходимости;
    • если “ленивая” конфигурация отключена, все внутренние структуры  и компоненты будут инициализироваться с помощью метода  Create().

ПОДСКАЗКА

Отключите “ленивую” конфигурацию в следующих случаях:
• при работе с серверными приложениями, для которых время отклика первого распознавания приоритетней общего потребления памяти;
• для измерения максимального объема памяти, используемой приложением 

Конфигурирование может занять время, но его достаточно выполнить один раз за жизненный цикл. 

Сконфигурированный экземпляр объекта IdEngine используется для инициализации сессии распознавания – создания экземпляров объекта IdSession, содержащего методы распознавания.

ВНИМАНИЕ!

IdEngine::Create() является фабричным методом и возвращает указатель на выделенный в памяти объект, который следует удалить.

Конфигурационные бандлы подробно описаны в разделе  Конфигурационные бандл файлы

Настройка сессии распознавания

Создание объекта настроек сессии

Создайте объект IdSessionSettings на основе сконфигурированного экземпляра IdEngine:

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

// Java
import com.smartengines.id.*;
IdSessionSettings settings = engine.CreateSessionSettings();

ВНИМАНИЕ!

IdEngine::CreateSessionSettings()является фабричным методом и возвращает выделенный указатель, который следует удалить.

Включение типов документов в процесс распознавания

Задайте типы распознаваемых документов в соответствии с примером: 

// C++
settings->AddEnabledDocumentTypes("uae.id.*"); // Задает распознавание удостоверения личности гражданина ОАЭ

// Java
settings.AddEnabledDocumentTypes("uae.id.*"); // Задает распознавание удостоверения личности гражданина ОАЭ

Распознаваемые типы документов описаны в разделе Поддерживаемые типы документов.

Настройка дополнительных параметров сессии 

Необязательный этап.

Задайте дополнительные параметры сессии:

// C++
settings->SetOption("common.extractTemplateImages", "true"); // Получение изображений шаблона

// Java
settings.SetOption("common.extractTemplateImages", "true"); // Получение изображений шаблона

Возможные параметры приведены в разделе Параметры сессии распознавания.

Инициализация сесии

При поставке продукта Smart ID Engine клиенту передается персональная подпись. Она содержится в файле README.html в директории /doc. 

Каждый раз при создании экземпляра сессии распознавания IdSession подпись необходимо передавать в качестве одного из аргументов функции создания сессии. 

Это подтверждает право вызывающего на использование библиотеки и разблокирует ее.

Проверка подписи осуществляется в оффлайн режиме. Библиотека не обращается ни к каким внешним ресурсам.

Инициализируйте сессию (объект IdSession):

// C++
const char* signature = "... YOUR SIGNATURE HERE ..."; //Подпись, используемая для запуска сессии распознавания Smart ID Engine
std::unique_ptr<se::id::IdSession> session(
  engine->SpawnSession(*settings, signature, &my_feedback));

// Java
import com.smartengines.id.*;
String signature = "... YOUR SIGNATURE HERE ..."; //Подпись, используемая для запуска сессии распознавания Smart ID Engine
IdSession session = engine.SpawnSession(settings, signature, my_feedback);

Обратные вызовы

Можно настроить обратные вызовы. Для этого используйте подкласс IdFeedback:

// C++

class MyFeedback : public se::id::IdFeedback { /* обратные вызовы */ };
// ...
MyFeedback my_feedback;

// Java
import com.smartengines.id.*;
class MyFeedback extends IdFeedback { /* обратные вызовы */ }
// ...
MyFeedback my_feedback = new MyFeedback();

Обратные вызовы описаны в разделе Обработка обратной связи.

Создание объекта изображения документа

Создайте объект изображения (Image) для последующей обработки: 

// C++
std::unique_ptr<se::common::Image> image(
    se::common::Image::FromFile(image_path)); // Загрузка из файла

// Java
import com.smartengines.common.*;
Image image = Image.FromFile(image_path);

ВНИМАНИЕ!

Image::FromFile() является фабричным методом и возвращает указатель на выделенный в памяти объект, который следует удалить

Обработка изображения документа 

Вызовите метод Process(…) для обработки изображения документа :

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

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

ВНИМАНИЕ!

Image::FromFile() не фабричный метод, но возвращаемый объект  result не является независимым, его срок жизни не превышает срок жизни объекта session.

Парсинг результата распознавания 

При работе с видеопотоком обрабатывайте кадры последовательно в рамках одной и той же сессии. Время обработки не ограничено, но рекомендуется выполнять обработку до получения значения true параметра result.GetIsTerminal().

Значения текстовых полей объекта IdResult содержат информацию о результатах распознавания:

// C++
for (auto it = result.TextFieldsBegin(); it != result.TextFieldsEnd(); ++it) {
    const se::id::IdTextField& field = it.GetValue();
    bool is_accepted = field.GetBaseFieldInfo().GetIsAccepted(); // Получение значения флага is_accepted
    std::string field_value = field.GetValue().GetFirstString().GetCStr(); // Получение результата распознавания поля в виде строки в кодировке UTF-8
}

// 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(); // Получение значения флага is_accepted
    String field_value = field.GetValue().GetFirstString().GetCStr(); // Получение результата распознавания поля в виде строки в кодировке UTF-8
}

Помимо текстовых, выводятся значения полей других типов, например, графических:

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

Структура пакета поставки

Состав базового пакета поставки Smart ID Engine: 

  • библиотека на языке C++;
  • обертка для C#/Java/Python/PHP;
  • исходный код обертки obj-C или/и React/Flutter для мобильных платформ;
  • автогенераторы для сборки оберток для продуктовой среды клиента (точная версия клиента на Python 3 или PHP. Рекомендуется использовать при возникновении проблем);
  • документация;
  • примеры.

Структура директорий: 

Директория Содержимое Описание
secommon Файлы пространств имен
C++ se::common 		Общие классы, например, Point, OcrString, Image, и т.д.
См. Общие классы
Файлы интеграции, например, модуль
Java com.smartengines.common (скомпилирован в один файл)

idengine

 пространства имен C++ se::id  Основные классы — main.
См. Основные классы
Файлы интеграции: например, модуль
Java com.smartengines.id 
(скомпилирован в один файл)

doc

Документация

 См. Документация
samples Полностью скомпилированный и готовый к использованию тестовый пример
data-zip Конфигурационные бандл файлы в формате:
bundle_something.se  		Конфигурационные бандл файлы
См. Конфигурационные бандл файлы

Общие классы 

Общие классы, например, Point, OcrString, Image и т.д., находятся в пространстве имен se::common в директории secommon.

Это следующие заголовочные файлы C++:

Заголовочный файл Описание
#include <secommon/se_export_defs.h> Содержит определения экспорта в библиотеках Smart Engines
#include <secommon/se_exceptions_defs.h> Содержит определения исключений в библиотеках Smart Engines
#include <secommon/se_geometry.h> Содержит классы и процедуры, описывающие геометрию (Point, Rectangle, и т.п..)
#include <secommon/se_image.h> Содержит классы и процедуры обработки изображений
#include <secommon/se_string.h>   Содержит классы строк (MutableString, OcrString, и т.д..)
#include <secommon/se_string_iterator.h>   Содержит определение итераторов строк
#include <secommon/se_serialization.h>   Содержит вспомогательные классы, связанные с сериализацией объектов (не используется в Smart ID Engine)
#include <secommon/se_common.h>   Вспомогательный заголовок, который включает в себя все вышеперечисленное.

Аналогичные Java API содержатся в модуле com.smartengines.common:

// Java
import com.smartengines.common.*; // Импорт классов пакета se::common classes

Основные классы

Основные классы Smart ID Engine содержатся в пространстве имен se::id в директории idengine:

Заголовочный файл Описание
#include <idengine/id_document_info.h> Предоставляет информацию о типе документа  (текстовое описание документа)
#include <idengine/id_engine.h>   Содержит класс IdEngine
#include <idengine/id_session_settings.h>  Содержит определение класса IdSessionSettings
#include <idengine/id_ session.h>   Содержит определение класса IdSession
#include <idengine/id_result.h>   Содержит определение класса IdResult, IdTemplateDetectionResult и IdTemplateSegmentationResult
#include <idengine/id_fields.h>   Содержит определения классов, описывающий поля Smart ID Engine
#include <idengine/id_feedback.h>   Содержит интерфейс обратной связи IdFeedback и связанные с ним контейнеры
#include <idengine/id_face_feedback.h>   Содержит интерфейс IdFaceFeedback 
#include <idengine/id_face_session_settings.h>   Содержит определение класса IdFaceSessionSettings 
#include <idengine/id_face_session.h>   Содержит определение класса IdFaceSession 
#include <idengine/id_face_result.h>   Содержит классы, описывающие результат распознавания лица  
#include <idengine/id_field_processing_session_settings.h>   Содержит определение класса IdFieldProcessingSessionSettings 
#include <idengine/id_field_processing_session.h>   Содержит определение сессии обработки вспомогательных полей 
#include <idengine/id_file_analysis_session.h> Cессия проверки изображения на наличие аномалий
#include <idengine/id_file_analysis_session_settings.h> Настройки  сессии проверки изображения на наличие аномалий

Аналогичные классы Java API содержатся в модуле com.smartengines.id:

// Java
import com.smartengines.id.*; // Импорт всех классов se::id classes

Документация

Все классы, методы, их параметры и значения параметров описаны в комментариях к коду, а также в справочном руководстве idengine.pdf, содержащемся в директории с документацией. 

Вся документация содержится в папке doc. Структура папки doc:

  • DOCUMENTS_REFERENCE.html — содержит список стран, документы которых поддерживаются Smart ID Engine, список поддерживаемых документов и их описание;
  • README.html — краткое описание SDK Smart ID Engine;
  • best_practices.html — рекомендации по использованию продукта;
  • idengine.pdf — описание классов, методов и т.д.;
  • NOTICE.txt — содержит информацию об используемом стороннем программном обеспечении;
  • WHATSNEW.txt — содержит описание обновлений. 

Обработка исключений

C++ API может выдавать исключения подклассов se::common::BaseException при неверном вводе данных, некорректных вызовах и других ошибках. Поддерживаются следующие подклассы исключений:

Исключение Описание
FileSystemException Выдается при попытке чтения из несуществующего файла или другой ошибке ввода-вывода, связанной с файловой системой
InternalException Выдается, если возникает неизвестная ошибка или ошибка возникает во внутренних компонентах системы.
InvalidArgumentException Выдается, если метод вызывается с недопустимыми входными параметрами
InvalidKeyException Выдается при попытке  доступа к ассоциативному контейнеру о с недействительным или несуществующим ключом или доступа к списку с недопустимым индексом или индексом, выходящим за пределы допустимого диапазона
InvalidStateException Выдается, если в системе возникает ошибка из-за неправильного внутреннего состояния системных объектов
MemoryException Выдается при попытке выделения объектов при недостаточном объеме оперативной памяти.
NotSupportedException Выдается при попытке доступа к методу, который с учетом текущего состояния или переданных аргументов не поддерживается в текущей версии библиотеки или не поддерживается вообще
Uninitialized Object Exception Выдается при попытке доступа к несуществующему или неинициализированному объекту 

При возникновении исключений, выводятся сообщения, понятные пользователю, с помощью метода e.what().

Примечание

 se::common::BaseException не является подклассом std::exception.

Интерфейс Smart ID Engine не имеет зависимостей от STL.

Оберткой для исключений Java API является общий класс java.lang.Exception. Тип исключения включен в текст сообщения.

Фабричные методы и управление памятью

Некоторые классы Smart ID Engine SDK содержат фабричные методы, возвращающие указатели на объекты, выделенные в куче.  Необходимо удалять такие объекты. 

ПОДСКАЗКА

В C++:
Для простоты управления памятью и предотвращения ее утечек пользуйтесь умными указателями std::unique_ptr<T> или std::shared_ptr<T> .

В Java API:
Удаляйте ненужные объекты с помощью метода .delete()

При возникновении проблем, свяжитесь с нашей техподдержкой: sales@smartengines.ru or support@smartengines.ru.

Конфигурационные бандл файлы

В каждую поставку включен один или несколько бандлов – архивов, содержащих необходимые настройки для создания объектов и конфигурирования Smart ID Engine. Обычно они имеют имя bundle_something.se и находятся внутри папки data-zip.

Поддерживаемые типы документов

Тип документа представляет из себя строку (string), описывающую тип физического документа, который необходимо распознать. Например, rus.passport.national или uae.id.type1 (паспорт гражданина РФ или паспорт ОАЭ). 

Для получения типов документов, которые Smart ID Engine SDK может распознать, выполните процедуру:

// C++
// Прохождение по циклу найденных внутренних движков
for (auto engine_it = settings->InternalEngineNamesBegin();
     engine_it != settings->InternalEngineNamesEnd();
     ++engine_it) {
    // Прохождение по циклу найденных типов документов, поддерживаемых движком
    for (auto it = settings->SupportedDocumentTypesBegin(engine_it.GeValue());
         it != settings->SupportedDocumentTypesEnd(engine_it.GetValue());
         ++it) {
        // метод it.GetValue() возвращает тип документов внутри
        // движка engine_it.GetValue()
    }
}

// Java
// Прохождение по циклу найденных внутренних движков
for (StringsSetIterator engine_it = settings.InternalEngineNamesBegin();
     !engine_it.Equals(settings.InternalEngineNamesEnd());
     engine_it.Advance()) {
    // Прохождение по циклу найденных типов документов, поддерживаемых движком
    for (StringsSetIterator it = settings.SupportedDocumentTypesBegin(engine_it.GeValue());
         !it.Equals(settings.SupportedDocumentTypesEnd(engine_it.GetValue()));
         it.Advance()) {
        // метод it.GetValue() возвращает тип документов внутри
        // движка engine_it.GetValue()
    }
}

ВНИМАНИЕ!

В одной сессии указывайте только те типы документов, которые обрабатываются одним и тем же внутреннем движком. Иначе при инициации сессии система выдаст исключение

Укажите типы документов, которые необходимо распознавать, с помощью метода AddEnabledDocumentTypes(…) класса IdSessionSettings:

// C++
settings->AddEnabledDocumentTypes("uae.id.type1"); // Включение в процесс распознавания удостоверения личности гражданина ОАЭ 1-го типа

// Java
settings.AddEnabledDocumentTypes("uae.id.type1"); // Включение в процесс распознавания удостоверения личности гражданина ОАЭ 1-го типа

Для исключения типов документов из процесса распознавания, пользуйтесь методом RemoveEnabledDocumentTypes(…).

Использование масок

При указании типов документов можно пользоваться масками (задаются с помощью звездочек). Каждый тип документа, передающийся системе, сопоставляется со всеми поддерживаемыми типами. Если тот или иной тип поддерживается, то он добавляются в список распознаваемых.

Например, тип uae.passport.type1 соответствует маске uae.*, *passport* и просто с символу *.

// C++
settings->AddEnabledDocumentTypes("uae.*"); // Включение в процесс распознавания всех поддерживаемых документов ОАЭ

// Java
settings.AddEnabledDocumentTypes("uae.*"); // Включение в процесс распознавания всех поддерживаемых документов ОАЭ

ПОДСКАЗКА

Для повышения качества обработки, укажите минимальное количество распознаваемых типов документов 

Режимы распознавания

На основе полученного списка поддерживаемых типов документов, указанных в файле конфигурации, и заданных масок, система определяет, какой движок использовать в созданной сессии.

Может быть несколько движков, поддерживающих один и тот же тип документа. Например, паспорт ОАЭ (uae.passport.*) может относиться как к движку документов ОАЭ, так и движку всех паспортов мира. Для удобства и предотвращения коллизий при указании типа документа, введена абстракция, обозначающая режим распознавания,  мод (мode), которая позволяет гибко использовать как полную маску документов, так и звездочку «*» 

Воспользуйтесь методом IdSessionSettings для получения списка доступных режимов в пакете конфигурации:

// C++
for (auto it = settings->SupportedModesBegin();
     it != settings->SupportedModesEnd();
     ++it) {
    // it.GetValue() имя поддерживаемого режима
}

// Java
for (StringsSetIterator it = settings.SupportedModesBegin();
     !it.Equals(settings.SupportedModesEnd());
     it.Advance()) {
    // it.GetValue() имя поддерживаемого режима
}

По умолчанию используется мод default. 

Для получения текущего режима и установки нового, используйте методы: 

// C++
std::string current_mode = settings->GetCurrentMode();
settings->SetCurrentMode("anypassport"); // Устанавливает режим AnyPassport
settings->AddEnabledDocumentTypes("*");  // Задает маску типов документов, включенных в процесс распознавания

// Java
String current_mode = settings.GetCurrentMode();
settings.SetCurrentMode("anypassport"); // Устанавливает режим  AnyPassport
settings.AddEnabledDocumentTypes("*"); // Задает маску типов документов, включенных в процесс распознавания

Доступны следующие режимы распознавания: 

Режим Типы распознаваемых документов
anydoc все документы, удостоверяющие личность
anypassport международные паспорта всех стран
anyid удостоверения личности всех стран
anydrvlic водительские права всех стран

Типы распознаваемых документов можно переопределить по запросу заказчика.

Параметры сессии распознавания

Каждой сессии распознавания можно задать определенный набор параметров с помощью  методов класса  IdSessionSettings. 

Для получения имен параметров и их значений, выполните следующую процедуру: 

// C++
for (auto it = settings->OptionsBegin();
     it != settings->OptionsEnd();
     ++it) {
    // it.GetKey() возвращает имя параметра
    // it.GetValue() возвращает значение параметра
}

// Java
for (StringsMapIterator it = settings.OptionsBegin();
     !it.Equals(settings.OptionsEnd());
     it.Advance()) {
    // it.GetKey() возвращает имя параметра
    // it.GetValue() возвращает значение параметра
}

Для изменения значений параметров, воспользуйтесь методом SetOption(…) :

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

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

Значения параметров всегда представлены строкой (string). При необходимости передать целочисленное (integer) или булевое (bool) значение, преобразите их в строку.

Параметры common:

Параметр Тип возвращаемого значения Значение по умолчанию Описание
Общие параметры
common.enableMultiThreading «true» или «false» «true» Задает параллельное исполнение внутренних алгоритмов 
common.extractRawFields «true» или «false» «false» Задает вывод необработанных результатов распознавания физического поля (без интеграции или последующей обработки) в RecognitionResult
common.extractTemplateImages «true» или «false» «false» Извлекает исправленные изображения шаблонов (страницы документа) в разделе ImageFields в RecognitionResult
common.rgbPixelFormat Строка символов R, G, B, и A “RGB” для 3-канальных изображений, “BGRA” for 4-канальных изображений Последовательность цветовых каналов в методе session.ProcessSnapshot() 
common.sessionTimeout Double “0.0” для бандлов обработки на сервере, ”5.0” для бандлов обработки в мобильных приложениях Таймаут сессии в секундах
common.extractImageFieldsInSourceResolution «true» или «false» «false» Извлекает значение полей документа ImageFields (например, фото или подпись) в разрешении, приближенном к входному изображению. Если опция отключена, разрешение соответствует внутренним размерам шаблона по умолчанию.
common.enableStoppers «true» или «false» «true» Включает интеллектуальные ограничители (smart stoppers) текстовых полей
common.anyPassportMrzRequired «true» или «false» «0» Включает «облегченный» режим работы  AnyPassport с жестким ограничением, требующим наличие МЧЗ
common.constrainMultiThreading Integer number n/a Ограничивает количество потоков. По умолчанию — неограниченное количество 
common.currentDate DD.MM.YYYY «false» Текущая дата
common.forceRawFieldsSourceExtraction «true»или «false» «false» Принудительно обрезает необработанные полевые изображения по сравнению с исходным изображением
Параметры штрихкодов, МЧЗ, банковских карт
common.barcodeAllowedSymbologies Стрка с разделителем ‘|’ «ALL» Список разрешенных символик штрихкодов:
  • ALL включает все допустипые символики: AZTEC|QR_CODE|MICRO_QR|RMQR|DATA_MATRIX|PDF_417|MICRO_PDF_417|CODABAR|CODE_128|EAN_8|EAN_13_UPC_A|ITF|UPC_E|CODE_39|CODE_93, могут подключаться по отдельности. 
Дополнительные группы параметров:
  • COMMON — наиболее часто используемые символики. Включает: 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, включает символики: CODABAR|CODE_128|EAN_8|EAN_13_UPC_A|ITF|UPC_E|CODE_39|CODE_93;
  • ALL_2D, включает символики: AZTEC|QR_CODE|MICRO_QR|RMQR|DATA_MATRIX|PDF_417|MICRO_PDF_417
common.barcodeMaxNumberPerFrame Integer number «1» Максимальное количество искомых штрихкодов в любом заданном кадре
common.barcodeRoiDetectionMode «focused», «anywhere» или «dummy» «focused» Режим обнаружения штрихкода ROI 
common.barcodeFeedMode «sequence» or «single» «single» Режим подачи штрихкода на распознавание:
  • single — распознаются отдельные кадры. Возвращаются все найденные на кадре и прочитанные штрих-коды;
  • sequence — распознавание продолжается до тех пор, пока оно не будет явно отменено пользователем. Возвращаются все штрих-коды, найденные и прочитанные во время сеанса
common.barcodeInterpretation String mask, separated with ‘|’ «» Маска для декодирования и интерпретации штрихкодов (AAMVA, GS1, и т.д.)
common.barcodeEffortLevel «low», «normal» или «high» «normal» Уровень усилий для обнаружения штрихкодов
common.useMrzControlDigitPostprocessing «true» или «false» «false» Принимает допустимые контрольные суммы машиночитаемой зоны (МЧЗ) и использует для постобработки статистической языковой модели
common.useLuhnCodeCheck «true» или «false» «true» Включает предположение о достоверности алгоритма Луна при постобработке статистики по номерам банковских карт

Обработка обратной связи

Smart ID Engine SDK поддерживает дополнительные обратные вызовы во время анализа документов до завершения их обработки — метода Process(…). Это позволяет пользователю получать больше информации о базовом процессе распознавания, а также помогает создавать интерактивный графический интерфейс.

Для поддержки обратной связи, создайте подкласс класса IdFeedback и реализуйте необходимые методы:

// 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() { }
}

Пользуйтесь методами 
TemplateDetectionResultReceived(…) и TemplateSegmentationResultReceived(…) для отображения зон документа и и границ полей в графическом интерфейсе во время распознавания видеопотока в реальном времени.

Создайте экземпляр класса  MyFeedback и передайте его при инициализации сессии:

// 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);

ВНИМАНИЕ!

Не удаляйте экземпляры подкласса IdFeedback  IdSession во время жизни сессии. Рекомендуется поместить их в одну область видимости.

Особенности Java API

Smart ID Engine SDK включает в себя Java API, автоматически генерируемый из интерфейса C++ с помощью инструмента SWIG.

Интерфейс Java почти идентичен C++.

Освобождение объекта

Несмотря на то, что сборка мусора присутствует и работает, рекомендуется вызывать метод obj.delete() для наших объектов API вручную, поскольку они являются обертками памяти, выделенной в куче. Размер их кучи неизвестен сборщику мусора, что может привести к задержке удаления объектов и, следовательно, высокому общему потреблению памяти. 

IdEngine engine = IdEngine.Create(config_path); // или любой другой объект
// ...
engine.delete(); // гарантирует принудительное и немедленное освобождение обернутого объекта C++

Область видимости объектов обратной связи

ВНИМАНИЕ!

При использовании вспомогательного объекта обратной связи с помощью подкласса IdFeedback, убедитесь, что его экземпляр имеет ту же область видимости, что и IdSession. Причина этого в том, что наш API не не содержит указатель на экземпляр объекта обратной связи. В результате, сборка мусора выполняется преждевременно, что приводит к сбою

// Java
// Недостаток: может повлечь преждевременное удаление сборщиком мусора экземпляра объекта обратной связи (feedback)
class MyDocumentRecognizer {
    private IdEngine engine;
    private IdSession session;
    private void InitializeSmartIdEngine() {
        // ...
        session = engine.SpawnSession(settings, signature, new MyFeedback());
        // объект обратной связи (feedback) мoжет быть удален сборщиком мусора, т.к. объект - вне сессии
    }
}

// Java
// Преимущество: доступ к сессии распознавания
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);
    }
}

Часто задаваемые вопросы

  • Как протестировать систему?

    Можно скачать демо-версию в RuStore

  • Какой пример использовать?

    Пользуйтесь примером из папки idengine_sample*. Пример smartid_sample* содержит устаревший интерфейс и предназначен только для тестирования обратной связи. 

  • Как установить и протестировать вашу библиотеку?

    Мы предлагаем библиотеку в виде классического SDK и примеры интеграции. Установите один из наших примеров (они находятся в папке /samples).

  • Может ли ваше API определить страну выдачи паспорта?

    В нашей системе имеются специальные движки, которые могут распознавать тип документа, например, паспорта (anypassport), удостоверения личности ЕС и т.д. Необходимо убедиться, что у вас есть этот движок (список всех поддерживаемых режимов распознавания и движков представлены в примерах в папке /samples). Для получения информации можете связаться с нами по почте  sales@smartengines.ru или support@smartengines.ru.

  • Как обновить систему до новой версии?

    Замените библиотеки в папке /bin, связи (в папке /bindings) и бандл (файл*.se в папке /data-zip). Все это содержится в поставляемом SDK.

  • Как понять, какие движки и типы документов для меня доступны?

    Документы в нашей библиотеке распределены по движкам, движки — по модам. Получить список мод, движков и типов документов можно с помощью методов класса IdSessionSettings. (см. примеры в папке  /samples).

  • У меня есть версия SDK для Windows, но предстоит работать на ОС семейства Linux. Как запустить docker контейнер для Linux?

    Наш SDK зависит от платформы. Свяжитесь с нами по почте  sales@smartengines.ru or support@smartengines.ru, и мы передадим подходящий SDK.

  • У меня есть версия SDK для Centos 7. При попытке запустить ее Ubuntu/Debian/Alpine, появляется много ошибок «undefined symbol».

    Не рекомендуется использовать SDK на несовместимых ОС. Свяжитесь с нами по почте sales@smartengines.ru or support@smartengines.ru, и мы передадим подходящий SDK.

Распространенные ошибки

  1. Failed to verify static auth (Не удалось проверить подпись).

    Возможно, введена неверная подпись.

  2. Found no single engine that supports settings-enabled document types (Не найден движок, который бы поддерживал все типы документов, заданные в настройках).

    Пакет не содержит указанную маску документов или указанную маску, совпадающую с документами из нескольких внутренних движков в текущем режиме. Подробнее о бандле см. здесь.

  3. Failed to initialize IdEngine: mismatching engine version in config: (Не удалось инициализировать IdEngine: несоответствующая версия движка в конфигурации).

    Нельзя использовать бандл версии, отличной от версии библиотеки. Они должны быть из одного SDK.

  4. libidengine.so:cannot open shared object file:no such file or directory (не удается открыть файл общего объекта: нет такого файла или каталога).

    Во многих интеграциях необходима дополнительная сборка обертки для работы с библиотекой на С++. Эта ошибка возникает, когда обертка не может найти по указанному пути основную библиотеку. Ее необходимо либо поместить в область видимости кода через переменные окружения, либо скомпилировать обертку с корректными путями к библиотеке. 

  5. for PYTHON and PHPlibpython3.x.x:cannot open shared object file: No such file or directory (не удается открыть файл общего объекта: нет такого файла или каталога для PYTHON и PHPlibpython3.x.x)

    Такого файла или каталога нет: модуль, который вы используете, создан для другой версии python, /samples/id engine_sample_*/ содержит скрипт для сборки модуля на вашей стороне. Не забудьте, что у вас должны быть установлены пакеты разработки для вашего языка.

    6. Smart ID Engine: лучшие практики

    1. Частым случаем интерфейса экрана распознавания является рисунок документа, наложенный на превью камеры. Это помогает пользователю совместить документ с камерой. Мы не рекомендуем делать обрезку изображения по вашему рисунку, особенно в случае баркодов и банковских карт, поскольку алгоритм поиска этого типа документов работает очень быстро и объект может быть распознан раньше, чем пользователь поместит его в необходимую зону.
    2. В мобильных SDK мы рекомендуем размещать кнопку «Сканировать» на экране с превью камеры. Это позволит пользователю лучше выровнять документ, дождаться фокусировки и инициализации движка прежде, чем начать распознавание. Этот трюк позволяет ускорить процесс захвата, так как движок будет обрабатывать меньше пустых начальных кадров.
    3. Судить о качестве распознавания мы рекомендуем по атрибуту полей isAccepted. Если необходимо более точное понимание качества результата распознавания, вы можете ориентироваться на атрибут Confidence, также доступный для каждого текстового поля.
    4. В мобильных SDK инициализируйте движок распознавания асинхронно перед тем, как сделать доступной кнопку сканирования документов. Пользователю не придется ждать инициализации движка, когда придет время сканировать документ.
    5. Не храните свою персонализированную подпись в читаемом виде (т.е. в ресурсах), всегда храните ее либо закодированной в бинарном файле приложения, либо подгружайте удаленно.
    6. Бандл находится отдельно от библиотеки, поэтому для минимизации размера приложения его можно при необходимости загружать со своих серверов по требованию.
    7. На мобильных платформах инициализация библиотеки (вызов метода Create() ) должна осуществляться строго в одном экземпляре. Этот процесс является самой тяжелой операцией (как и сам анализ изображений), поэтому он всегда должен осуществляться вне UI потока. На базе одного экземпляра может быть порождено множество сеансов распознавания. Сессии можно запускать параллельно и они не будут влиять друг на друга.
    8. Все возможности нашего SDK описаны в документе idengine.pdf — справочном руководстве по интерфейсу основной библиотеки C++.
    9. На мобильных платформах желательно включать ленивую инициализацию. В серверных вариантах, где инициализация библиотеки происходит один раз при старте приложения, мы рекомендуем значение false.
    10. Если вы загружаете изображения из файла, убедитесь, что загруженные файлы размещены на высокопроизводительном дисковом устройстве. На некоторых машинах время загрузки изображения из файла может быть больше, чем время самого распознавания.
    11. Избегайте предварительной обработки входных изображений. Наши продукты лучше всего работают с изображениями, полученными непосредственно с устройства захвата (камеры или сканера).
    12. Избегайте излишне огромных изображений. Иногда большое разрешение изображения не дает прироста в качестве, а только влияет на увеличение времени распознавания.
    13. Всегда лучше указывать минимальный набор документов, который вы собираетесь распознавать. Библиотека будет тратить меньше времени на поиск.

Заказать продукт

Для заказа решений, получения подробной информации или триал версий заполните приведенную ниже форму, и мы обязательно с Вами свяжемся.

    Array ( )