В этом разделе мы приводим наиболее часто задаваемые вопросы про наши продукты и краткую инструкцию по использованию Smart IDReader SDK и его оберток. Если вашего вопроса нет в списке, то задайте нам его написав на [email protected] или позвонив по телефону +7 (495) 649 82 60.
Ниже приведена краткая инструкция по использованию Smart IDReader SDK и его оберток. Если вы не нашли на этой странице нужную вам информацию, вы всегда можете обратиться за помощью по адресу [email protected] или к своему менеджеру по продажам.
• Базовая функциональность
• Руководство по использованию C++-интерфейса
○ Заголовочные файлы и пространства имен
○ Документация кода
○ Исключения
○ Создание объектов и владение памятью
• Конфигурационные бандлы
• Установка типов документов в Recognition Session
○ Поддерживаемые типы документов
○ Использование символа подстановки
○ Режимы
• Коллбеки
• Java-интерфейс
○ Деаллокация объектов
○ Область видимости структуры коллбеков
• C-интерфейс
○ Управление памятью
○ Коды возврата и тексты исключений
• PHP-интерфейс
• Python-интерфейс
RecognitionEngine
:
se::smartid::RecognitionEngine engine(configuration_bundle_path);
Процесс конфигурирования класса RecognitionEngine
может занять некоротое время, но это нужно делать только один раз за срок жизни программы. Созданный экземпляр Recogition Engine
в дальнейшем используется для создания легковесных объектов типа RecognitionSession
, который уже в свою очередь используется для обработки изображений документов.
Подробнее о конфигурационных бандлах читайте в разделе Конфигурационные бандлы.
SessionSettings
соответствующим методом класса RecognitionEngine
:
std::unique_ptr<se::smartid::SessionSettings> settings(engine.CreateSessionSettings());
Обратите внимание, что метод RecognitionEngine::CreateSessionSettings()
возвращает указатель на новый аллоцированный объект, и вам будет необходимо его удалить самостоятельно.
settings->AddEnabledDocumentTypes("mrz.*");
Подробнее о типах документов читайте в разделе Установка типов документов в Recognition Session.
// Установка таймаута сессии на 5 секунд
settings->SetOption("common.sessionTimeout", "5.0");
ResultReporter
для имплементации коллбеков (опционально):
class ConcreteResultReporter : public se::smartid::ResultReporterInterface { /* callbacks */ }
ConcreteResultReporter optional_reporter;
Подробнее о коллбеках читайте в разделе Коллбеки.
RecognitionSession
):
unique_ptr<RecognitionSession> session(engine.SpawnSession(*settings, &optional_reporter));
ProcessSnapshot(...)
, ProcessImageFile(...)
или аналогичные:
se::smartid::RecognitionResult result = session->ProcessImageFile(image_path);
При работе с видеопотоком вам необходимо подавать кадры один за другим, до тех пор, пока полученный результат не будет содержать поля result.IsTerminal()
со значением true
.
RecognitionResult
для получения результатов распознавания полей:
for (const std::string &field_name : result.GetStringFieldNames()) {
const se::smartid::StringField &string_field = result.GetStringField(field_name);
bool is_accepted = string_field.IsAccepted();
std::string field_value = string_field.GetUtf8Value();
}
Помимо строковых полей также можно получить значение полей-изображений:
for (const std::string &field_name : result.GetImageFieldNames()) {
const se::smartid::ImageField &image_field = result.GetImageField(field_name);
const se::smartid::Image &image = image_field.GetValue();
}
РУКОВОДСТВО ПО ИСПОЛЬЗОВАНИЮ C++-ИНТЕРФЕЙСА
Заголовочные файлы и пространства имен
Основные заголовочные файлы C++-интерфейса:
#include <smartIdEngine/smartid_engine.h> // Все вместе
#include <smartIdEngine/smartid_common.h> // Вспомогательные классы
#include <smartIdEngine/smartid_result.h> // Классы, связанные с получением результата распознавания
C++ интерфейс Smart IDReader SDK заключен в пространстве имен se::smartid
.
Все С++ классы и методы содержат полезную документацию в заголовочных файлах, в формате Doxygen. Дополнительная документация находится в директории doc
в каждом SDK-пакете. Сэмпл-приложения и скрипты для их сборки можно найти в директории samples
в каждом SDK-пакете.
С++ классы Smart IDReader SDK используют исключения типа std::exception
в случае, если пользователь передает некорректные входные данные, или если происходит какая-то иная ошибка. Большинство исключений содержат в своем тексте полезную информацию — пожалуйста, обращайте внимание на содержимое e.what()
.
Создание объектов и владение памятью
У некоторых классов Smart IDReader SDK есть фабричные методы, которые возвращают указатели на созданные в куче объекты. Вызывающий должен удалять эти объекты самостоятельно. Рекомендуется использовать std::unique_ptr<T>
для управления памятью и уменьшения риска утечки памяти.
В каждой поставке содержится один или несколько конфигурационных бандлов — архивов, содержащих все необходимое для конфигурации и функционирование системы Smart IDReader. Как правило, они имеют имя вида bundle_something.zip
и находятся в директории data-zip
.
УСТАНОВКА ТИПОВ ДОКУМЕНТОВ В RECOGNITION SESSION
Предположим, у вас уже созданы объекты RecognitionEngine
и SessionSettings
:
// Создание экземпляра RecognitionEngine с путем к конфигурационному файлу
se::smartid::RecognitionEngine engine(configuration_bundle_path);
// Создание экземпляра SessionSettings
std::unique_ptr<se::smartid::SessionSettings> settings(engine.CreateSessionSettings());
Для вызова engine.SpawnSession(settings, optional_reporter)
необходимо задать маску разрешенных типов документа. По умолчанию все типы документов отключены.
Поддерживаемые типы документов
Тип документа является просто строковым идентификатором. Примеры типов документа: rus.passport.national
или mrz.mrp
. Доступные типы документов, включенные в предоставленный вам конфигурационный пакет, могут быть получены методом GetSupportedDocumentTypes()
:
const vector<vector<string> > &supported_document_types = settings->GetSupportedDocumentTypes();
Возвращаемое значение — двумерный вектор. В рамках одной сессии можно включить одновременно только те документы, которые сгруппированы в один и тот же вектор vector<string>
нижнего уровня.
Использование символа подстановки
Поскольку по умолчанию все типы документов отключены, для создания сессии нужные документы необходимо включить. Сделать это можно при помощи методов AddEnabledDocumentTypes(string)
или SetEnabledDocumentTypes(vector<string>)
класса SessionSettings
:
// settings->AddEnabledDocumentTypes("*");
settings->AddEnabledDocumentTypes("mrz.*");
// settings->AddEnabledDocumentTypes("card.*");
// settings->AddEnabledDocumentTypes("rus.passport.national");
// settings->AddEnabledDocumentTypes("usa.drvlic.*");
Также вы можете использовать метод RemoveEnabledDocumentTypes(string)
для отключения уже включенных типов.
Для удобства вы можете использовать символ подстановки (звездочку) при включении и отключении типов документов. При использовании символа подстановки все доступные в конфигурации типы документов проверяются на соответствие предоставленному шаблону, и, в случае совпадения, включаются (или отключаются). К приеру, тип документа rus.passport.national
будет соответствовать маскам rus.*
, *passport*
и, конечно, просто символу подстановки *
.
Для того, чтобы получить список включенных в данный момент типов документа вы можете использовать соответствующий метод класса SessionSettings
:
const std::vector<std::string> &enabled_doctypes = settings->GetEnabledDocumentTypes();
Как было упомянуто ранее, в рамках одной сессии вы можете включить только типы документов, принадлежащих одному списку vector<string>
из структуры поддерживаемых типов. В противном случае при создании сессии engine.SpawnSession(...)
будет сгенерировано соответствующее исключение.
Как правило, если вам заранее известен тип распознаваемого документа, сессию лучше создавать с минимальным количеством включенных типов.
По типам документам, доступным в предоставленной конфигурации, и по указанным маскам включенных типов документов, RecognitionEngine
при создании сессии выбирает, какую внутреннюю конфигурацию («внутренний движок») использовать. Однако, в некоторых конфигурациях может быть несколько внутренних движков, которые могут поддерживать один и тот же тип документа. К примеру, паспорт США (usa.passport.*
) может поддерживаться как во внутреннем движке распознавания документов США, так и в движке, который предоставляет функциональность распознавания всех международных паспортов. Для того, чтобы избавиться от этой неопределенности, существует понятие режимов (modes).
Для получения списка доступных режимов вы можете использовать соответствующий метод SessionSettings
:
const std::vector<std::string> &available_modes = settings->GetAvailableModes();
Во всех конфигурациях присутствует режим default
, и он всегда активен по умолчанию. У класса SessionSettings
существуют методы для получения текущего режима и для установки нового:
const std::string ¤t_mode = settings->GetCurrentMode();
// Установка текущего режима на AnyPassport
settings->SetCurrentMode("anypassport");
// Включение маски документов _в рамках текущего режима_
settings->AddEnabledDocumentTypes("*");
Во всех конфигурациях сохраняется строгий инвариант: все внутренние движки с одним и тем же режимом не пересекаются по типам поддерживаемых документов.
Smart IDReader SDK поддерживает вызов опциональных коллбеков при анализе документа и в процессе распознавания, до того, как метод ProcessSnapshot(...)
или его аналог завершил свою работу. Это позволяет пользователю получать более свежую информацию о процессе распознавания и получать графический фидбек.
Для использования коллбеков вам необходимо создать класс, наследующийся от ResultReporterInterface
и имплементировать соответствующие методы:
class ConcreteResultReporter : public se::smartid::ResultReporterInterface {
public:
virtual void SnapshotRejected() override { }
virtual void DocumentMatched(vector<MatchResult> &match_results) override { }
virtual void DocumentSegmented(const vector<SegmentationResult> &segmentation_results) override { }
virtual void SnapshotProcessed(const RecognitionResult &recog_result) override { }
virtual void SessionEnded() override { }
};
Методы DocumentMatched(...)
и DocumentSegmented(...)
предназначены специально для возврата координат документа, его зон и полей, для использования при графической визуализации процесса распознавания в видеопотоке.
Указатель на экземпляр класса ConcreteResultReporter
необходимо подавать в метод создания сессии:
ConcreteResultReporter reporter;
unique_ptr<RecognitionSession> session(engine.SpawnSession(*settings, &reporter));
Важно! Экземпляр класса, наследуемого от ResultReporterInterface
, нельзя удалять до конца жизни объекта RecognitionSession
.
Smart IDReader SDK предоставляет Java-обертку внешнего интерфейса, автоматически сгенерированную на основе C++ интерфейса при помощи SWIG. Java-интерфейс аналогичен базовому C++-интерфейсу за исключением небольшого количества деталей (связанных, к примеру, с обертками интерфейсов STL-контейнеров). Для примера использования рекомендуется ознакомиться с sample-приложением.
Существует несколько тонкостей при использовании Java-интерфейса, связанных с управлением памятью.
Поскольку обернутые объекты владеют памятью, выделенной на native-куче (и их размер не известен сборщику мусора Java), для объектов типа RecognitionEngine
, RecognitionSession
, SessionSettings
и RecognitionResult
рекомендуется вручную вызывать метод obj.delete()
после использования.
RecognitionEngine engine = new RecognitionEngine(config_path); // или какой-то другой объект
// ...
engine.delete(); // форсирует деаллокацию памяти, выделенной в C++-коде
Это важно, поскольку с точки зрения сборщика мусора эти объекты занимают всего несколько байт в Java-куче, когда их настоящая занимаемая память может исчисляться десятками мегабайт. Это делает поведение сборщика мусора непредсказуемым.
Область видимости структуры коллбеков
При использовании коллбеков убедитесь, что экземпляр класса находится в той же области работы сборщика мусора, что и RecognitionSession. Оберточный класс не владет указателем на наследованный класс коллбеков, что может привести к его удалению сборщиком мусора еще до то того, как закончится сессия распознавания.
// НЕПРАВИЛЬНО: может привести к преждевременному удалению экземпляра класса MyResultReporter
class MyDocumentRecognizer {
private RecognitionEngine engine;
private RecognitionSession session;
private void InitializeSmartIdReader() {
// ...
session = engine.SpawnSession(settings, new MyResultReporter());
// reporter может быть удален, поскольку сессия им не владеет
}
}
// ПРАВИЛЬНО: reporter будет удален вместе с session
class MyDocumentRecognizer {
private RecognitionEngine engine;
private RecognitionSession session;
private MyResultReporter reporter;
private void InitializeSmartIdReader() {
// ...
reporter = new MyResultReporter();
session = engine.SpawnSession(settings, reporter);
}
}
Smart IDReader SDK предоставляет C-обертку для случаев, когда использование C++ невозможно. Для примера использования рекомендуется ознакомиться с sample-приложением.
Поскольку в C нет конструкторов и деструкторов, для создания и удаления объектов используются пары функций Create/Destroy.
Коды возврата и тексты исключений
Поскольку в C нет исключений, каждая функция возвращает код ошибки типа int
(нулевое значение означает выполнение без ошибок). Также в функции подается указатель CSmartIdErrorMessage *
на буфер описания ошибки (содержащий текст исключения).
SmartIDReader SDK предоставляет PHP-обертку (поддерживаются версии 5.5, 5.6 и 7). Методы Image::CopyToBuffer
и Image::CopyBase64toBuffer
в PHP-обертке недоступны, вместо них можно пользоваться методом Image::GetBase64String
. Остальная функциональность аналогично C++ и Java. Для примера использования рекомендуется ознакомиться с sample-приложением, для сборки обертночного модуля необходимо ознакомиться с README.txt
в директории с sample-приложением.
Smart IDReader SDK предоставляет Python-обертку (поддерживаются версии Python 2.7+ и Python 3+), интерфейс аналогичен другим интерфейсам. Для примера использования рекомендуется ознакомиться с sample-приложением, для сборки обертночного модуля необходимо ознакомиться с README.txt
в директории с sample-приложением.
Новости
12.04.2022 07.04.2022Владимир Арлазаров дал интервью изданию «Москва Меняется»
01.04.2022Smart Engines в гостях на Открытом эфире Kommersant по кибербезопасности
Все новости
Билайн
Билайн использует технологии Smart Engines для распознавания и проверки документов
Vodafone Qatar
Vodafone Qatar использует технологии Smart Engines для сканирования ID документов Катара
МКБ
МКБ распознает клиентские данные с помощью искусственного интеллекта от Smart Engines
МТС
В терминалах выдачи сим-карт МТС используются технологии Smart Engines
Заказать продукт
Для заказа решений, получения подробной информации или триал версий заполните приведенную ниже форму, и мы обязательно с Вами свяжемся.