Как добавлять ярлыки к изображениям с помощью модели, обученной в AutoML, на устройстве Android

Специальный API AutoML Vision Edge больше не доступен. Вместо этого используйте Custom Image Labeling API, который теперь поддерживает эти модели. Если вы используете этот API, следуйте инструкциям по переходу.

После того как вы обучите собственную модель с помощью AutoML Vision Edge, вы сможете использовать ее в своем приложении для присвоения ярлыков изображениям. Есть два способа интеграции моделей, обученных с помощью AutoML Vision Edge: вы можете связать модель, поместив ее в папку ресурсов вашего приложения, или динамически загрузить ее из Firebase.

Варианты комплектации моделей
Встроенные в приложение	Модель входит в состав APK-файла приложения. Модель доступна сразу, даже если устройство Android не подключено к интернету. Проект Firebase не требуется
Размещено в Firebase	Загрузите модель в Firebase Machine Learning. Уменьшает размер APK-файла. Модель скачивается по запросу Как отправлять обновления модели без повторной публикации приложения Простое A/B-тестирование с помощью Firebase Remote Config Требуется проект Firebase

Попробовать

• Попробуйте пример приложения, чтобы увидеть, как используется этот API.

Подготовка

1. В файле build.gradle на уровне проекта убедитесь, что репозиторий Google Maven указан в разделах buildscript и allprojects.

2. Добавьте зависимости для библиотек ML Kit для Android в файл gradle на уровне приложения вашего модуля, который обычно называется app/build.gradle: Для связывания модели с вашим приложением:

    dependencies {
      // ...
      // Image labeling feature with bundled automl model
      implementation 'com.google.mlkit:image-labeling-automl:16.2.1'
    }
    

Чтобы динамически скачивать модель из Firebase, добавьте зависимость linkFirebase:

    dependencies {
      // ...
      // Image labeling feature with automl model downloaded
      // from firebase
      implementation 'com.google.mlkit:image-labeling-automl:16.2.1'
      implementation 'com.google.mlkit:linkfirebase:16.0.1'
    }
    

3. Если вы хотите скачать модель, убедитесь, что вы добавили Firebase в проект Android. Это не требуется, если вы упаковываете модель.

1. Как загрузить модель

Как настроить источник локальной модели

Чтобы встроить модель в приложение:

1. Извлеките модель и ее метаданные из ZIP-архива, скачанного из консоли Firebase. Мы рекомендуем использовать скачанные файлы без изменений, в том числе не переименовывать их.

2. Добавьте модель и ее файлы метаданных в пакет приложения:

а. Если в вашем проекте нет папки с объектами, создайте ее, нажав правой кнопкой мыши на папку app/ и выбрав New > Folder > Assets Folder (Создать > Папка > Папка объектов).

Б. Создайте подпапку в папке объектов, чтобы хранить в ней файлы модели.

В. Скопируйте файлы model.tflite, dict.txt и manifest.json в подпапку (все три файла должны находиться в одной папке).

3. Добавьте в файл build.gradle приложения следующие строки, чтобы Gradle не сжимал файл модели при сборке приложения:

    android {
        // ...
        aaptOptions {
            noCompress "tflite"
        }
    }
    

Файл модели будет включен в пакет приложения и доступен ML Kit как необработанный объект.

Примечание. Начиная с версии 4.1 плагина Android Gradle, файлы .tflite будут добавляться в список noCompress по умолчанию, и указанные выше действия больше не потребуются.

4. Создайте объект LocalModel, указав путь к файлу манифеста модели:

Kotlin

val localModel = AutoMLImageLabelerLocalModel.Builder()
        .setAssetFilePath("manifest.json")
        // or .setAbsoluteFilePath(absolute file path to manifest file)
        .build()

Java

AutoMLImageLabelerLocalModel localModel =
    new AutoMLImageLabelerLocalModel.Builder()
        .setAssetFilePath("manifest.json")
        // or .setAbsoluteFilePath(absolute file path to manifest file)
        .build();

Как настроить источник модели, размещенный в Firebase

Чтобы использовать модель, размещенную на удаленном сервере, создайте объект RemoteModel, указав название, которое вы присвоили модели при публикации:

Kotlin

// Specify the name you assigned in the Firebase console.
val remoteModel =
    AutoMLImageLabelerRemoteModel.Builder("your_model_name").build()

Java

// Specify the name you assigned in the Firebase console.
AutoMLImageLabelerRemoteModel remoteModel =
    new AutoMLImageLabelerRemoteModel.Builder("your_model_name").build();

Затем запустите задачу скачивания модели, указав условия, при которых вы хотите разрешить скачивание. Если модели нет на устройстве или доступна более новая версия, задача асинхронно скачает модель из Firebase:

Kotlin

val downloadConditions = DownloadConditions.Builder()
    .requireWifi()
    .build()
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
    .addOnSuccessListener {
        // Success.
    }

Java

DownloadConditions downloadConditions = new DownloadConditions.Builder()
        .requireWifi()
        .build();
RemoteModelManager.getInstance().download(remoteModel, downloadConditions)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(@NonNull Task task) {
                // Success.
            }
        });

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

Как создать инструмент для разметки изображений на основе модели

После того как вы настроите источники модели, создайте объект ImageLabeler на основе одного из них.

Если у вас есть только локально упакованная модель, просто создайте разметчик из объекта AutoMLImageLabelerLocalModel и настройте пороговое значение оценки достоверности, которое вы хотите требовать (см. Оценка вашей модели):

Kotlin

val autoMLImageLabelerOptions = AutoMLImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0)  // Evaluate your model in the Firebase console
                                // to determine an appropriate value.
    .build()
val labeler = ImageLabeling.getClient(autoMLImageLabelerOptions)

Java

AutoMLImageLabelerOptions autoMLImageLabelerOptions =
        new AutoMLImageLabelerOptions.Builder(localModel)
                .setConfidenceThreshold(0.0f)  // Evaluate your model in the Firebase console
                                               // to determine an appropriate value.
                .build();
ImageLabeler labeler = ImageLabeling.getClient(autoMLImageLabelerOptions)

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

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

Kotlin

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener { isDownloaded -> 
    val optionsBuilder =
        if (isDownloaded) {
            AutoMLImageLabelerOptions.Builder(remoteModel)
        } else {
            AutoMLImageLabelerOptions.Builder(localModel)
        }
    // Evaluate your model in the Firebase console to determine an appropriate threshold.
    val options = optionsBuilder.setConfidenceThreshold(0.0f).build()
    val labeler = ImageLabeling.getClient(options)
}

Java

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(Boolean isDownloaded) {
                AutoMLImageLabelerOptions.Builder optionsBuilder;
                if (isDownloaded) {
                    optionsBuilder = new AutoMLImageLabelerOptions.Builder(remoteModel);
                } else {
                    optionsBuilder = new AutoMLImageLabelerOptions.Builder(localModel);
                }
                AutoMLImageLabelerOptions options = optionsBuilder
                        .setConfidenceThreshold(0.0f)  // Evaluate your model in the Firebase console
                                                       // to determine an appropriate threshold.
                        .build();

                ImageLabeler labeler = ImageLabeling.getClient(options);
            }
        });

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

Kotlin

RemoteModelManager.getInstance().download(remoteModel, conditions)
    .addOnSuccessListener {
        // Download complete. Depending on your app, you could enable the ML
        // feature, or switch from the local model to the remote model, etc.
    }

Java

RemoteModelManager.getInstance().download(remoteModel, conditions)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(Void v) {
              // Download complete. Depending on your app, you could enable
              // the ML feature, or switch from the local model to the remote
              // model, etc.
            }
        });

2. Как подготовить входное изображение

Затем для каждого изображения, которое вы хотите пометить, создайте объект InputImage. Маркировка изображений выполняется быстрее всего, если вы используете Bitmap или, если вы используете Camera2 API, YUV_420_888 media.Image, которые рекомендуется использовать, когда это возможно.

Объект InputImage можно создать из разных источников. Ниже описаны все способы.

Использование media.Image

Чтобы создать объект InputImage из объекта media.Image, например при съемке изображения камерой устройства, передайте объект media.Image и поворот изображения в InputImage.fromMediaImage().

Если вы используете библиотеку CameraX, классы OnImageCapturedListener и ImageAnalysis.Analyzer вычисляют значение поворота за вас.

Kotlin

private class YourImageAnalyzer : ImageAnalysis.Analyzer {

    override fun analyze(imageProxy: ImageProxy) {
        val mediaImage = imageProxy.image
        if (mediaImage != null) {
            val image = InputImage.fromMediaImage(mediaImage, imageProxy.imageInfo.rotationDegrees)
            // Pass image to an ML Kit Vision API
            // ...
        }
    }
}

Java

private class YourAnalyzer implements ImageAnalysis.Analyzer {

    @Override
    public void analyze(ImageProxy imageProxy) {
        Image mediaImage = imageProxy.getImage();
        if (mediaImage != null) {
          InputImage image =
                InputImage.fromMediaImage(mediaImage, imageProxy.getImageInfo().getRotationDegrees());
          // Pass image to an ML Kit Vision API
          // ...
        }
    }
}

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

Kotlin

private val ORIENTATIONS = SparseIntArray()

init {
    ORIENTATIONS.append(Surface.ROTATION_0, 0)
    ORIENTATIONS.append(Surface.ROTATION_90, 90)
    ORIENTATIONS.append(Surface.ROTATION_180, 180)
    ORIENTATIONS.append(Surface.ROTATION_270, 270)
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
@Throws(CameraAccessException::class)
private fun getRotationCompensation(cameraId: String, activity: Activity, isFrontFacing: Boolean): Int {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    val deviceRotation = activity.windowManager.defaultDisplay.rotation
    var rotationCompensation = ORIENTATIONS.get(deviceRotation)

    // Get the device's sensor orientation.
    val cameraManager = activity.getSystemService(CAMERA_SERVICE) as CameraManager
    val sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION)!!

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360
    }
    return rotationCompensation
}
MLKitVisionImage.kt

Java

private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
static {
    ORIENTATIONS.append(Surface.ROTATION_0, 0);
    ORIENTATIONS.append(Surface.ROTATION_90, 90);
    ORIENTATIONS.append(Surface.ROTATION_180, 180);
    ORIENTATIONS.append(Surface.ROTATION_270, 270);
}

/**
 * Get the angle by which an image must be rotated given the device's current
 * orientation.
 */
@RequiresApi(api = Build.VERSION_CODES.LOLLIPOP)
private int getRotationCompensation(String cameraId, Activity activity, boolean isFrontFacing)
        throws CameraAccessException {
    // Get the device's current rotation relative to its "native" orientation.
    // Then, from the ORIENTATIONS table, look up the angle the image must be
    // rotated to compensate for the device's rotation.
    int deviceRotation = activity.getWindowManager().getDefaultDisplay().getRotation();
    int rotationCompensation = ORIENTATIONS.get(deviceRotation);

    // Get the device's sensor orientation.
    CameraManager cameraManager = (CameraManager) activity.getSystemService(CAMERA_SERVICE);
    int sensorOrientation = cameraManager
            .getCameraCharacteristics(cameraId)
            .get(CameraCharacteristics.SENSOR_ORIENTATION);

    if (isFrontFacing) {
        rotationCompensation = (sensorOrientation + rotationCompensation) % 360;
    } else { // back-facing
        rotationCompensation = (sensorOrientation - rotationCompensation + 360) % 360;
    }
    return rotationCompensation;
}

Затем передайте объект media.Image и значение угла поворота в InputImage.fromMediaImage():

Kotlin

val image = InputImage.fromMediaImage(mediaImage, rotation)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromMediaImage(mediaImage, rotation);

Как использовать URI файла

Чтобы создать объект InputImage на основе URI файла, передайте контекст приложения и URI файла в InputImage.fromFilePath(). Это полезно, когда вы используете намерение ACTION_GET_CONTENT, чтобы предложить пользователю выбрать изображение из галереи.

Kotlin

val image: InputImage
try {
    image = InputImage.fromFilePath(context, uri)
} catch (e: IOException) {
    e.printStackTrace()
}
MLKitVisionImage.kt

Java

InputImage image;
try {
    image = InputImage.fromFilePath(context, uri);
} catch (IOException e) {
    e.printStackTrace();
}

Как использовать ByteBuffer или ByteArray

Чтобы создать объект InputImage из ByteBuffer или ByteArray, сначала рассчитайте угол поворота изображения, как описано выше для входных данных media.Image. Затем создайте объект InputImage с буфером или массивом, а также высотой, шириной, форматом кодирования цвета и углом поворота изображения:

Kotlin

val image = InputImage.fromByteBuffer(
        byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt
// Or:
val image = InputImage.fromByteArray(
        byteArray,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromByteBuffer(byteBuffer,
        /* image width */ 480,
        /* image height */ 360,
        rotationDegrees,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java
// Or:
InputImage image = InputImage.fromByteArray(
        byteArray,
        /* image width */480,
        /* image height */360,
        rotation,
        InputImage.IMAGE_FORMAT_NV21 // or IMAGE_FORMAT_YV12
);
MLKitVisionImage.java

Используется Bitmap

Чтобы создать объект InputImage на основе объекта Bitmap, добавьте следующее объявление:

Kotlin

val image = InputImage.fromBitmap(bitmap, 0)
MLKitVisionImage.kt

Java

InputImage image = InputImage.fromBitmap(bitmap, rotationDegree);
MLKitVisionImage.java

Изображение представлено объектом Bitmap вместе с градусами поворота.

3. Как запустить инструмент для распознавания объектов на изображениях

Чтобы добавить ярлыки к объектам на изображении, передайте объект image методу process() объекта ImageLabeler.

Kotlin

labeler.process(image)
        .addOnSuccessListener { labels ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }
ImageLabelingActivity.kt

Java

labeler.process(image)
        .addOnSuccessListener(new OnSuccessListener<List<ImageLabel>>() {
            @Override
            public void onSuccess(List<ImageLabel> labels) {
                // Task completed successfully
                // ...
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Task failed with an exception
                // ...
            }
        });
ImageLabelingActivity.java

Примечание. Если вы используете API CameraX, обязательно закройте ImageProxy после завершения работы с ним, например добавив OnCompleteListener в Task, возвращенный методом process. Пример можно найти в классе VisionProcessorBase в кратком руководстве по работе с приложением.

4. Как получить информацию об объектах с ярлыками

Если операция по распознаванию объектов на изображении выполнена успешно, слушателю успешного выполнения передается список объектов ImageLabel. Каждый объект ImageLabel представляет собой то, что было помечено на изображении. Вы можете получить текстовое описание каждой метки, оценку достоверности соответствия и индекс соответствия. Пример:

Kotlin

for (label in labels) {
    val text = label.text
    val confidence = label.confidence
    val index = label.index
}
ImageLabelingActivity.kt

Java

for (ImageLabel label : labels) {
    String text = label.getText();
    float confidence = label.getConfidence();
    int index = label.getIndex();
}
ImageLabelingActivity.java

Советы по повышению эффективности в реальном времени

Если вы хотите помечать изображения в приложении реального времени, следуйте этим рекомендациям, чтобы добиться наилучшей частоты кадров:

• Если вы используете API Camera или camera2, ограничьте количество вызовов к средству добавления ярлыков к изображениям. Если во время работы инструмента для разметки изображений становится доступен новый кадр видео, пропустите его. Пример можно найти в классе VisionProcessorBase краткого руководства по работе с примером приложения.
• Если вы используете API CameraX, убедитесь, что для стратегии противодействия избыточному давлению задано значение по умолчанию ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST. Это гарантирует, что для анализа будет передаваться только одно изображение за раз. Если во время работы анализатора будет создано больше изображений, они будут автоматически удалены и не будут поставлены в очередь на отправку. После того как анализируемое изображение будет закрыто вызовом ImageProxy.close(), будет доставлено следующее последнее изображение.
• Если вы используете результаты распознавания объектов для наложения графики на входное изображение, сначала получите результат от ML Kit, а затем отрисуйте изображение и наложите графику за один шаг. Оно отрисовывается на экране только один раз для каждого входного кадра. Пример можно найти в классах CameraSourcePreview и GraphicOverlay в кратком руководстве по работе с примером приложения.
• Если вы используете Camera2 API, снимайте изображения в формате ImageFormat.YUV_420_888. Если вы используете более раннюю версию Camera API, снимайте изображения в формате ImageFormat.NV21.