Документация по Smart ID Engine SDK

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

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

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

Создание движка распознавания.
Создание сессии распознавания.
Настройка сессии распознавания.
Создание объекта изображения документа Image.
Процесс распознавания.
Разбор результата распознавания.
Освобождение памяти.

Создание движка распознавания

Из Описания системы:

Движок распознавания — это объект, в котором хранятся и инициализируются все инструменты распознавания. Он создается на основе конфигурационного бандла, содержащего все возможные настройки: список документов, поддерживаемых конкретным SDK, их полей, список возможных проверок подлинности и так далее.

Примечание.

В особых случаях бандл может поставляться не отдельно, а в составе (внутри) библиотеки.

При создании данного объекта обычно указывается способ инициализации и путь до бандла (если он поставляется отдельно).

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

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

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

C++Java

C++

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

Java

import com.smartengines.id.*;

try {
    // load library
    System.loadLibrary("jniidengine");
    IdEngine instance = IdEngine.Create(configuration_bundle_path, true); 
} catch (Exception e) {
    Log.e("SMARTENGINES", e.getMessage());
}

Параметры:

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

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

Внимание!

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

Создание сессии распознавания

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

Из Описания системы:

Настройки сессии — это объект, в котором хранится:

список поддерживаемых документов для распознавания, сгруппированных по внутренним движкам. Их состав задается в конфигурационном бандле, с которым был создан движок (только чтение);
список документов, переданных на распознавание (по умолчанию — *);
специальные опции сессии: количество потоков для распознавания и прочее. Полный список можно найти в документации.

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

C++Java

C++

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

Java

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

Внимание!

IdEngine::CreateSessionSettings() является фабричным методом и и возвращает указатель на выделенный в памяти и инициализированный объект. За удаление этого объекта ответственен вызывающий.

Включение типов документов

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

Каждый тип документа, передаваемый системе, сопоставляется со всеми поддерживаемыми типами. Если определённый тип поддерживается, он добавляется в список распознаваемых документов.

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

C++Java

C++

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

Java

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

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

Рекомендация.

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

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

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

C++Java

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

Режим (Mode)

Из Описания системы:

Для Smart ID Engine:

расширенная информация о документах в том числе ссылки на PRADO (только чтение и только для Smart ID Engine);
список ожидаемых полей для распознавания (по умолчанию все);
список наборов документов (Параметр mode. По умолчанию — default);

Внутренние движки — это группы документов, организованные таким образом, чтобы алгоритм их поиска и распознавания работал максимально эффективно.

Список документов для распознавания формируется в рамках конфигурационного бандла. Внутри него документы могут быть сгруппированы, например, в следующие внутренние движки:

все документы одной страны;
паспорта всех стран;
все документы, удостоверяющие личность, стран СНГ и так далее.

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

Для решения этой проблемы каждый внутренний движок имеет параметр "режим" (mode). Указав этот параметр вместе со списком ожидаемых для распознавания документов, вы сможете успешно создать сессию.

Внимание!

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

Данные о внутренних движках, их составе и режимах содержатся в настройках сессии, а также в документации к каждому конкретному SDK.

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

C++Java

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++Java

C++

std::string current_mode = settings->GetCurrentMode();
// Устанавливает режим AnyPassport
settings->SetCurrentMode("anypassport");

Java

String current_mode = settings.GetCurrentMode();
// Устанавливает режим  AnyPassport
settings.SetCurrentMode("anypassport");

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

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

singleshot - можно использовать режим для распознавания одного кадра. В мобильных сборках рекомендуется применять его для распознавания изображений из галереи.

Режим singleshot можно использовать также для any режимов, например anydoc-singleshot или anypassport-singleshot. Режим singleshot более требователен к ресурсам, но более устойчив к различным немобильным вариантам использования.

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

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

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

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

C++Java

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++Java

C++

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

Java


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

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

Из Описания системы:

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

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

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

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

C++Java

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

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

Из Описания системы:

Для работы распознавания системе необходимо передать изображение специального класса se.common.image. Создать его можно из следующих форматов:

Поддерживаемые форматы:

jpeg, png;
tiff (✔️TIFF_LZW, ✔️TIFF_PACKBITS,✔️TIFF_CCITT);
base64 (форматы из пунктов выше);
файловый буфер с предварительным указанием цветовой схемы, ширины\высоты\количества каналов.

Максимально допустимый размер изображения по умолчанию 15000x15000px. Предельный размер изображения может быть увеличен пользователем.

Работа с HEIC

Работа с HEIC в мобильных SDK не отличается от работы с другими форматами изображений. Чтение HEIC осуществляется системными средствами.

В серверных SDK необходимо самостоятельно открыть HEIC формат сторонними средствами и конвертировать либо в один из поддерживаемых нами форматов, либо передать непосредственно сырые пиксели в виде RGB буфера (рекомендуется).

Работа с PDF

PDF с предварительной конвертацией в растровые форматы. По запросу клиента Smart Engines предоставляет такой конвертер под выбранную архитектуру.

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

C++Java

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

Справка

Для передачи любых изображений в движок необходим объект класса se.common.Image.

Список актуальных методов:

Image.FromFile(imagePath) — принимает локальный путь к файлу;
Image.FromFileBuffer(data) — принимает прочитанный в буфер файл;
Image.FromBase64Buffer(data) — принимает прочитанный в буфер файл, обернутый в base64;
Image.FromBufferExtended(raw_data, width, height, stride, pixel_format, bytes_per_channel) — эффективный способ создать объект Image из сырых пикселей;
Image.FromYUV(planeY, planeU, planeV, yuvDimensions) — позволяет создать Image из YUV_420_888.

Внимание!

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

Процесс распознавания

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

C++Java

C++

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

Java

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

Для работы с видео потоком следует передавать серию изображений в цикле:

Выход из цикла осуществляется автоматически благодаря механизму терминальности.

Из Описания системы:

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

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

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

Терминальность — автоматическая остановка процесса распознавания в видеопотоке. Принимает значение true в двух случаях:

добавление новых кадров не приведёт к изменению результата распознавания;
исчерпалось ограничение времени сессии, заданное в настройках.

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

Внимание!

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

Разбор результата распознавания

Из Описания системы:

Результат распознавания — это объект интерфейса, содержащий всю доступную информацию о результате работы системы распознавания. Каждый параметр выводится с помощью отдельного метода, что позволяет при встраивании оперировать только необходимыми данными. Состав полей в объекте зависит от типа сессии, в которой выполнялось распознавание, а тип сессии зависит от функционала используемого продукта.

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

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

C++Java

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
}

// Изображения
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 (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
}

// Изображения
for (IdImageFieldsMapIterator it = result.ImageFieldsBegin();
    !it.Equals(result.ImageFieldsEnd());
     it.Advance()) {
    IdImageField field = it.GetValue();

    Image image = field.GetValue();
}

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

Для анализа промежуточных результатов распознавания рекомендуется использовать метод result.GetTemplateDetectionResulsCount(), поскольку он позволяет определить наличие документа в текущем кадре.

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

Из Описания системы:

Распознавание в видеопотоке — это сложный и зачастую не мгновенный процесс, который требует взаимодействия с пользователем. Предоставляя информацию о ходе распознавания на экране в процессе работы, мы помогаем пользователю лучше понять этапы функционирования системы. Именно поэтому технологии машинного зрения часто дополняются элементами дополненной реальности, что улучшает пользовательский опыт и делает взаимодействие более интуитивным.

В объекте результата распознавания находится информация о координатах четырехугольника шаблона документа (границы документа) и координаты четырехугольников шаблонов полей документа. По этим координатам, например, можно отрисовать границы найденного документа на экране с превью камеры.

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

C++Java

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++Java

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

Освобождение памяти

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

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

Java

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

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

Рекомендации.

в C++:
Для простоты управления памятью и предотвращения ее утечек пользуйтесь умными указателями std::unique_ptr<T> или std::shared_ptr<T>.
в Java API:
Удаляйте ненужные объекты с помощью метода .delete().

Особенности JNI интерфейса

Следует иметь ввиду особенности интеграции с Java.

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

Внимание

Java Native Interface (JNI) — стандартный механизм для запуска кода под управлением Java, который написан на языках C/C++ и скомпонован в виде динамических библиотек.

Любой объект, возвращаемый функцией JNI (это все методы нашей обертки), является локальной ссылкой, которая действительна в течении всего времени собственного метода в текущем потоке. При этом наш движок продолжает существовать глобально.

При неправильном использовании методов обертки с большой вероятностью вы будете получать Null Pointer Exception в разные моменты времени работы приложения. Семпл в нашем SDK следует правилам использования JNI функций.

Подробнее о работе с JNI: https://developer.android.com/training/articles/perf-jni#java

При использовании вспомогательного объекта обратной связи с помощью подкласса 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);  
    }
}

Интерфейс библиотеки

Общие классы

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

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

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

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

Java

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

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

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

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

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

Java


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

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

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.
Тип исключения включен в текст сообщения.

Сравнение лиц

Сравнение (определение схожести) лиц на изображениях функционирует в двух режимах:

"Одно к одному" — сравнение двух изображений лица.
"Одно ко многим" — поочередное сравнение нескольких изображений с одним (опорным).

Жизненный цикл функционала сравнения лиц

Создайте экземпляр IdEngine или воспользуйтесь уже созданным:

C++Java

	std::unique_ptr<se::id::IdEngine> engine(se::id::IdEngine::Create(face_config_path.c_str()));

Создайте объект IdFaceSessionSettings на основе сконфигурированного экземпляра IdEngine:
cpp
```
// C++
id_face_settings_.reset(engine->CreateFaceSessionSettings());
```

Внимание!

IdEngine::CreateFaceSessionSettings() является фабричным методом и и возвращает указатель на выделенный в памяти и инициализированный объект. За удаление этого объекта ответственен вызывающий.

Инициализируйте IdFaceSession:

cpp

// C++
const char* signature = "... ПОДПИСЬ ...";
id_face_session_.reset(engine->SpawnFaceSession(*id_face_settings_, signature));

Загрузите изображения лиц в систему:

cpp

// C++
std::unique_ptr<se::common::Image> imageA(
    se::common::Image::FromFile(image_pathA)); // Загрузка изображения A

std::unique_ptr<se::common::Image> imageB(
    se::common::Image::FromFile(image_pathB)); // Загрузка изображения B

При работе в режиме "одно ко многим" можно загрузить любое количество лиц.

Следующие шаги зависят от режима, в котором вы работаете.

В режиме "одно к одному":

Сравните два изображения (А и B) с помощью метода GetSimilarity():
cpp
```
// C++
double face_sim = face_session->GetSimilarity(*imageA, *imageB).GetSimilarityEstimation();
```

Данный метод определяет степень схожести двух изображений лиц.

В режиме "одно ко многим":

Из загруженных изображений выберите опорное (A) с помощью метода SetFaceToMatchWith():
cpp
```
// C++
face_session->SetFaceToMatchWith(*imageA); // Назначение жизбражения image A опорным
```
Сравните другие загруженные изображения (B, C и т.д) с опорным (A) с помощью метода GetSimilarityWith():
cpp
```
// C++
double face_sim_A_B = face_session->GetSimilarityWith(*imageB).GetSimilarityEstimation();
double face_sim_A_C = face_session->GetSimilarityWith(*imageC).GetSimilarityEstimation();
.....
```
Данный метод определяет степень схожести переданных изображений с опорным.

Рекомендация.

Если необходимо сравнить несколько изображений с одним, то для большей эффективности рекомендуется пользоваться режимом "одно ко многим". Данный режим более эффективен в таких случаях.

Результат определения схожести лиц

Используются следующие классы:

IdFaceSimilarity — описывает процесс и результат проверки схожести лиц на изображениях. Содержит методы:

GetSimilarity() и GetSimilarityWith() — возвращают одно из трех значений: different, uncertain, same. Рекомендуется пользоваться данными методами.
GetSimilarityEstimation() — возвращает десятичную дробь от 0.0 до 1.0, обозначающее степень сходства изображений. Занчение 1.0 указывает на 100% схожесть найденных лиц, 0.0 — что лица абсолюто разные.

IdFaceStatus — статус обработки входных изображений. Содержит методы:

GetStatus() — возвращает статус обработки изображений. Если лицо не найдено на обоих изображениях, система считает, что лица разные, и сравнение завершается.

Журнал

// Possible status values:
// IdFaceStatus_NotUsed,            ///< Движок не инициализирован
// IdFaceStatus_Success,            ///< Движок инициализирован, сравнение лиц успешно заврешено
// IdFaceStatus_A_FaceNotFound,     ///< Не найдено лицо на изображении A
// IdFaceStatus_B_FaceNotFound,     ///< Не найдено лицо на изображении B
// IdFaceStatus_FaceNotFound,       ///< Не найдено лицо на обоих изображениях (A и B) (для режима "одно к одному")
// IdFaceStatus_NoAccumulatedResult ///< Не установлено опорное изображение (для режима "одно ко многим")

IdFaceStatus_A_FaceNotFound, IdFaceStatus_B_FaceNotFound, IdFaceStatus_FaceNotFound — не найдено лицо на одном или обоих изображениях. Сравнение завершено.
IdFaceStatus_Success — найдены лица на обоих изображения (для режима "одно к одному").
IdFaceStatus_NoAccumulatedResult — не найдено опорное лицо (для режима "одно ко многим").

Определение живости лиц

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

Создайте сессию с помощью метода CreateFaceSessionSettings() класса IdFaceSessionSettings:

cpp

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

Задайте параметры сесси с помощью метода:

cpp

// C++
session_settings->SetOption(key, value);

где: key — имя параметра,value — значение параметра.

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

initializerInstructionTime – максимальное время прохождения первой инструкции (в миллисекундах);
faceMinInstructionTime – минимальное время прохождения одной инструкции (в миллисекундах);
faceMaxInstructionTime – максимальное время прохождения одной инструкции (в миллисекундах);
minPassTime – минимальная задержка переключения инструкций (в миллисекундах);
instructionsCountBase – количество инструкций, необходимое для прохождения проверки;
instructionsCountDeltaRandom – максимальное количество инструкций для оклонения от базового (значения параметра instructionsCountBase). С помощью значений параметров instructionsCountBase и instructionsCountDeltaRandom задаются верхнее и нижнее значения диапазона, в который входит количество инструкций. Например, если значение параметра instructionsCountBase равно 7, а значение параметра instructionsCountDeltaRandom равно 2, то количестиво инструкций является произвольным целым числом в диапазоне [5, 9];
allowedNumberOfFailedInstructions – допустимое количество непройденных инструкций.

Например:

cpp

// C++
std::unique_ptr<se::id::IdFaceSessionSettings> session_settings(engine->CreateFaceSessionSettings());
session_settings.SetOption("initializerInstructionTime", "7000"); // установка максимального времи прохождения первой инструкции — 7000 миллисекунд.
session_settings.SetOption("faceMinInstructionTime", "6000"); // установка минимального времи прохождения одной инструкции — 6000 миллисекунд.
session_settings.SetOption("faceMaxInstructionTime", "8000"); // установка максимального времи прохождения одной инструкции — 8000 миллисекунд.
session_settings.SetOption("minPassTime", "6000"); // установка задержки переключения инструкций — 6000 миллисекунд.
session_settings.SetOption("instructionsCountBase", "7"); // установка количества инструкций, необходимого для прохождения проверки — 7 инструкций.
session_settings.SetOption("instructionsCountDeltaRandom", "2"); // установка максимального количества инструкций для оклонения от базового — 2 инструкции.
session_settings.SetOption("allowedNumberOfFailedInstructions", "1"); // установка допустимого количества непройденных инструкций — 1 инструкция.

Создайте сессию — основной объект для проверки живости лица:

cpp

// C++
std::unique_ptr<se::id::IdFaceSession> session(engine->SpawnFaceSession(*settings, ${put_yor_personalized_signature_from_doc_README.html}, &optional_feedback));

Создайте объект, описывающий результат проверки живости лица:

cpp

// C++
se::id::IdFaceLivenessResult liveness_result;

Пройдитесь по всем изображениям и передайте их в сессию:

cpp

// C++
 for (int i = 0; i < number_of_images; ++i) {
        std::unique_ptr<se::common::Image> image(se::common::Image::FromFile(lst_path.c_str(), i));
		session->AddFaceImage(*image);
 }

Получите инструкцию:

cpp

// C++
session->GetLivenessResult().GetLivenessInstruction();

Обновите результат проверки:

cpp

// C++
liveness_result = session->GetLivenessResult();

Если возвращаемое значение метода GetLivenessInstruction() "CT" (Complete — завершено):

cpp

// C++
liveness_result.GetLivenessInstruction() == "CT"

то получите оценку полученного результат:

cpp

// C++
std::string result = (liveness_result.GetLivenessEstimation() == 1.00000) ? "Liveness detected" : "Liveness undetected";

Обработайте обратную связь — опционально:

cpp

// C++
class OptionalFeedback : public se::id::IdFaceFeedback {
public:
	virtual ~OptionalFeedback() override = default;
public:
  virtual void MessageReceived(
      const char* message) override {
    printf("[Face feedback called]: %s\n", message);
  }
};

Особенности интеграции REST-API сервера и 1C

Взаимодействие REST-API сервера Smart IdEngine и 1С (как и с другими ERP-системами) осуществляется посредством http-запросов. Для интеграции REST-API сервера и 1C установка каких-либо компонентов на стороне 1C не требуется.

REST-API сервер по умолчанию слушает порт на всех доступных сетевых интерфейсах. Если сервер и система 1C установлены на одном ПК, то для обращения к серверу следует использовать локальный адрес данного ПК. Если он размещается на другом ПК сети, то следует использовать внешний IP-адрес этого ПК.

В случае работы сервера в небезопасных сетях (без VPN), необходимо использовать шифрование http-трафика. В качестве proxy-сервера рекомендуется использовать NGINX.

Конфигурация сервера, то есть политика прослушивания сетевых интерфейсов, и номер порта задаются в файле config.json.

Возможны два способа распознавания документов с использованием API:

Простое распознавание — документ и настройки сессии отправляются в одном запросе. Задача обрабатывается за один запрос.
Сессионное распознавание — пользователь создает сессию и отправляет множество изображений на распознавания в рамках одного ID сессии. Это могут быть многостраничные документы или серия изображений одного документа.

Настройки параметров распознавания включают в себя:

mode — режим работы. Обычно, default.
mask — маска документа. Явный или неявный тип документа, который необходимо распознать.

Пример: default:rus.passport.national.

Как начать распознавание Выполните в Swagger первый POST запрос на простой URL, прикрепив изображение. Если в ответ вы получите ошибку с описанием "Found no single engine that supports document types enabled in settings" это означает, что конфигурация вашего REST API сервера содержит несколько режимов распознавания с маской *. Сервер не смог определить, какой движок распознавания выбрать по маске документа *.

Выполните запрос к diagnostic и проверьте содержимое bundle_masks. Вы увидите, что документы сгруппированы по режимам (":" — разделение режима и маски). Подробно см. Включение типов документов.

Распознавание PDF

PDF поддерживается для распознавания серверными SDK. Поддержка PDF реализована посредством предварительного преобразования документов PDF в растровые изображения (например, PNG).

Преобразование PDF в растровые изображения может выполняться с помощью библиотеки с открытым исходным кодом PDFium через утилиту командной строки pdfium_cli.

Утилита преобразования PDF предоставляется по запросу, чтобы уменьшить размер дистрибутива SDK.

По запросу клиента может быть предоставлена готовая к использованию утилита преобразования PDF в растровые изображения для конкретной целевой архитектуры.

Параметр	Описание	По умолчанию
-i, --input	Путь к входному файлу PDF	—
-o, --output	Каталог вывода	`result`
-p, --prefix	Префикс имени файла для выходных файлов	`page_`
-d, --dpi	Разрешение рендеринга в DPI	`300`
-r, --pages	Диапазон страниц для рендеринга, например «1-3,5,7» или «all»	`all`
-g, --grayscale	Рендеринг страниц в оттенках серого (меньший размер файла PNG)	—
-h, --help	Вывести сообщение справки	—

Примеры:

shell

./pdfium_cli -i file.pdf

shell

./pdfium_cli -i file.pdf -o out -d 150 -r 1-5

Документация по Smart ID Engine SDK ​

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

Создание движка распознавания ​

Создание сессии распознавания ​

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

Включение типов документов ​

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

Режим (Mode) ​

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

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

Создание объекта Image ​

Процесс распознавания ​

Разбор результата распознавания ​

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

Освобождение памяти ​

Особенности JNI интерфейса ​

Интерфейс библиотеки ​

Общие классы ​

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

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

Сравнение лиц ​

Жизненный цикл функционала сравнения лиц ​

Результат определения схожести лиц ​

Определение живости лиц ​

Особенности интеграции REST-API сервера и 1C ​

Распознавание PDF ​

Документация по Smart ID Engine SDK

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

Создание движка распознавания

Создание сессии распознавания

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

Включение типов документов

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

Режим (Mode)

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

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

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

Процесс распознавания

Разбор результата распознавания

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

Освобождение памяти

Особенности JNI интерфейса

Интерфейс библиотеки

Общие классы

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

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

Сравнение лиц

Жизненный цикл функционала сравнения лиц

Результат определения схожести лиц

Определение живости лиц

Особенности интеграции REST-API сервера и 1C

Распознавание PDF