Пометка изображений пользовательской моделью на Android

Вы можете использовать ML Kit, чтобы распознавать объекты на изображении и маркировать их. Этот API поддерживает широкий спектр пользовательских моделей классификации изображений. См. Пользовательские модели с комплектом ML , чтобы узнать о требованиях к совместимости моделей, где найти предварительно обученные модели и как обучать собственные модели.

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

	В комплекте	Разделенный
Имя библиотеки	com.google.mlkit:image-labeling-custom	com.google.android.gms:play-services-mlkit-image-labeling-custom
Реализация	Pipeline статически связан с вашим приложением во время сборки.	Pipeline загружается динамически через сервисы Google Play.
Размер приложения	Увеличение размера примерно на 3,8 МБ.	Увеличение размера примерно на 200 КБ.
Время инициализации	Трубопровод доступен сразу.	Возможно, придется дождаться загрузки конвейера перед первым использованием.
Стадия жизненного цикла API	Общая доступность (GA)	Бета

Примечание . Несвязанная версия маркировки изображений с пользовательскими моделями в настоящее время предлагается в бета-версии, что означает, что она может быть изменена несовместимыми с предыдущими способами и не подлежит никакому соглашению об уровне обслуживания или политике устаревания.

Существует два способа интеграции пользовательской модели: связать модель, поместив ее в папку ресурсов вашего приложения, или динамически загрузить ее из Firebase. В следующей таблице сравниваются эти два варианта.

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

Попробуйте

• См. приложение быстрого запуска Vision для примера использования связанной модели и приложение быстрого запуска automl для примера использования размещенной модели.

Прежде чем вы начнете

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

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

   Для связывания конвейера с вашим приложением:

   dependencies {
     // ...
     // Use this dependency to bundle the pipeline with your app
     implementation 'com.google.mlkit:image-labeling-custom:17.0.1'
   }
   

   Для использования конвейера в сервисах Google Play:

   dependencies {
     // ...
     // Use this dependency to use the dynamically downloaded pipeline in Google Play Services
     implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta4'
   }
   

3. Если вы решите использовать конвейер в Сервисах Google Play , вы можете настроить свое приложение для автоматической загрузки конвейера на устройство после установки приложения из Play Store. Для этого добавьте следующее объявление в файл AndroidManifest.xml вашего приложения:

   <application ...>
       ...
       <meta-data
           android:name="com.google.mlkit.vision.DEPENDENCIES"
           android:value="custom_ica" />
       <!-- To use multiple downloads: android:value="custom_ica,download2,download3" -->
   </application>
   

   Вы также можете явно проверить доступность пайплайна и запросить загрузку через ModuleInstallClient API сервисов Google Play.

   Если вы не включаете загрузку конвейера во время установки или не запрашиваете явную загрузку, конвейер загружается при первом запуске средства маркировки. Запросы, которые вы делаете до завершения загрузки, не дают результатов.

4. Добавьте зависимость linkFirebase , если вы хотите динамически загружать модель из Firebase:

   Для динамической загрузки модели из Firebase добавьте зависимость linkFirebase :

   dependencies {
     // ...
     // Image labeling feature with model downloaded from Firebase
     implementation 'com.google.mlkit:image-labeling-custom:17.0.1'
     // Or use the dynamically downloaded pipeline in Google Play Services
     // implementation 'com.google.android.gms:play-services-mlkit-image-labeling-custom:16.0.0-beta4'
     implementation 'com.google.mlkit:linkfirebase:17.0.0'
   }
   

5. Если вы хотите загрузить модель , убедитесь, что вы добавили Firebase в свой проект Android , если вы еще этого не сделали. Это не требуется, когда вы связываете модель.

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

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

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

1. Скопируйте файл модели (обычно заканчивающийся на .tflite или .lite ) в папку assets/ вашего приложения. (Возможно, вам потребуется сначала создать папку, щелкнув правой кнопкой мыши app/ папку, а затем выбрав « Создать» > «Папка» > «Папка активов» .)

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

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

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

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

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

   Котлин

   val localModel = LocalModel.Builder()
           .setAssetFilePath("model.tflite")
           // or .setAbsoluteFilePath(absolute file path to model file)
           // or .setUri(URI to model file)
           .build()

   Джава

   LocalModel localModel =
       new LocalModel.Builder()
           .setAssetFilePath("model.tflite")
           // or .setAbsoluteFilePath(absolute file path to model file)
           // or .setUri(URI to model file)
           .build();

   Примечание: приложения, предназначенные для Android 11 (уровень API 30), больше не могут получать доступ к файлам из внешнего хранилища из-за обновлений хранилища в Android 11 .
   Примечание. Если у вас есть модель, обученная с помощью AutoML Vision Edge в Firebase (не в Google Cloud), описанное выше может не работать. Следуйте инструкциям в руководстве по миграции .

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

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

Котлин

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

Джава

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

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

Котлин

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

Джава

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

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

Настройте этикетировщик изображений

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

Доступны следующие варианты:

Опции
confidenceThreshold	Минимальная оценка достоверности обнаруженных меток. Если не задано, будет использоваться любой порог классификатора, указанный в метаданных модели. Если модель не содержит метаданных или метаданные не определяют пороговое значение классификатора, будет использоваться пороговое значение по умолчанию, равное 0,0.
maxResultCount	Максимальное количество возвращаемых ярлыков. Если не установлено, будет использоваться значение по умолчанию 10.

Если у вас есть только локально связанная модель, просто создайте метку из вашего объекта LocalModel :

Котлин

val customImageLabelerOptions = CustomImageLabelerOptions.Builder(localModel)
    .setConfidenceThreshold(0.5f)
    .setMaxResultCount(5)
    .build()
val labeler = ImageLabeling.getClient(customImageLabelerOptions)

Джава

CustomImageLabelerOptions customImageLabelerOptions =
        new CustomImageLabelerOptions.Builder(localModel)
            .setConfidenceThreshold(0.5f)
            .setMaxResultCount(5)
            .build();
ImageLabeler labeler = ImageLabeling.getClient(customImageLabelerOptions);

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

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

Котлин

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
    .addOnSuccessListener { isDownloaded ->
    val optionsBuilder =
        if (isDownloaded) {
            CustomImageLabelerOptions.Builder(remoteModel)
        } else {
            CustomImageLabelerOptions.Builder(localModel)
        }
    val options = optionsBuilder
                  .setConfidenceThreshold(0.5f)
                  .setMaxResultCount(5)
                  .build()
    val labeler = ImageLabeling.getClient(options)
}

Джава

RemoteModelManager.getInstance().isModelDownloaded(remoteModel)
        .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(Boolean isDownloaded) {
                CustomImageLabelerOptions.Builder optionsBuilder;
                if (isDownloaded) {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(remoteModel);
                } else {
                    optionsBuilder = new CustomImageLabelerOptions.Builder(localModel);
                }
                CustomImageLabelerOptions options = optionsBuilder
                    .setConfidenceThreshold(0.5f)
                    .setMaxResultCount(5)
                    .build();
                ImageLabeler labeler = ImageLabeling.getClient(options);
            }
        });

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

Котлин

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.
    }

Джава

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 вычисляют для вас значение поворота.

Котлин

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
            // ...
        }
    }
}

Джава

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
          // ...
        }
    }
}

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

Котлин

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

Джава

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() :

Котлин

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

Java

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

Использование URI файла

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

Котлин

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 с буфером или массивом вместе с высотой изображения, шириной, форматом кодирования цвета и степенью поворота:

Котлин

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

Джава

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 , сделайте следующее объявление:

Котлин

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

Java

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

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

3. Запустите этикетировщик изображений

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

Котлин

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

Джава

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

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

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

Если операция маркировки изображения завершается успешно, прослушивателю успеха передается список объектов ImageLabel . Каждый объект ImageLabel представляет что-то, что было помечено на изображении. Вы можете получить текстовое описание каждой метки (если оно доступно в метаданных файла модели TensorFlow Lite), показатель достоверности и индекс. Например:

Котлин

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

Джава

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

Примечание. Если вы используете модель TensorFlow Lite, несовместимую с ML Kit, вы получите MlKitException с кодом ошибки MlKitException#INVALID_ARGUMENT и некоторыми сведениями о том, почему оно несовместимо. Дополнительные сведения см. в разделе Требования к совместимости пользовательских моделей .

Советы по улучшению производительности в реальном времени

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

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