FAQ

В этом разделе мы приводим наиболее часто задаваемые вопросы про наши продукты и краткую инструкцию по использованию Smart IDReader SDK и его оберток. Если вашего вопроса нет в списке, то задайте нам его написав на support@smartengines.ru или позвонив по телефону +7 (495) 649 82 60.

Общие вопросы

  • Можно ли использовать ваши технологии распознавания на сервере?
     
    Да, наши решения можно использовать для распознавания фотографий и сканов документов на вашем сервере или непосредственно на рабочих местах ваших пользователей.
     
  • Можно ли реализовать распознавание через Интернет, предоставив клиенту возможность приложить фотографию или скан документа?
     
    Да, клиенты могут загружать на ваш сайт фотографии документов со своих ноутбуков, персональных компьютеров и мобильных телефонов. При этом после распознавания, извлеченные данные можно автоматически добавлять в заполняемые ими на сайте поля анкеты или других форм.
     
  • Можно ли распознавать фотографии, сделанные с помощью мобильного телефона?
     
    Да, наша технология умеет исправлять проективные искажения документов на фотографиях, обеспечивая высокое качество распознавания документов независимо от условий освещения и технических характеристик используемого для фотографирования устройства.
     
  • Можно ли распознавать ксерокопии документов низкого качества?
     
    Да, наши технологии позволяют распознавать ксерокопии документов даже низкого качества. Технологически возможность распознавания обеспечивается практически до того момента, пока документ может прочитать без ошибок человек.
     
  • Требуется ли вашей технологии распознавания связь с внешним миром (Интернет)?
     
    Нет, наши решения полностью автономны и обеспечивают безопасность работы с персональными данными, так как не создают копий и не передают данные на обработку через интернет. Это означает, что они всегда работают только на ВАШИХ устройствах (серверах, персональных компьютерах, мобильных телефонах и планшетах).
     
  • Что входит в комплект поставки вашего решения?
     
    В комплект поставки нашего решения для операционных систем «Аврора», Android, iOS, «Эльбрус», Linux, Windows, macOS входит SDK со стандартным набором оберток, документация и примеры интеграции.

Краткое руководство по Smart IDReader SDK

Ниже приведена краткая инструкция по использованию Smart IDReader SDK и его оберток. Если вы не нашли на этой странице нужную вам информацию, вы всегда можете обратиться за помощью по адресу support@smartengines.ru или к своему менеджеру по продажам.

  •   Базовая функциональность
  •   Руководство по использованию C++-интерфейса
       ○  Заголовочные файлы и пространства имен
       ○  Документация кода
       ○  Исключения
       ○  Создание объектов и владение памятью
  •   Конфигурационные бандлы
  •   Установка типов документов в Recognition Session
       ○  Поддерживаемые типы документов
       ○  Использование символа подстановки
       ○  Режимы
  •   Коллбеки
  •   Java-интерфейс
       ○  Деаллокация объектов
       ○  Область видимости структуры коллбеков
  •   C-интерфейс
       ○  Управление памятью
       ○  Коды возврата и тексты исключений
  •   PHP-интерфейс
  •   Python-интерфейс

БАЗОВАЯ ФУНКЦИОНАЛЬНОСТЬ

  1. Создайте экземпляр класса RecognitionEngine:
    se::smartid::RecognitionEngine engine(configuration_bundle_path);

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

    Подробнее о конфигурационных бандлах читайте в разделе Конфигурационные бандлы.

  2. Создайте объект SessionSettings соответствующим методом класса RecognitionEngine:
    std::unique_ptr<se::smartid::SessionSettings> settings(engine.CreateSessionSettings());

    Обратите внимание, что метод RecognitionEngine::CreateSessionSettings() возвращает указатель на новый аллоцированный объект, и вам будет необходимо его удалить самостоятельно.

  3. Влючите необходимые типы документов:
    settings->AddEnabledDocumentTypes("mrz.*");

    Подробнее о типах документов читайте в разделе Установка типов документов в Recognition Session.

  4. Установка дополнительных настроек сессии (опционально):
    // Установка таймаута сессии на 5 секунд
    settings->SetOption("common.sessionTimeout", "5.0");
  5. Создайте дочерний класс от ResultReporter для имплементации коллбеков (опционально):
    class ConcreteResultReporter : public se::smartid::ResultReporterInterface { /* callbacks */ }
    
    ConcreteResultReporter optional_reporter;

    Подробнее о коллбеках читайте в разделе Коллбеки.

  6. Создайте сессию распознавания (экземпляр RecognitionSession):
    unique_ptr<RecognitionSession> session(engine.SpawnSession(*settings, &optional_reporter));
  7. Для обработки изображения вызовите метод ProcessSnapshot(...), ProcessImageFile(...) или аналогичные:
    se::smartid::RecognitionResult result = session->ProcessImageFile(image_path);

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

  8. Используйте экземпляр 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 &current_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.

 
JAVA-ИНТЕРФЕЙС

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

 
C-ИНТЕРФЕЙС

Smart IDReader SDK предоставляет C-обертку для случаев, когда использование C++ невозможно. Для примера использования рекомендуется ознакомиться с sample-приложением.

Управление памятью

Поскольку в C нет конструкторов и деструкторов, для создания и удаления объектов используются пары функций Create/Destroy.

Коды возврата и тексты исключений

Поскольку в C нет исключений, каждая функция возвращает код ошибки типа int (нулевое значение означает выполнение без ошибок). Также в функции подается указатель CSmartIdErrorMessage * на буфер описания ошибки (содержащий текст исключения).

 
PHP-ИНТЕРФЕЙС

SmartIDReader SDK предоставляет PHP-обертку (поддерживаются версии 5.5, 5.6 и 7). Методы Image::CopyToBuffer и Image::CopyBase64toBuffer в PHP-обертке недоступны, вместо них можно пользоваться методом Image::GetBase64String. Остальная функциональность аналогично C++ и Java. Для примера использования рекомендуется ознакомиться с sample-приложением, для сборки обертночного модуля необходимо ознакомиться с README.txt в директории с sample-приложением.

 
PYTHON-ИНТЕРФЕЙС

Smart IDReader SDK предоставляет Python-обертку (поддерживаются версии Python 2.7+ и Python 3+), интерфейс аналогичен другим интерфейсам. Для примера использования рекомендуется ознакомиться с sample-приложением, для сборки обертночного модуля необходимо ознакомиться с README.txt в директории с sample-приложением.

Наши клиенты

Туту.ру

Туту.ру — онлайн-бронирование билетов с помощью технологий распознавания документов

Делимобиль

Делимобиль использует технологию распознавания Smart IDReader для удаленной верификации клиентов

Мегафон

В сети МегаФон оформляют сим-карты с помощью технологии распознавания Smart IDReader

QIWI

Smart IDReader интегрирован в мобильное приложение для агентов проекта «Совесть» (проект группы QIWI)

 

 

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