Привет, Хабр! В одной из прошлых наших статей изучался вопрос встраивания ядра распознавания Smart IDReader в iOS приложения. Пришло время обсудить эту же проблему, но для ОС Android. Ввиду большого количества версий системы и широкого парка устройств это будет посложнее, чем для iOS, но всё же вполне решаемая задача. Disclaimer – приведённая ниже информация не является истинной в последней инстанции, если вы знаете как упростить процесс встраивания/работы с камерой или сделать по другому – добро пожаловать в комментарии!
Допустим, мы хотим добавить функционал распознавания документов в своё приложение и для этого у нас есть Smart IDReader SDK, который состоит из следующих частей:
bin– сборка библиотеки ядраlibjniSmartIdEngine.soдля 32х битной архитектуры ARMv7bin-64– сборка библиотеки ядраlibjniSmartIdEngine.soдля 64х битной архитектуры ARMv8bin-x86– сборка библиотеки ядраlibjniSmartIdEngine.soдля 32х битной архитектуры x86bindings– JNI обёрткаjniSmartIdEngineJar.jarнад библиотекойlibjniSmartIdEngine.sodata– файлы конфигурации ядраdoc– документация к SDK
Некоторые комментарии по содержанию SDK.
Наличие трех сборок библиотеки под разные платформы – плата за большое разнообразие устройств на ОС Android (сборку для MIPS не делаем по причине отсутствия устройств данной архитектуры). Сборки для ARMv7 и ARMv8 являются основными, версия для x86 обычно используется нашими клиентами для конкретных устройств на базе мобильных процессоров Intel.
Обёртка JNI (Java Native Interface) jniSmartIdEngineJar.jar требуется для вызова C++ кода из Java приложений. Сборка обёртки у нас автоматизирована с помощью инструментария SWIG (simplified wrapper and interface generator).
Итак, как говорят французы, revenons à nos moutons! У нас есть SDK и нужно с минимальными усилиями встроить его в проект и начать использовать. Для этого потребуются следующие шаги:
- Добавление необходимых файлов к проекту
- Подготовка данных и инициализация движка
- Подключение камеры к приложению
- Передача данных и получение результата
Для того чтобы каждый мог поиграться с библиотекой мы подготовили и выложили исходный код Smart IDReader Demo for Android на Github. Проект сделан для Android Studio и демонстрирует пример работы с камерой и ядром на основе простого приложения.
Добавление необходимых файлов к проекту
Рассмотрим данный процесс на примере проекта приложения под Android Studio, для пользователей других IDE процесс не особо отличается. По умолчанию в каждом проекте Android Studio создает папку libs, из которой сборщик Gradle забирает и добавляется к проекту JAR файлы. Именно туда скопируем JNI обёртку jniSmartIdEngineJar.jar. Для добавления библиотек ядра существует несколько способов, проще всего это сделать с помощью JAR архива. Создаем в папке libs архив с именем native-libs.jar (это важно!) и внутри архива подпапки lib/armeabi-v7a и lib/arm64-v8a и помещаем туда соответствующие версии библиотек (для x86 библиотеки подпапка будет lib/x86).
В этом случае ОС Android после установки приложения автоматически развернёт нужную версию библиотеки для данного устройства. Сопутствующие файлы конфигурации движка добавляем в папку assets проекта, если данная папка отсутствует, то её можно создать вручную или с помощью команды File|New|Folder|Assets Folder. Как видим, добавить файлы к проекту очень просто и занимает совсем немного времени.
Подготовка данных и инициализация движка
Итак, мы добавили необходимые файлы к приложению и даже успешно его собрали. Руки так и тянутся попробовать новый функционал в деле, но для этого нужно ещё немного поработать :-) А именно сделать следующее:
- Развернуть файлы конфигурации ядра из assets
- Загрузить библиотеку и инициализировать движок
Чтобы библиотека могла получить доступ к файлам конфигурации необходимо перенести их из assets в рабочую папку приложения. Достаточно сделать это один раз при запуске и затем обновлять только при выходе новой версии. Проще всего такую проверку сделать, основываясь на версии кода приложения, и если она изменилась то обновить файлы.
// текущая версия кода приложения PackageInfo packageInfo = getPackageManager().getPackageInfo(getPackageName(), 0); int version_code = packageInfo.versionCode; SharedPreferences sPref = PreferenceManager.getDefaultSharedPreferences(this); // версия кода из настроек int version_current = sPref.getInt("version_code", -1); // если версии отличаются нужно обновить данные need_copy_assets = version_code != version_current; // обновляем версию кода в настройках SharedPreferences.Editor ed = sPref.edit(); ed.putInt("version_code", version_code); ed.commit(); … if (need_copy_assets == true) copyAssets();
Сама процедура копирования не сложна и заключается в получении данных из файлов, находящихся в assets приложения, и записи эти данных в файлы рабочего каталога. Пример кода функции, осуществляющей такое копирование, можно посмотреть в примере на Github.
Осталось только загрузить библиотеку и инициализировать ядро. Вся процедура занимает определённое время, поэтому разумно выполнять её в отдельном потоке, чтобы не затормаживать основной GUI поток. Пример инициализации на основе AsyncTask
private static RecognitionEngine engine; private static SessionSettings sessionSettings; private static RecognitionSession session; ... сlass InitCore extends AsyncTask<Void, Void, Void> { @Override protected Void doInBackground(Void... unused) { if (need_copy_assets) copyAssets(); // конфигурирование ядра configureEngine(); return null; } @Override protected void onPostExecute(Void aVoid) { super.onPostExecute(aVoid); if(is_configured) { // устанавливаем ограничения на распознаваемые документы (например, rus.passport.* означает подмножество документов российского паспорта) sessionSettings.AddEnabledDocumentTypes(document_mask); // получаем полные наименования распознаваемых документов StringVector document_types = sessionSettings.GetEnabledDocumentTypes(); ... } } } … private void configureEngine() { try { // загрузка библиотеки ядра System.loadLibrary("jniSmartIdEngine"); // путь к файлу настроек ядра String bundle_path = getFilesDir().getAbsolutePath() + File.separator + bundle_name; // инициализация ядра engine = new RecognitionEngine(bundle_path); // инициализация настроек сессии sessionSettings = engine.CreateSessionSettings(); is_configured = true; } catch (RuntimeException e) { ... } catch(UnsatisfiedLinkError e) { ... } }
Подключение камеры к приложению
Если ваше приложение уже использует камеру, то можете спокойно пропустить этот раздел и перейти к следующему. Для оставшихся рассмотрим вопрос использования камеры для работы с видео потоком для распознавания документов посредством Smart IDReader. Сразу оговоримся, что мы используем класс Camera, а не Camera2, хотя он и объявлен как deprecated начиная с версии API 21 (Android 5.0). Это осознанно сделано по следующим причинам:
- Класс Camera значительно проще в использовании и содержит необходимый функционал
- Поддержка старых устройств на Android 2.3.x и 4.x.x до сих пор актуальна
- Класс Camera до сих пор отлично поддерживается, тогда как в начале запуска Android 5.0 у многих производителей были проблемы с реализацией Camera2
Чтобы добавить поддержку камеры в приложение нужно прописать в манифест следующие строки:
<uses-permission android:name="android.permission.CAMERA" /> <uses-feature android:name="android.hardware.camera" />
Хорошим тоном является запрос разрешения на использование камеры, реализованные в Android 6.x и выше. К тому же пользователи этих систем всегда могут отобрать разрешения у приложения в настройках, так что проверку все равно проводить нужно.
// если необходимо - запрашиваем разрешение if( needPermission(Manifest.permission.CAMERA) == true ) requestPermission(Manifest.permission.CAMERA, REQUEST_CAMERA); … public boolean needPermission(String permission) { // проверка разрешения int result = ContextCompat.checkSelfPermission(this, permission); return result != PackageManager.PERMISSION_GRANTED; } public void requestPermission(String permission, int request_code) { // запрос на разрешение работы с камерой ActivityCompat.requestPermissions(this, new String[]{permission}, request_code); } @Override public void onRequestPermissionsResult(int requestCode, String permissions[], int[] grantResults) { switch (requestCode) { case REQUEST_CAMERA: { // запрос на разрешение работы с камерой boolean is_granted = false; for(int grantResult : grantResults) { if(grantResult == PackageManager.PERMISSION_GRANTED) // разрешение получено is_granted = true; } if (is_granted == true) { camera = Camera.open(); // открываем камеру .... } else toast("Enable CAMERA permission in Settings"); } default: super.onRequestPermissionsResult(requestCode, permissions, grantResults); } }
Важной частью работы с камерой является установка её параметров, а именно режима фокусировки и разрешения предпросмотра. Из-за большого разнообразия устройств и характеристик их камер этому вопросу следует уделить особое внимание. Если камера не поддерживает возможности фокусировки, то приходится работать с фиксированным фокусом или направленным на бесконечность. В таком случае особо ничего сделать нельзя, получаем изображения с камеры as is. А если нам повезло и фокусировка доступна, то проверяем, поддерживаются ли режимы FOCUS_MODE_CONTINUOUS_PICTURE или FOCUS_MODE_CONTINUOUS_VIDEO, что означает постоянный процесс фокусировки на объектах съемки в процессе работы. Если эти режимы поддерживаются, то выставляем их в параметрах. Если же нет, то можно сделать следующий финт – запустить таймер и самим вызывать функцию фокусировки у камеры с заданной периодичностью.
Camera.Parameters params = camera.getParameters(); // список поддерживаемых режимов фокусировки List<String> focus_modes = params.getSupportedFocusModes(); String focus_mode = Camera.Parameters.FOCUS_MODE_AUTO; boolean isAutoFocus = focus_modes.contains(focus_mode); if (isAutoFocus) { if (focus_modes.contains(Camera.Parameters.FOCUS_MODE_CONTINUOUS_PICTURE)) focus_mode = Camera.Parameters.FOCUS_MODE_CONTINUOUS_PICTURE; else if (focus_modes.contains(Camera.Parameters.FOCUS_MODE_CONTINUOUS_VIDEO)) focus_mode = Camera.Parameters.FOCUS_MODE_CONTINUOUS_VIDEO; } else { // если нет автофокуса то берём первый возможный режим фокусировки focus_mode = focus_modes.get(0); } // установка режима фокусировки params.setFocusMode(focus_mode); // запуск автофокуса по таймеру если нет постоянного режима фокусировки if (focus_mode == Camera.Parameters.FOCUS_MODE_AUTO) { timer = new Timer(); timer.schedule(new Focus(), timer_delay, timer_period); } … // таймер периодической фокусировки private class Focus extends TimerTask { public void run() { focusing(); } } public void focusing() { try{ Camera.Parameters cparams = camera.getParameters(); // если поддерживается хотя бы одна зона для фокусировки if( cparams.getMaxNumFocusAreas() > 0) { camera.cancelAutoFocus(); cparams.setFocusMode(Camera.Parameters.FOCUS_MODE_AUTO); camera.setParameters(cparams); } }catch(RuntimeException e) { ... } }
Установка разрешения предпросмотра достаточно проста, основные требования чтобы соотношения сторон preview камеры соответствовали сторонам области отображения для отсутствия искажений при просмотре, и желательно чтобы разрешение было как можно выше, так как от него зависит качество распознавания документа. В нашем примере приложение отображает preview на весь экран, поэтому выбираем максимальное разрешение, соответствующее соотношениям сторон экрана.
DisplayMetrics metrics = new DisplayMetrics(); getWindowManager().getDefaultDisplay().getMetrics(metrics); // соотношение сторон экрана float best_ratio = (float)metrics.heightPixels / (float)metrics.widthPixels; List<Camera.Size> sizes = params.getSupportedPreviewSizes(); Camera.Size preview_size = sizes.get(0); // допустимое отклонение от оптимального соотношения при выборе final float tolerance = 0.1f; float preview_ratio_diff = Math.abs( (float) preview_size.width / (float) preview_size.height - best_ratio); // выбираем оптимальное разрешение preview камеры по соотношению сторон экрана for (int i = 1; i < sizes.size() ; i++) { Camera.Size tmp_size = sizes.get(i); float tmp_ratio_diff = Math.abs( (float) tmp_size.width / (float) tmp_size.height - best_ratio); if( Math.abs(tmp_ratio_diff - preview_ratio_diff) < tolerance && tmp_size.width > preview_size.width || tmp_ratio_diff < preview_ratio_diff) { preview_size = tmp_size; preview_ratio_diff = tmp_ratio_diff; } } // установка размера preview в настройках камеры params.setPreviewSize(preview_size.width, preview_size.height);
Осталось совсем немного – установить ориентацию камеры и отображение preview на поверхность Activity. По умолчанию углу 0 градусов соответствует альбомная ориентация устройства, при поворотах экрана её нужно соответственно менять. Тут можно еще вспомнить добрым словом Nexus 5X от Google, матрица которого установлена в устройстве вверх ногами и для которого нужна отдельная проверка на ориентацию.
private boolean is_nexus_5x = Build.MODEL.contains("Nexus 5X"); SurfaceView surface = (SurfaceView) findViewById(R.id.preview); ... // портретная ориентация camera.setDisplayOrientation(!is_nexus_5x ? 90: 270); // отображение preview на поверхность приложения camera.setPreviewDisplay(surface.getHolder()); // начало процесса preview camera.startPreview();
Передача данных и получение результата
Итак, камера подключена и работает, осталось самое интересное – задействовать ядро и получить результат. Запускаем процесс распознавания, начав новую сессию и установив callback для получения кадров с камеры в режиме preview.
void start_session() { if (is_configured == true && camera_ready == true) { // установка параметров сессии, например тайм-аут sessionSettings.SetOption("common.sessionTimeout", "5.0"); // создании сессии распознавания session = engine.SpawnSession(sessionSettings); try { session_working = true; // семафоры готовности кадра к обработке и ожидания кадра frame_waiting = new Semaphore(1, true); frame_ready = new Semaphore(0, true); // запуск потока распознавания в отдельном AsyncTask new EngineTask().execute(); } catch (RuntimeException e) { ... } // установка callback для получения изображений с камеры camera.setPreviewCallback(this); } }
Функция onPreviewFrame() получает текущее изображение с камеры в виде массива байт формата YUV NV21. Так как она может вызываться только в основном потоке, чтобы его не замедлять вызовы ядра для обработки изображения помещаются в отдельный поток с помощью AsyncTask, синхронизация процесса происходит с помощью семафоров. После получения изображения с камеры даём сигнал рабочему потоку начать его обработку, по окончании — сигнал на получение нового изображения.
// текущее изображение private static volatile byte[] data; ... @Override public void onPreviewFrame(byte[] data_, Camera camera) { if(frame_waiting.tryAcquire() && session_working) { data = data_; // семафор готовности изображения к обработке frame_ready.release(); } } … class EngineTask extends AsyncTask<Void, RecognitionResult, Void> { @Override protected Void doInBackground(Void... unused) { while (true) { try { frame_ready.acquire(); // ждем новый кадр if(session_working == false) // остановка если сессия завершена break; Camera.Size size = camera.getParameters().getPreviewSize(); // передаём кадр в ядро и получаем результат RecognitionResult result = session.ProcessYUVSnapshot(data, size.width, size.height, !is_nexus_5x ? ImageOrientation.Portrait : ImageOrientation.InvertedPortrait); ... // семафор ожидания нового кадра frame_waiting.release(); }catch(RuntimeException e) { ... } catch(InterruptedException e) { ... } } return null; }
После обработки каждого изображения ядро возвращает текущий результат распознавания. Он включает в себя найденные зоны документа, текстовые поля со значениями и флагами уверенности, а также графические поля, такие как фотографии или подписи. Если данные распознаны корректно или произошел тайм-аут, то устанавливается флаг IsTerminal, сигнализирующий о завершении процесса. Для промежуточных результатов можно производить отрисовку найденных зон и полей, показывать текущий прогресс по качеству распознавания и многое другое, все зависит от вашей фантазии.
void show_result(RecognitionResult result) { // получаем распознанные поля с документа StringVector texts = result.GetStringFieldNames(); // получаем изображения с документа, такие как фотография, подпись и так далее StringVector images = result.GetImageFieldNames(); for (int i = 0; i < texts.size(); i++) // текстовые поля документа { StringField field = result.GetStringField(texts.get(i)); String value = field.GetUtf8Value(); // данные поля boolean is_accepted = field.IsAccepted(); .. статус поля ... } for (int i = 0; i < images.size(); i++) // графические поля документа { ImageField field = result.GetImageField(images.get(i)); Bitmap image = getBitmap(field.GetValue()); // получаем Bitmap ... } ... }
После этого нам остается только остановить процесс получения изображений с камеры и прекратить процесс распознавания.
void stop_session() { session_working = false; data = null; frame_waiting.release(); frame_ready.release(); camera.setPreviewCallback(null); // останавливаем процесс получения изображений с камеры ... }
Заключение
Как можно убедиться на нашем примере, процесс подключения Smart IDReader SDK к Android приложениям и работа с камерой не являются чем-то сложным, достаточно всего лишь следовать некоторым правилам. Целый ряд наших заказчиков успешно применяют наши технологии в своих мобильных приложениях, причем сам процесс добавления нового функционала занимает весьма небольшой время. Надеемся, с помощью данной статьи и вы смогли убедиться в этом!
P.S. Чтобы посмотреть, как Smart IDReader выглядит в нашем исполнении после встраивания, вы можете скачать бесплатные полные версии приложений из App Store и Google Play.
