Документация по Smart Code Engine SDK
Smart Code Engine — это многоплатформенный автономный SDK для распознавания линейных и двухмерных штрихкодов, МЧЗ, номеров банковских карт и телефонных номеров и других кодифицированных объектов.
Жизненный цикл
Жизненный цикл CodeEngine состоит из следующих этапов:
- Создание движка распознавания.
- Создание сессии распознавания.
- Настройка сессии распознавания.
- Создание объекта изображения (Image).
- Процесс распознавания.
- Обработка результата распознавания.
- Освобождение памяти.
Создание движка распознавания
Из Описания системы:
Движок распознавания — это объект, в котором хранятся и инициализируются все инструменты распознавания. Он создается на основе конфигурационного бандла, содержащего все возможные настройки: список документов, поддерживаемых конкретным SDK, их полей, список возможных проверок подлинности и так далее.
Примечание.
В особых случаях бандл может поставляться не отдельно, а в составе (внутри) библиотеки.
При создании данного объекта обычно указывается способ инициализации и путь до бандла (если он поставляется отдельно).
Инициализацию движка рекомендуется выполнять в единственном экземпляре. Один экземпляр позволяет создавать множество сессий распознавания.
Процесс инициализации является достаточно "тяжелой" операцией (как и сам анализ изображений), поэтому его следует выполнять вне потока пользовательского интерфейса.
Создайте экземпляр CodeEngine:
std::unique_ptr<se::code::CodeEngine> engine(
se::code::CodeEngine::CreateFromEmbeddedBundle(true));import com.smartengines.code.*;
CodeEngine engine = CodeEngine.CreateFromEmbeddedBundle(true);Параметры:
- метод
CreateFromEmbeddedBundle()— флаг “ленивой” конфигурации (по умолчанию —true). Необязательный параметр.
Создание сессии распознавания
Создание объекта настроек сессии
Из Описания системы:
Настройки сессии — это объект, в котором хранится:
- список поддерживаемых документов для распознавания, сгруппированных по внутренним движкам. Их состав задается в конфигурационном бандле, с которым был создан движок (только чтение);
- список документов, переданных на распознавание (по умолчанию —
*); - специальные опции сессии: количество потоков для распознавания и прочее. Полный список можно найти в документации.
Создайте объект CodeEngineSessionSettings на основе сконфигурированного экземпляра CodeEngine:
std::unique_ptr<se::code::CodeEngineSessionSettings> settings(engine->GetDefaultSessionSettings());import com.smartengines.code.*;
CodeEngineSessionSettings settings = engine.GetDefaultSessionSettings();Внимание!
CodeEngine::GetDefaultSessionSettings() является фабричным методом и и возвращает указатель на выделенный в памяти и инициализированный объект. За удаление этого объекта ответственен вызывающий.
Настройка сессии распознавания
Движок распознает штрихкоды в определенном наборе кадров. По умолчанию эта функция отключена.
Для ее включения, установите соответствующий параметр сессии:
settings->SetOption("barcode.enabled", "true"); // Включение распознавания штрихкодов в текущей сессииsettings.SetOption("barcode.enabled", "true"); // Включение распознавания штрихкодов в текущей сессииНастройка дополнительных параметров сессии
Необязательный этап.
Задайте, при необходимости, дополнительные параметры сессии:
settings->SetOption("barcode.COMMON.enabled", "true"); // Включение распознавания наиболее часто используемых символик штрихкодов в текущей сессииsettings.SetOption("barcode.COMMON.enabled", "true"); // Включение распознавания наиболее часто используемых символик штрихкодов в текущей сессииНастройка распознаваемых символик штрихкодов
По умолчанию все символики штрихкодов исключены из процесса распознавания.
Для включения символики в процесс распознавания, установите значения параметров:
settings->SetOption("barcode.<symbology>.enabled", "true");settings.SetOption("barcode.<symbology>.enabled", "true");Наборы поддерживаемых символик:
| Название | Символики штрихкодов | Описание |
|---|---|---|
| COMMON | AZTEC; QR_CODE; DATA_MATRIX; PDF_417; CODABAR; CODE_128; EAN_8; EAN_13_UPC_A; ITF; UPC_E;CODE_39; CODE_93 | Наиболее часто используемые символики. Могут подключаться по отдельности |
| ALL | AZTEC; QR_CODE; MICRO_QR; RMQR; DATA_MATRIX; PDF_417; MICRO_PDF_417; CODABAR; CODE_128; EAN_8; EAN_13_UPC_A; ITF; UPC_E; CODE_39; CODE_93 | Все поддерживаемые символики. Могут подключаться по отдельности |
| ALL_1D | CODE_128; EAN_8; EAN_13_UPC_A; ITF; UPC_E; CODE_39; CODE_93 | Одномерные штрихкоды. Могут подключаться по отдельности |
| ALL_2D | AZTEC; QR_CODE; MICRO_QR; RMQR; DATA_MATRIX; PDF_417; MICRO_PDF_417 | Двумерные штрихкоды. Могут подключаться по отдельности |
Включение набора штрихкодов COMMON в процесс распознавания:
settings->SetOption("barcode.COMMON.enabled", "true");settings.SetOption("barcode.COMMON.enabled", "true");Включение набора штрихкодов ALL в процесс распознавания:
settings->SetOption("barcode.ALL.enabled", "true");settings->SetOption("barcode.ALL.enabled", "true");Внимание!
Рекомендуется включать в процесс распознавания только необходимые символики для достижения максимальной производительности и качества распознавания.
Результат распознавания содержит два поля:
- bytes — поле данных в формате base64;
- value — поле данных в человекочитаемом формате или, если это невозможно, — копия данных поля bytes. Кодировка определяет тип формата данных, содержащихся в данном поле. Как правило, это значение utf8 или base64.
Существует три основных сценария распознавания штрихкодов:
- focused — штрихкоды обрабатываются с помощью портативной камеры в видеопотоке, когда штрихкод занимает значительную площадь исходного изображения;
- anywhere — штрихкоды обрабатываются на любом изображении в любом месте. Ресурсоемкая операция. Может применяться для обработки любого изображения из галереи. Рекомендуется использовать данный сценарий для распознавания изображений из галереи;
- dummy — в основном, используется, когда расположение штрихкода заранее определено.
Внимание!
Для платежных штрихкодов рекомендуется:
- включить символики QR, Aztec и DataMatrix в процесс распознавания;
- установить режим распознавания focused;
- установить параметр maxAllowedCodesPerFrame=1 — ограничение максимально возможного количества распознаваемых штрихкодов единицей.
Для включения необходимого режима? установите соответствующий параметр сессии:
settings->SetOption("barcode.roiDetectionMode", "focused");settings.SetOption("barcode.roiDetectionMode", "focused");По умолчанию установлен “одиночный” режим подачи штрихкода — single: распознавание до первого найденного штрихкода.
Чтобы распознать несколько штрихкодов, установите “последовательный” режим — sequence:
settings->SetOption("barcode.feedMode", "sequence");settings.SetOption("barcode.feedMode", "sequence");Существует набор структурированных текстовых сообщений, которые обычно кодируются с помощью штрихкодов. Вы можете указать, какое структурированное сообщение вы ожидаете увидеть в своем сеансе. Эта подсказка обозначается как preset (пресет) и заполняет набор полей, на которые разбивается содержимое. По умолчанию данная функция отключена.
Для включения пресета, задайте следующий параметр сессии:
settings->SetOption("barcode.preset", "AAMVA");settings.SetOption("barcode.preset", "AAMVA");Можно задать сложный пресет:
settings->SetOption("barcode.preset", "URL|PAYMENT");settings.SetOption("barcode.preset", "URL|PAYMENT");где значение параметра содержит набор пресетов, разделенных знаком |.
Если пресет настроен корректно, к результату добавляется параметр CodeField message_type, содержащий название пресета, а также соответствующий список CodeFields.
Полный список поддерживаемых пресетов: AAMVA, GS1, URL, EMAIL, VCARD, ICALENDAR, PHONE, SMS, ISBN, WIFI, GEO, PAYMENT.
Каждый пресет содержит определенный набор полей:
| Пресет | Поля |
|---|---|
| AAMVA | В соответствие сл спецификацией AAMVA, например, "AAMVA_VERSION", "ANSI", "DAC" и др. |
| GS1 | "BATCH/LOT", "EXPIRY", "GTIN", "SERIAL", "SSCC/SSCI" и др. |
| URL | "URL" |
| "Body", "Recipients", "Subject", "URL mailto", "Carbon copy" и др. | |
| VCARD | "vCard version", "ADR", "AGENT", "BDAY", "CATEGORIES", "CLASS", "LABEL", "EMAIL" и др. |
| ICALENDAR | "EVENT0", "EVENT1" и др. |
| PHONE | "Phone" |
| SMS | "SMS_number", "Body" |
| ISBN | "ISBN", "ISBN type", "Prefix", "Registration group" |
| WIFI | "Authentication type", "Password", "SSID" и др. |
| GEO | "Latitude", "Longitude", "Query" |
| PAYMENT | "BIC", "BankName", "CorrespAcc", "Name", "PersonalAcc"и др. |
Настройки распознавания штрихкодов:
| Параметр | Тип возвращаемого значения | Значение по умолчанию | Описание |
|---|---|---|---|
| barcode.enabled | "true" или "false" | "false" | Включает/отключает распознавание штрихкода |
| barcode.ALL.enabled | "true" или "false" | "false" | Включает/отключает распознавание всех символик |
| barcode.COMMON.enabled | "true" или "false" | "false" | Включает/отключает распознавание наиболее частых (common) символик |
| barcode.maxAllowedCodesPerFrame | целое число | “1” | Задает максимальное число распознаваемых кодов |
| barcode.roiDetectionMode | "focused", "anywhere" или "dummy" | “focused” | Устанавливает режим ROI |
| barcode.feedMode | "sequence" или "single" | “single” | Устанавливает режим подачи штрихкодов |
| barcode.effortLevel | "low", "normal" или "high" | “normal” | Задает уровень усилий при распознавании |
| barcode.<symbology>.enabled | "true" или "false" | "false" | Включает/отключает указанную символику |
| barcode.<symbology>.minMsgLen | целое число | “1” | Минимальная длина сообщения со штрихкодом |
| barcode.<symbology>.maxMsgLen | целое число | “999” | Максимальная длина сообщения со штрихкодом |
| barcode.<symbology>.checkSumPresence | целое число | “0” | Задает наличие контрольной суммы (для 1d штрихкодов) |
| barcode.<symbology>.extendedMode | "true" или "false" | "false" | Устанавливает расширенный режим распознавания (для 1d штрихкодов) |
| barcode.<symbology>.barcodeColour | "black", "white" или "unknown" | "unknown" | Задает цвет ожидаемого штрихкода |
| barcode.preset | имя пресета | — | Задает пресет для интерпретации содержимого декодированного штрих-кода |
| barcode.preset.PAYMENT.strictSpecCompliance | "true" или "false" | "false" | Определяет, точно ли пресет PAYMENT соответствует спецификации |
| barcode.smartPaymentBarDecoding | "true" или "false" | "false" | Включает/отключает умное распознавание кодировки для платежных штрихкодов |
Для включения умного распознавания кодировок платежных штрихкодов, не соответствующих спецификации, установите параметры:
settings->SetOption("barcode.smartPaymentBarDecoding", "true");settings.SetOption("barcode.smartPaymentBarDecoding", "true");Будет создан объект CodeField smart_payment_bar_decoding_result, содержащий название кодировки. Этот объект можно использовать в пресете PAYMENT вместо спецификации. Полный список поддерживаемых кодировок: UTF8, CP1251, KOI8_R, ISO8859_5, CP932.
Настройка распознавания банковских карт
Движок bank_card распознает банковские карты в определенном наборе кадров. По умолчанию эта функция отключена. Чтобы ее включить, установите следующие значения параметров сессии:
settings->SetOption("bank_card.enabled", "true");settings.SetOption("bank_card.enabled", "true");Поддерживаются три типа банковских карт:
- embossed — эмбоссированные, или карты с нанесением данных в виде рельефных знаков;
- indent — гравированные, или карты с нанесением данных в виде гравированных знаков;
- freeform — напечатанные, или карты с плоским нанесением данных. Данные могут располагаться в различных частях карты.
По умолчанию активированы все типы.
Можно явно включить распознавание банковских карт с помощью опций:
settings->SetOption("bank_card.embossed.enabled", "true");settings.SetOption("bank_card.embossed.enabled", "true");Результат распознавания эмбоссированных карт и гравированных карт может содержать следующие поля:
| Поле | Описание |
|---|---|
| number | номер карты (обязательное поле) |
| name | имя держателя карты |
| expiry_date | срок действия в формате MM/ГГ (месяц/год) |
| optional_data_0 | дополнительная строка любого формата |
| optional_data_1 | дополнительная строка любого формата |
| optional_data_2 | дополнительная строка любого формата |
Результат распознавания напечатанных карт (freeform) может содержать следующие поля:
| Поле | Описание |
|---|---|
| number | номер карты (обязательное поле) |
| name | имя держателя карты |
| expiry_date | срок действия в формате MM/ГГ (месяц/год) |
| iban | IBAN (по ISO 13616) |
| secret code | код VC/CVV |
Режим захвата определяет, как искать банковскую карту. Существуют два режима захвата:
- mobile — подходит для распознавания с помощью портативных камер в видеопотоке;
- anywhere — подходит для распознавания отсканированных, снятых на веб-камеру изображений, изображений и карт, размещенных произвольным образом. Рекомендуется применять для распознавания карт и изображений из галереи устройства.
По умолчанию установлен режим mobile.
Опции распознавания банковских карт:
| Параметр | Тип возвращаемого значения | Значение по умолчанию | Описание |
|---|---|---|---|
| bank_card.enabled | "true" или "false" | "false" | Включает/отключает распознавание банковской карты |
| bank_card.captureMode | "mobile" или "anywhere" | "mobile" | Устанавливает режим распознавания банковской карты |
| bank_card.enableStoppers | "true" или "false" | "true" | Включает/отключает интеллектуальные ограничители текстовых полей (стопперы) |
| bank_card.extractBankCardImages | "true" или "false" | "false" | Извлекает исправленное изображение банковской карты и сохраняет его в соответствующем объекте CodeObject |
Настройка распознавание МЧЗ
Движок МЧЗ распознает машиночитаемые зоны на определенном наборе кадров согласно спецификации ICAO. По умолчанию эта функция отключена. Чтобы ее включить, задайте соответствующие опции сессии:
settings->SetOption("mrz.enabled", "true");settings.SetOption("mrz.enabled", "true");Результат распознавания содержится в поле объекта full_mrz. Этот объект также содержит набор разделенных полей, имена которых зависят от типа МЧЗ.
Движок поддерживает распознавание следующих типов МЧЗ:
| Тип МЧЗ | Документ | Описание |
|---|---|---|
| подтип ICAO 9303 MRZ MRP (TD3) | Машиночитаемый паспорт | 2 строки по 44 символа |
| подтип ICAO 9303 MRZ MRVA | Машиночитаемая виза | Тип A, 2 строки по 44 символа |
| подтип ICAO 9303 MRZ MRVB | Машиночитаемая виза | Тип B, 2 строки по 36 символов |
| подтип ICAO 9303 MRZ TD1 | Машиночитаемый проездной документ | Тип 1, 3 строки по 30 символов |
| подтип ICAO 9303 MRZ TD2 | Машиночитаемый проездной документ | Type 2, 2 строки по 36 символов |
| МЧЗ-подобная зона | Болгарские свидетельства о регистрации транспортного средства | 3 строки по 30 символов |
| МЧЗ-подобная зона | Водительские права Швейцарии | 3 строки: 9 символов в первой строке, 30 символов во второй и третьей строках |
| МЧЗ-подобная зона | Удостоверение личности Эквадора | 3 строки по 30 символов |
| МЧЗ-подобная зона | Удостоверение личности Франции | 2 строки по 36 символов |
| МЧЗ-подобная зона | Удостоверение личности Кении | 3 строки по 30 символов |
| МЧЗ-подобная зона | Российский внутренний паспорт | 2 строки по 44 символа |
| МЧЗ-подобная зона | Российская виза | 2 строки по 44 символа |
В зависимости от типа МЧЗ, результат распознавания содержит подмножество полей со следующими названиями:
| Название поля | Описание |
|---|---|
| mrz_doc_type_code | Код типа документа |
| mrz_number | Номер документа |
| mrz_issuer | Кем выдан |
| mrz_proprietor | Владелец |
| mrz_vehicle_number | Номер транспортного средства |
| mrz_line1 | Строка 1 |
| mrz_line2 | Строка 2 |
| mrz_line3 | Строка 3 |
| full_mrz | МЧЗ полностью |
| mrz_vin | VIN (Идентификационный номер транспортного средства) |
| mrz_id_number | Идентификационный номер |
| mrz_cd_number | Контрольное число номера |
| mrz_cd_bgrvrd_1 | 1-е контрольное число регистрационного сертификата транспортного средства Болгарии |
| mrz_cd_bgrvrd_2 | 2-е контрольное число регистрационного сертификата транспортного средства Болгарии |
| mrz_birth_date | Дата рождения |
| mrz_name | Имя |
| mrz_nationality | Гражданство |
| mrz_opt_data_1 | Персональный номер или другие дополнительные данные строки 1 |
| mrz_opt_data_2 | Персональный номер или другие дополнительные данные строки 2 |
| mrz_last_name | Фамилия |
| mrz_gender | Пол |
| mrz_expiry_date | Дата окончания срока действия |
| mrz_issue_date | Дата выдачи |
| photo | Фото |
| mrz_cd_birth_date | Контрольное число даты рождения |
| mrz_cd_composite | Составное контрольное число |
| mrz_cd_expiry_date | Контрольное число даты окончания действия |
| mrz_cd_opt_data_2 | Контрольное число строки 2 дополнительных данных |
| mrz_authority_code | Код подразделения |
| mrz_id_visa | ИД визы |
| mrz_invitation_number | Номер приглашения |
| mrz_cd_name | Контрольное число имени |
| mrz_cd_invitation_number | Контрольное число номера приглашения |
| mrz_cd_id_visa | Контрольное число ИД визы |
| mrz_first_name | Имя |
| mrz_cd_issue_date | Контрольное число даты вычета |
Настройка распознавания строк кодированного текста
Движок code_text_line распознает строки кодированного текста. По умолчанию эта функция отключена. Чтобы ее включить, задайте соответствующие опции сессии:
settings->SetOption("code_text_line.enabled", "true");settings.SetOption("code_text_line.enabled", "true");Существует два типа поддерживаемых кодированных текстовых строк: phone_number (номер телефона) и card_number (номер карты). По умолчанию оба типа не активированы.
Внимание!
Типы phone_number и card_number являются взаимоисключающими.
Укажите явно тип строки кодированного текста с помощью соответствующей опции сессии:
settings->SetOption("code_text_line.card_number.enabled", "true");settings.SetOption("code_text_line.card_number.enabled", "true");Движок code_text_line распознает как печатные, так и рукописные текстовые строки.
Внимание!
Текстовая строка должна составлять не менее трети площади, занимаемой символами, обозначающими регион.
Поддерживаются номера в следующих форматах:
- 11 цифр — номера, начинающиеся с 7 или 8, и кодами 3XX, 4XX, 7XX, 8XX, 9XX;
- 10 цифр — номера, начинающиеся с 9 (сокращенная запись мобильных номеров).
Настройка распознавания платежных реквизитов
Движок payment_details распознает платежные реквизиты, представленные в текстовой форме, которые необходимы для осуществления платежа в финансовой системе Российской Федерации. По умолчанию эта функция отключена. Чтобы ее включить, задайте соответствующие опции сессии:
settings->SetOption("payment_details.enabled", "true");settings.SetOption("payment_details.enabled", "true");Для включения распознавания определенного типа платежных реквизитов, задайте соответствующие опции сессии:
settings->SetOption("payment_details.<type>.enabled", "true");settings.SetOption("payment_details.<type>.enabled", "true");Полный список поддерживаемых типов: inn, kpp, rcbic, rus_bank_account, personal_account.
Внимание!
По умолчанию включено распознавание всех типов платежных реквизитов.
Технология Universal Pay, применяемая в Smart Code Engine, позволяет распознавать объекты в платежном документе без указания типа.
Поддерживаемые объекты:
- платежный штрихкод, выполненный по стандарту ГОСТ Р 56042-2014: QR Code, Aztec Code, Data Matrix;
- банковская карта;
- номер телефона;
- номер банковской карты.
Клиент предоставляет на вход последовательность изображений, а сессия распознает и кладет в результат только те объекты, по которым можно произвести платеж (т.е. остальные двумерные штрихкоды не по ГОСТ будут игнорироваться).
В рамках одной сессии распознается один платежный объект.
После обнаружения платежного объекта на последовательности кадров, сессия завершается. При этом для штрихкодов достаточно одного кадра, для остальных типов объектов требуется несколько кадров.
Примеры настроек параметров Universal Pay:
settings->SetOption("global.workflow", "universalPay");
settings->SetOption("barcode.enabled", "true");
settings->SetOption("barcode.QR_CODE.enabled", "true");
settings->SetOption("barcode.AZTEC.enabled", "true");
settings->SetOption("barcode.DATA_MATRIX.enabled", "true");
settings->SetOption("barcode.preset", "PAYMENT");
settings->SetOption("barcode.feedMode", "sequence");
settings->SetOption("bank_card.enabled", "true");
settings->SetOption("code_text_line.enabled", "true");
settings->SetOption("code_text_line.phone_number.enabled", "true");
settings->SetOption("code_text_line.card_number.enabled", "true");settings.SetOption("global.workflow", "universalPay");
settings.SetOption("barcode.enabled", "true");
settings.SetOption("barcode.QR_CODE.enabled", "true");
settings.SetOption("barcode.AZTEC.enabled", "true");
settings.SetOption("barcode.DATA_MATRIX.enabled", "true");
settings.SetOption("barcode.preset", "PAYMENT");
settings.SetOption("barcode.feedMode", "sequence");
settings.SetOption("bank_card.enabled", "true");
settings.SetOption("code_text_line.enabled", "true");
settings.SetOption("code_text_line.phone_number.enabled", "true");
settings.SetOption("code_text_line.card_number.enabled", "true");Параметры сессии распознавания
Каждой сессии распознавания можно задать определенный набор параметров с помощью методов класса CodeEngineSessionSettings.
Для получения имен параметров и их значений, выполните следующую процедуру:
for (auto it = settings->Begin(); it != settings->End(); ++it) {
// it.GetKey() возвращает имя параметра
// it.GetValue() возвращает значение параметра
}for (StringsMapIterator it = settings.Begin();
!it.Equals(settings.OptionsEnd());
it.Advance()) {
// it.GetKey() возвращает имя параметра
// it.GetValue() возвращает значение параметра
}Для изменения значений параметров, воспользуйтесь методом SetOption(...):
settings->SetOption("barcode.enabled", "true");
settings->SetOption("barcode.COMMON.enabled", "true");settings.SetOption("barcode.enabled", "true");
settings.SetOption("barcode.COMMON.enabled", "true");Значения параметров всегда представлены строкой (string). При необходимости передать целочисленное (integer) или булевое (bool) значение, преобразите их в строку.
Глобальные параметры:
| Параметр | Тип возвращаемого значения | Значение по умолчанию | Описание |
|---|---|---|---|
| global.workflow | Строка | "common" | Режим распознавания |
| global.enableMultiThreading | "true" или "false" | "true" | Обеспечивает параллельное выполнение внутренних алгоритмов |
| global.rgbPixelFormat | Строка символов R, G, B, и A | “RGB” для 3-канальных изображений, “BGRA” for 4-канальных изображений | Последовательность цветовых каналов в методе session.ProcessSnapshot() |
| global.sessionTimeout | Double | “0.0” для серверных бандлов, “5.0” для мобильных бандлов | Таймаут сессии в секундах |
Инициализация сессии
Из Описания системы:
При поставке продукта клиенту передается персональная подпись. Она содержится в файле README.html в директории /doc.
Каждый раз при создании экземпляра сессии распознавания подпись необходимо передавать в качестве одного из аргументов. Это подтверждает право вызывающего на использование библиотеки и разблокирует ее.
Проверка подписи осуществляется в оффлайн режиме. Библиотека не обращается ни к каким внешним ресурсам.
Инициализируйте сессию (объект CodeEngineSession):
const char* signature = "... YOUR SIGNATURE HERE ..."; //Подпись, используемая для запуска Smart Code Engine
std::unique_ptr<se::code::CodeEngineSession> session(engine->SpawnSession(*settings, signature, &my_workflow_feedback, &my_visualization_feedback));import com.smartengines.code.*;
String signature = "... YOUR SIGNATURE HERE ..."; //Подпись, используемая для запуска Smart Code Engine
CodeEngineSession session = engine.SpawnSession(settings, signature, my_workflow_feedback, my_visualization_feedback);Внимание!
CodeEngine::SpawnSession() является фабричным методом и и возвращает указатель на выделенный в памяти и инициализированный объект. За удаление этого объекта ответственен вызывающий.
Создание объекта Image
Из описания системы:
Для работы распознавания системе необходимо передать изображение специального класса se.common.image. Создать его можно из следующих форматов:
Поддерживаемые форматы:
- jpeg, png;
- tiff (✔️TIFF_LZW, ✔️TIFF_PACKBITS,✔️TIFF_CCITT);
- base64 (форматы из пунктов выше);
- файловый буфер с предварительным указанием цветовой схемы, ширины\высоты\количества каналов.
Максимальный допустимый размер изображения по умолчанию — 15000x15000px. Предельный размер изображения может быть увеличен пользователем.
Работа с HEIC
Работа с HEIC в мобильных SDK не отличается от работы с другими форматами изображений. Чтение HEIC осуществляется системными средствами.
В серверных SDK необходимо самостоятельно открыть HEIC формат сторонними средствами и конвертировать либо в один из поддерживаемых нами форматов, либо передать непосредственно сырые пиксели в виде RGB буфера (рекомендуется).
Создайте объект настроек обработки изображения (Image) для последующей обработки:
std::unique_ptr<se::common::Image> image(se::common::Image::FromFile(image_path)); // Загрузка из файлаimport com.smartengines.code.*;
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() является фабричным методом и и возвращает указатель на выделенный в памяти и инициализированный объект. За удаление этого объекта ответственен вызывающий.
Процесс распознавания
Вызовите метод Process(...) для обработки изображения:
const se::code::CodeEngineResult& result = session->Process(*image);import com.smartengines.code.*;
CodeEngineResult result = session.Process(image);Внимание!
CodeEngineResult::Process() не фабричный метод. Возвращаемый объект CodeEngineResult не является независимым, его срок жизни не превышает срок жизни объекта CodeEngineSession.
Обработка результата распознавания
Из Описания системы:
Результат распознавания — это объект интерфейса, содержащий всю доступную информацию о результате работы системы распознавания. Каждый параметр выводится с помощью отдельного метода, что позволяет при встраивании оперировать только необходимыми данными. Состав полей в объекте зависит от типа сессии, в которой выполнялось распознавание, а тип сессии зависит от функционала используемого продукта.
Значения полей объекта CodeEngineResult содержат информацию о результатах распознавания:
for (auto it_obj = result.ObjectsBegin(); it_obj != result.ObjectsEnd(); ++it_obj) {
const se::code::CodeObject& code_object = it_obj.GetValue();
std::string object_type = code_object.GetTypeStr(); // Тип объекта в формате строки
bool is_accepted = code_object.IsAccepted(); // Получение значения флага is_accepted
for (auto it_field = code_object.FieldsBegin();
it_field != code_object.FieldsEnd(); ++it_field) {
const se::code::CodeField &code_field = it_field.GetValue();
std::string code_field_name = code_field.Name(); // Имя поля
if (code_field.HasOcrStringRepresentation())
std::string ocr_string = code_field.GetOcrString()
.GetFirstString()
.GetCStr(); // Получение результата распознавания поля в виде строки в кодировке UTF-8
}
}import com.smartengines.code.*;
for (CodeObjectsMapIterator it_obj = result.ObjectsBegin();
!it_obj.Equals(result.ObjectsEnd()); it_obj.Advance()) {
CodeObject code_object = it_obj.GetValue();
String object_type = code_object.GetTypeStr(); // Тип объекта в формате строки
boolean is_accepted = code_object.IsAccepted(); // Получение значения флага is_accepted
}
for (CodeFieldsMapIterator it_field = code_object.FieldsBegin();
!it_field.Equals(code_object.FieldsEnd()); it_field.Advance()) {
CodeField code_field = it_field.GetValue();
String code_field_name = code_field.Name(); // Имя поля
if (code_field.HasOcrStringRepresentation())
String ocr_string = code_field.GetOcrString().GetFirstString().GetCStr(); // Получение результата распознавания поля в виде строки в кодировке UTF-8
}Обратные вызовы
Из Описания системы:
Распознавание в видеопотоке — это сложный и зачастую не мгновенный процесс, который требует взаимодействия с пользователем. Предоставляя информацию о ходе распознавания на экране в процессе работы, мы помогаем пользователю лучше понять этапы функционирования системы. Именно поэтому технологии машинного зрения часто дополняются элементами дополненной реальности, что улучшает пользовательский опыт и делает взаимодействие более интуитивным.
В объекте результата распознавания находится информация о координатах четырехугольника шаблона документа (границы документа) и координаты четырехугольников шаблонов полей документа. По этим координатам, например, можно отрисовать границы найденного документа на экране с превью камеры.
Smart Code Engine SDK поддерживает дополнительные обратные вызовы во время анализа объектов до завершения их обработки — метода Process(...). Это позволяет пользователю получать больше информации о базовом процессе распознавания, а также помогает создавать интерактивный графический интерфейс.
Для поддержки обратной связи, создайте подкласс классов CodeEngineWorkflowFeedback и CodeEngineVisualizationFeedback и реализуйте необходимые методы:
class MyWorkflowFeedback : public se::code::CodeEngineWorkflowFeedback {/* callbacks */ };
class MyVisualizationFeedback : public se::code::CodeEngineVisualizationFeedback { /* callbacks */ };
// ...
MyWorkflowFeedback my_workflow_feedback;
MyVisualizationFeedback my_visualization_feedback;import com.smartengines.code.*;
class MyWorkflowFeedback extends CodeEngineWorkflowFeedback { /* callbacks */ }
class MyVisualizationFeedback extends CodeEngineVisualizationFeedback { /* callbacks */ }
// ...
MyWorkflowFeedback my_workflow_feedback = new MyWorkflowFeedback();
MyVisualizationFeedback my_visualization_feedback = new MyVisualizationFeedback();
CodeEngineSession session = engine.SpawnSession(settings, signature, my_workflow_feedback, my_visualization_feedback);Освобождение памяти
Несмотря на то, что сборка мусора присутствует и работает, рекомендуется вызывать метод obj.delete() для наших объектов API вручную, поскольку они являются обертками памяти, выделенной в куче. Размер их кучи не известен сборщику мусора, что может привести к задержке удаления объектов и, следовательно, высокому общему потреблению памяти.
CodeEngine engine = CodeEngine.Create(config_path); // или любой другой объект
// ...
engine.delete(); // гарантирует принудительное и немедленное освобождение обернутого объекта C++Некоторые классы Smart Code Engine SDK содержат фабричные методы, возвращающие указатели на объекты, выделенные в куче. Необходимо удалять такие объекты.
Рекомендации.
в 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> | Содержит вспомогательные классы, связанные с сериализацией объектов (не используется в Smart Code Engine) |
| <secommon/se_common.h> | Вспомогательный заголовок, который включает в себя все вышеперечисленное. |
Аналогичные Java API содержатся в модуле com.smartengines.common:
import com.smartengines.common.*; // Импорт классов пакета se::common classesОсновные классы
Основные классы Smart Code Engine содержатся в пространстве имен se::code в директории codeengine:
| Заголовочный файл | Описание |
|---|---|
| <codeengine/code_engine.h> | Содержит класс CodeEngine |
| <codeengine/code_engine_session.h> | Содержит определение класса CodeEngineSession |
| <codeengine/code_engine_session_settings.h> | Содержит определение класса CodeEngineSessionSettings |
| <codeengine/code_engine_result.h> | Содержит определение класса CodeEngineResult |
| <codeengine/code_engine_feedback.h> | Содержит определение классов CodeEngineWorkflowFeedback и CodeEngineVisualizationFeedback и связанные с ними контейнеры |
| <codeengine/code_object_field.h> | Содержит определение класса CodeField |
| <codeengine/code_object.h> | Содержит определение класса CodeObject |
Аналогичные классы Java API содержатся в модуле com.smartengines.code:
import com.smartengines.codeengine.*; // Импорт всех классов se::codeОбработка исключений
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.
Тип исключения включен в текст сообщения.