FAQ

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

В каждой поставке содержится один или несколько конфигурационных бандлов – архивов, содержащих все необходимое для конфигурации и функционирование системы Smart IDReader. Как правило, они имеют имя вида bundle_something.zip и находятся в директории data-zip.

Предположим, у вас уже созданы объекты 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) необходимо задать маску разрешенных типов документа. По умолчанию все типы документов отключены.

const vector<vector<string> > &supported_document_types = settings->GetSupportedDocumentTypes();

// settings->AddEnabledDocumentTypes("*");
settings->AddEnabledDocumentTypes("mrz.*");
// settings->AddEnabledDocumentTypes("card.*");
// settings->AddEnabledDocumentTypes("rus.passport.national");
// settings->AddEnabledDocumentTypes("usa.drvlic.*");

const std::vector<std::string> &enabled_doctypes = settings->GetEnabledDocumentTypes();

const std::vector<std::string> &available_modes = settings->GetAvailableModes();

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.

Smart IDReader SDK предоставляет Java-обертку внешнего интерфейса, автоматически сгенерированную на основе C++ интерфейса при помощи SWIG. Java-интерфейс аналогичен базовому C++-интерфейсу за исключением небольшого количества деталей (связанных, к примеру, с обертками интерфейсов STL-контейнеров). Для примера использования рекомендуется ознакомиться с sample-приложением.

Существует несколько тонкостей при использовании Java-интерфейса, связанных с управлением памятью.

RecognitionEngine engine = new RecognitionEngine(config_path); // или какой-то другой объект // ...engine.delete(); // форсирует деаллокацию памяти, выделенной в C++-коде

// НЕПРАВИЛЬНО: может привести к преждевременному удалению экземпляра класса 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-приложением.

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-приложением.