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

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

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

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

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

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

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

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

Примечание.

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

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

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

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

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

C++

std::unique_ptr<se::text::TextEngine> engine(
    se::text::TextEngine::Create(configuration_bundle_path));

Java

TextEngine engine = TextEngine.Create(configuration_bundle_path);

Параметры:

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

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

Внимание!

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

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

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

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

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

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

C++

std::unique_ptr<se::text::TextSessionSettings> settings(
    engine->CreateSessionSettings());

Java

TextSessionSettings settings = engine.CreateSessionSettings();

Внимание!

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

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

Включение языков

Включите язык(и) распознаваемых документов.
Поддерживаемые языки — русский (rus) и английский (eng).

C++

settings->AddEnabledLanguages("rus"); // Russian language

Java

settings.AddEnabledLanguages("rus"); // Russian language

Поддерживаемые языки

Язык представляет собой строку (string), описывающий алфавит, который необходимо распознать (для этого обычно используются коды ISO 639-3). Также имеются два служебных языка — digits и punct (цифры и знаки пунктуации).

Получить информацию о языках, поддерживаемых SDK Smart Text Engine, входящим в ваш пакет поставки, можно следующим способом:

C++

// Iterating through supported languages
for (auto it = settings->SupportedLanguagesBegin();
     it != settings->SupportedLanguagesEnd();
     ++it) {
  //Getting language code
  std::string lang = it.GetValue();
  //Getting the string of characters
  std::string char_str = settings->GetLanguageAlphabet(lang); 
}

Java

// Iterating through supported languages
for (StringSetIterator it = settings.SupportedLanguagesBegin();
     !it.Equals(settings.SupportedLanguagesEnd());
     it.Advance()) {
  //Getting language code
  String lang = it.GetValue();
  //Getting the string of characters
  String char_str = settings.GetLanguageAlphabet(lang);
}

Для включения нескольких языков, укажите их через двоеточие, например, eng:digits.

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

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

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

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

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

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

C++

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

Java

String signature = "... YOUR SIGNATURE HERE ..."; //Подпись, используемая для запуска сессии распознавания Smart ID Engine
TextSession session = engine.SpawnSession(settings, signature);

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

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

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

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

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

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

Работа с HEIC

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

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

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

C++

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

Java

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() является фабричным методом и и возвращает указатель на выделенный в памяти и инициализированный объект. За удаление этого объекта ответственен вызывающий.

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

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

C++

session->ProcessImage(*image);

Java

session.ProcessImage(image);

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

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

Для получения результата рапознавания, выполните:

C++

const se::text::TextResult& result = session->GetCurrentResult();

java

TextResult result = session.GetCurrentResult();

Для получения информации об объекте TextScene, содержащим результаты распознавания, вызовите метод GetCurrentScene():

C++

const se::text::TextScene& scene = result.GetCurrentScene();

Java

TextScene scene = result.GetCurrentScene();

Для итерации по фрагментам распознанного текста, опысываемых коллекцией экземпляров TextChunk, получите объект TextIterator из объекта TextScene:

C++

 std::unique_ptr<se::text::TextIterator> chunk_iterator;
 chunk_iterator.reset(scene.CreateIterator("default"));
    for (; !chunk_iterator->Finished(); chunk_iterator->Advance()) {
      //Getting text chunk value (UTF-8 string representation)
      std::string chunk_str = chunk_iterator->GetTextChunk().GetOcrString().GetFirstString().GetCStr();
    }

Java

TextIterator chunk_iterator = scene.CreateIterator("default");
    for (; !chunk_iterator.Finished(); chunk_iterator.Advance()) {
      //Getting text chunk value (UTF-8 string representation)
      String chunk_str = chunk_iterator.GetTextChunk().GetOcrString().GetFirstString().GetCStr();
    }

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

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

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

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

• в C++:
  Для простоты управления памятью и предотвращения ее утечек пользуйтесь умными указателями std::unique_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>	Содержит вспомогательные классы, связанные с сериализацией объектов (не используется в Smart ID Engine)
<secommon/se_common.h>	Вспомогательный заголовок, который включает в себя все вышеперечисленное

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

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

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

Основные классы Smart Text Engine содержатся в пространстве имен se::text в директории textengine:

Заголовочный файл	Описание
<textengine/text_chunk_info.h>	Предоставляет информацию о фрагментах текста
<textengine/text_engine.h>	Содержит класс textengine
<textengine/text_session_settings.h>	Содержит определение класса textSessionSettings
<textengine/text_ session.h>	Содержит определение класса textSession
<textengine/text_result.h>	Содержит определение класса textResult
<textengine/text_feedback.h>	Содержит интерфейс обратной связи text_Feedback и связанные с ним контейнеры
<textengine/text_forward_declarations.h>	Служебный заголовок, содержащий предварительные декларации
<textengine/text_iterator.h>	Содержит определение класса TextIterator
<textengine/text_scene.h>	Содержит определение класса text_scene

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

import com.smartengines.text.*; // Импорт всех классов se::text 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.
Тип исключения включен в текст сообщения.