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

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

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

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

1. Создание движка распознавания.
2. Создание сессии распознавания.
3. Настройка сессии распознавания.
4. Создание объекта изображения (Image).
5. Процесс распознавания.
6. Разбор результата распознавания.
7. Освобождение памяти.

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

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

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

Примечание.

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

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

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

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

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

C++

std::unique_ptr<se::doc::DocEngine> engine(se::doc::DocEngine::Create(  
    configuration_bundle_path));

Java

import com.smartengines.doc.*  
DocEngine engine = DocEngine.Create(configuration_bundle_path);

Параметры:

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

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

Внимание!

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

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

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

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

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

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

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

C++

std::unique_ptr<se::doc::DocSessionSettings> settings(engine->CreateSessionSettings());

Java

import com.smartengines.doc.*  
DocSessionSettings settings = engine.CreateSessionSettings();

Внимание!

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

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

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

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

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

C++

settings->AddEnabledDocumentTypes("rus.2ndfl.*"); // Задает распознавание 2-НДФЛ

Java

settings.AddEnabledDocumentTypes("rus.2ndfl.*"); // Задает распознавание 2-НДФЛ

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

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

C++

// Прохождение по циклу найденных внутренних движков  
for (int i_engine = 0;  
     i_engine < settings->GetInternalEnginesCount();  
     ++i_engine) {  
    // Прохождение по циклу типов документов, поддерживаемых данным внутренним движком  
    for (int i_doc = 0;  
         i_doc < settings->GetSupportedDocumentTypesCount(i_engine);  
         ++i_doc) {  
        // Получение имени типа поддерживаемого документа   
        std::string doctype = settings->GetSupportedDocumentType(i_engine, i_doc);  
    }  
}

Java

// Прохождение по циклу внутренних движков  
for (int i_engine = 0;  
     i_engine < settings.GetInternalEnginesCount();  
     i_engine++) {  
    // Прохождение по циклу типов документов, поддерживаемых данным внутренним движком   
    for (int i_doc = 0;  
         i_doc < settings.GetSupportedDocumentTypesCount(i_engine);  
         i_doc++) {  
        // Получение имени типа поддерживаемого документа   
        String doctype = settings.GetSupportedDocumentType(i_engine, i_doc);  
    }  
}

Внимание!

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

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

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

C++

settings->AddEnabledDocumentTypes("rus.2ndfl.type1"); // Включение НДФЛ в процесс распознавания

Java

settings.AddEnabledDocumentTypes("rus.2ndfl.type1"); // Включение НДФЛ в процесс распознавания

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

C++

settings->AddEnabledDocumentTypes("rus.2ndfl.*"); // Включение в процесс распознавания 2-НДФЛ

Java

settings.AddEnabledDocumentTypes("rus.2ndfl.*"); // Включение в процесс распознавания 2-НДФЛ

Внимание!

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

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

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

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

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

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

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

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

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

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

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

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

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

C++

const char* signature = "... YOUR SIGNATURE HERE ..." //Подпись, используемая для запуска Smart Document Engine;  
std::unique_ptr<se::doc::DocSession> session(engine->SpawnSession(*settings, signature));

Java

import com.smartengines.doc.*  
String signature = "... YOUR SIGNATURE HERE ..." //Подпись, используемая для запуска Smart Document Engine;  
DocSession session = engine.SpawnSession(settings, signature);

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

Создайте объект настроек обработки изображения:

C++

std::unique_ptr<se::doc::DocProcessingSettings> proc_settings(session->CreateProcessingSettings());

Java

import com.smartengines.doc.*  
DocProcessingSettings proc_settings = session.CreateProcessingSettings();

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

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

C++

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

Java

import com.smartengines.doc.*  
Image image = Image.FromFile(image_path); // Загрузка из файла

Внимание!

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

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

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

C++

session->ProcessImage(*image, proc_settings.get())

Java

session.ProcessImage(*image, proc_settings.get());

Распознавание многостраничных документов

Smart Document Engine поддерживает распознавание многостраничных документов.

Можно распознать все страницы документа за одну сессию, последовательно вызывая метод processImage() для распознавания каждой страницы.

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

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

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

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

Получение текущего результата из сессии

Получите текущий результат из сессии:

C++

const se::doc::DocResult& result = session->GetCurrentResult();

Java

import com.smartengines.doc.*  
DocResult result = session.GetCurrentResult();

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

Используйте объект класса DocResult для получения результатов распознавания:

C++

// Прохождение по циклу найденных документов  
for (auto doc_it = result.DocumentsBegin();  
     doc_it != result.DocumentsEnd();  
     ++doc_it) {  
    const se::doc::Document& doc = doc_it.GetDocument();  
     
    // Прохождение по циклу текстовых полей   
    for (auto it = doc.TextFieldsBegin();  
         it != doc.TextFieldsEnd();  
         ++it) {

        // Получение значений текстовых полей (в виде строки в кодировке UTF-8)  
        std::string field_value = it.GetField().GetOcrString().GetFirstString().GetCStr();  
    }  
}

Java

import com.smartengines.doc.*  
// Прохождение по циклу найденных документов  
for (DocumentsIterator doc_it = result.DocumentsBegin();  
     !doc_it.Equals(result.DocumentsEnd());  
     doc_it.Advance()) {  
    Document doc = doc_it.GetDocument();
     
    // Прохождение по циклу текстовых полей  
    for (DocTextFieldsIterator it = doc.TextFieldsBegin();  
         !it.Equals(doc.TextFieldsEnd());  
         it.Advance()) {
        // Получение значений текстовых полей (в виде строки в кодировке UTF-8)  
        String field_value = it.GetField().GetOcrString().GetFirstString().GetCStr();  
    }  
}

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

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

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

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

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

Общие классы

Общие классы, например, 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>	Содержит вспомогательные классы, связанные с сериализацией объектов
<secommon/se_common.h>	Вспомогательный заголовок, который включает в себя все вышеперечисленное

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

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

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

Основные классы Smart Document Engine содержатся в пространстве имен  se::doc в директории docengine:

Заголовочный файл	Описание
<docengine/doc_document_info.h>	Предоставляет информацию о типе документа (текстовое описание документа)
<docengine/doc_engine.h>	Содержит определение класса DocEngine
<docengine/doc_session_settings.h>	Содержит определение класса DocSessionSettings
<docengine/doc_session.h>	Содержит определение класса DocSession
<docengine/doc_processing_settings.h>	Содержит определение класса DocProcessingSettings
<docengine/doc_result.h>	Содержит определения классов DocResult, DocTemplateDetectionResult и DocTemplateSegmentationResult
<docengine/doc_document.h>	Содержит определение класса Document
<docengine/doc_documents_iterator.h	Содержит итераторы документов
<docengine/doc_fields.h>	Содержит определения классов, описывающих поля Smart Document Engine
<docengine/doc_fields_iterator.h>	Содержит итераторы полей
<docengine/doc_feedback.h>	Содержит интерфейс обратной связи DocFeedback и связанные с ним контейнеры
<docengine/doc_document_field_info.h>	Содержит информацию о поле документа, описание класса DocDocumentFieldInfo
<docengine/doc_document_fields_info_iterator.h>	Содержит итераторы информации о полях документа, описываемых классом DocDocumentFieldInfo
<docengine/doc_basic_object.h>	Содержит определение класса DocBasicObject
<docengine/doc_basic_objects_iterator.h>	Содержит итераторы основных объектов документов DocBasicObject
<docengine/doc_objects.h>	Содержит определения классов графических объектов
<docengine/doc_objects_collection.h>	Содержит определение класса массива документов DocObjectsCollection
<docengine/doc_objects_collection_iterator.h>	Содержит итераторы массива объектов документов DocObjectsCollection
<docengine/doc_forward_declarations.h>	Сервисный заголовочный файл. Содержит объявления классов
<docengine/doc_physical_document.h>	Содержит определения классов DocPhysicalDocument, DocPhysicalPage и DocPageInfo, описывающих физический документ
<docengine/doc_physical_document_iterators.h>	Содержит итераторы массива физических документов DocPhysicalDocument
<docengine/doc_scene_info.h>	Содержит определения класса DocSceneInfo, описывающего сценарий распознавания документа

Устаревшие заголовочные файлы (будут исключены в следующих версиях):

Заголовочный файл	Описание
<docengine/doc_video_session.h>	Содержит определение класса DocVideoSession
<docengine/doc_external_processor.h>	Содержит интерфейс обработки внешнего документа
<docengine/doc_graphical_structure.h>	Содержит определение класса DocGraphicalStructure
<docengine/doc_tags_collection.h>	Содержит определение класса DocTagsCollection
<docengine/doc_view.h>	Содержит определение класса DocView
<docengine/doc_views_iterator.h>	Содержит итераторы образов документов DocView
<docengine/doc_views_collection.h>	Содержит определение класса DocViewsCollection

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

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

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

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

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

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

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

Примечание.

se::common::BaseException не является подклассом std::exception. Интерфейс Smart Document Engine не имеет зависимостей от STL.

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