Помечайте изображения с помощью ML Kit на Android, Помечайте изображения с помощью ML Kit на Android

На этой странице описана старая версия Image Labeling API, который был частью ML Kit для Firebase. Функциональность этого API была разделена на два новых API ( подробнее ):

• На устройстве image labeling является частью нового автономного SDK ML Kit, который вы можете использовать с Firebase или без него.
• Облако image labeling является частью Firebase ML , который включает в себя все функции облачного машинного обучения Firebase.

Вы можете использовать ML Kit для маркировки объектов, распознанных на изображении, используя модель на устройстве или облачную модель. Ознакомьтесь с обзором , чтобы узнать о преимуществах каждого подхода.

Использование ML Kit для доступа к функциям Cloud ML регулируется Лицензионным соглашением Google Cloud Platform и Условиями использования отдельных услуг и взимается соответствующая плата. Информацию о выставлении счетов см. на странице цен на Firebase.

Прежде чем начать

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

   apply plugin: 'com.android.application'
   apply plugin: 'com.google.gms.google-services'
   
   dependencies {
     // ...
   
     implementation 'com.google.firebase:firebase-ml-vision:24.0.3'
     implementation 'com.google.firebase:firebase-ml-vision-image-label-model:20.0.1'
   }

3. Необязательно, но рекомендуется : если вы используете API на устройстве, настройте свое приложение для автоматической загрузки модели ML на устройство после установки приложения из Play Store.

   Для этого добавьте следующее объявление в файл AndroidManifest.xml вашего приложения:

   <application ...>
     ...
     <meta-data
         android:name="com.google.firebase.ml.vision.DEPENDENCIES"
         android:value="label" />
     <!-- To use multiple models: android:value="label,model2,model3" -->
   </application>

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

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

   1. Откройте страницу API ML Kit в консоли Firebase .

   2. Если вы еще не обновили свой проект до тарифного плана Blaze, нажмите «Обновить», чтобы сделать это. (Вам будет предложено выполнить обновление, только если ваш проект не входит в план Blaze.)

      Только проекты уровня Blaze могут использовать облачные API.

   3. Если облачные API еще не включены, нажмите «Включить облачные API» .
   Прежде чем развернуть в рабочей среде приложение, использующее Cloud API, вам следует предпринять некоторые дополнительные действия, чтобы предотвратить и смягчить последствия несанкционированного доступа к API .

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

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

1. Подготовьте входное изображение

Создайте объект FirebaseVisionImage из вашего изображения. Средство разметки изображений работает быстрее всего, если вы используете Bitmap или, если вы используете API camera2, media.Image в формате JPEG, что рекомендуется, когда это возможно.

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

  Если вы используете библиотеку CameraX , классы OnImageCapturedListener и ImageAnalysis.Analyzer вычисляют значение поворота за вас, поэтому вам просто нужно преобразовать поворот в одну из констант ROTATION_ ML Kit перед вызовом FirebaseVisionImage.fromMediaImage() :

  Java

  private class YourAnalyzer implements ImageAnalysis.Analyzer {
  
      private int degreesToFirebaseRotation(int degrees) {
          switch (degrees) {
              case 0:
                  return FirebaseVisionImageMetadata.ROTATION_0;
              case 90:
                  return FirebaseVisionImageMetadata.ROTATION_90;
              case 180:
                  return FirebaseVisionImageMetadata.ROTATION_180;
              case 270:
                  return FirebaseVisionImageMetadata.ROTATION_270;
              default:
                  throw new IllegalArgumentException(
                          "Rotation must be 0, 90, 180, or 270.");
          }
      }
  
      @Override
      public void analyze(ImageProxy imageProxy, int degrees) {
          if (imageProxy == null || imageProxy.getImage() == null) {
              return;
          }
          Image mediaImage = imageProxy.getImage();
          int rotation = degreesToFirebaseRotation(degrees);
          FirebaseVisionImage image =
                  FirebaseVisionImage.fromMediaImage(mediaImage, rotation);
          // Pass image to an ML Kit Vision API
          // ...
      }
  }

  Kotlin

  private class YourImageAnalyzer : ImageAnalysis.Analyzer {
      private fun degreesToFirebaseRotation(degrees: Int): Int = when(degrees) {
          0 -> FirebaseVisionImageMetadata.ROTATION_0
          90 -> FirebaseVisionImageMetadata.ROTATION_90
          180 -> FirebaseVisionImageMetadata.ROTATION_180
          270 -> FirebaseVisionImageMetadata.ROTATION_270
          else -> throw Exception("Rotation must be 0, 90, 180, or 270.")
      }
  
      override fun analyze(imageProxy: ImageProxy?, degrees: Int) {
          val mediaImage = imageProxy?.image
          val imageRotation = degreesToFirebaseRotation(degrees)
          if (mediaImage != null) {
              val image = FirebaseVisionImage.fromMediaImage(mediaImage, imageRotation)
              // Pass image to an ML Kit Vision API
              // ...
          }
      }
  }

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

  Java

  private static final SparseIntArray ORIENTATIONS = new SparseIntArray();
  static {
      ORIENTATIONS.append(Surface.ROTATION_0, 90);
      ORIENTATIONS.append(Surface.ROTATION_90, 0);
      ORIENTATIONS.append(Surface.ROTATION_180, 270);
      ORIENTATIONS.append(Surface.ROTATION_270, 180);
  }
  
  /**
   * 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, Context context)
          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);
  
      // On most devices, the sensor orientation is 90 degrees, but for some
      // devices it is 270 degrees. For devices with a sensor orientation of
      // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
      CameraManager cameraManager = (CameraManager) context.getSystemService(CAMERA_SERVICE);
      int sensorOrientation = cameraManager
              .getCameraCharacteristics(cameraId)
              .get(CameraCharacteristics.SENSOR_ORIENTATION);
      rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360;
  
      // Return the corresponding FirebaseVisionImageMetadata rotation value.
      int result;
      switch (rotationCompensation) {
          case 0:
              result = FirebaseVisionImageMetadata.ROTATION_0;
              break;
          case 90:
              result = FirebaseVisionImageMetadata.ROTATION_90;
              break;
          case 180:
              result = FirebaseVisionImageMetadata.ROTATION_180;
              break;
          case 270:
              result = FirebaseVisionImageMetadata.ROTATION_270;
              break;
          default:
              result = FirebaseVisionImageMetadata.ROTATION_0;
              Log.e(TAG, "Bad rotation value: " + rotationCompensation);
      }
      return result;
  }
  VisionImage.java

  Kotlin

  private val ORIENTATIONS = SparseIntArray()
  
  init {
      ORIENTATIONS.append(Surface.ROTATION_0, 90)
      ORIENTATIONS.append(Surface.ROTATION_90, 0)
      ORIENTATIONS.append(Surface.ROTATION_180, 270)
      ORIENTATIONS.append(Surface.ROTATION_270, 180)
  }
  /**
   * 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, context: Context): 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)
  
      // On most devices, the sensor orientation is 90 degrees, but for some
      // devices it is 270 degrees. For devices with a sensor orientation of
      // 270, rotate the image an additional 180 ((270 + 270) % 360) degrees.
      val cameraManager = context.getSystemService(CAMERA_SERVICE) as CameraManager
      val sensorOrientation = cameraManager
              .getCameraCharacteristics(cameraId)
              .get(CameraCharacteristics.SENSOR_ORIENTATION)!!
      rotationCompensation = (rotationCompensation + sensorOrientation + 270) % 360
  
      // Return the corresponding FirebaseVisionImageMetadata rotation value.
      val result: Int
      when (rotationCompensation) {
          0 -> result = FirebaseVisionImageMetadata.ROTATION_0
          90 -> result = FirebaseVisionImageMetadata.ROTATION_90
          180 -> result = FirebaseVisionImageMetadata.ROTATION_180
          270 -> result = FirebaseVisionImageMetadata.ROTATION_270
          else -> {
              result = FirebaseVisionImageMetadata.ROTATION_0
              Log.e(TAG, "Bad rotation value: $rotationCompensation")
          }
      }
      return result
  }
  VisionImage.kt

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

  Java

  FirebaseVisionImage image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation);
  VisionImage.java

  Kotlin

  val image = FirebaseVisionImage.fromMediaImage(mediaImage, rotation)
  VisionImage.kt

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

  Java

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

  Kotlin

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

• Чтобы создать объект FirebaseVisionImage из ByteBuffer или массива байтов, сначала рассчитайте поворот изображения, как описано выше для ввода media.Image .

  Затем создайте объект FirebaseVisionImageMetadata , который содержит высоту, ширину изображения, формат цветовой кодировки и поворот:

  Java

  FirebaseVisionImageMetadata metadata = new FirebaseVisionImageMetadata.Builder()
          .setWidth(480)   // 480x360 is typically sufficient for
          .setHeight(360)  // image recognition
          .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
          .setRotation(rotation)
          .build();
  VisionImage.java

  Kotlin

  val metadata = FirebaseVisionImageMetadata.Builder()
          .setWidth(480) // 480x360 is typically sufficient for
          .setHeight(360) // image recognition
          .setFormat(FirebaseVisionImageMetadata.IMAGE_FORMAT_NV21)
          .setRotation(rotation)
          .build()
  VisionImage.kt

  Используйте буфер или массив и объект метаданных для создания объекта FirebaseVisionImage :

  Java

  FirebaseVisionImage image = FirebaseVisionImage.fromByteBuffer(buffer, metadata);
  // Or: FirebaseVisionImage image = FirebaseVisionImage.fromByteArray(byteArray, metadata);
  VisionImage.java

  Kotlin

  val image = FirebaseVisionImage.fromByteBuffer(buffer, metadata)
  // Or: val image = FirebaseVisionImage.fromByteArray(byteArray, metadata)
  VisionImage.kt

• Чтобы создать объект FirebaseVisionImage из объекта Bitmap :

  Java

  FirebaseVisionImage image = FirebaseVisionImage.fromBitmap(bitmap);
  VisionImage.java

  Kotlin

  val image = FirebaseVisionImage.fromBitmap(bitmap)
  VisionImage.kt

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

2. Настройте и запустите средство разметки изображений.

Чтобы пометить объекты на изображении, передайте объект FirebaseVisionImage методу processImage FirebaseVisionImageLabeler .

1. Сначала получите экземпляр FirebaseVisionImageLabeler .

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

   Java

   FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
       .getOnDeviceImageLabeler();
   
   // Or, to set the minimum confidence required:
   // FirebaseVisionOnDeviceImageLabelerOptions options =
   //     new FirebaseVisionOnDeviceImageLabelerOptions.Builder()
   //         .setConfidenceThreshold(0.7f)
   //         .build();
   // FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
   //     .getOnDeviceImageLabeler(options);
   

   Kotlin

   val labeler = FirebaseVision.getInstance().getOnDeviceImageLabeler()
   
   // Or, to set the minimum confidence required:
   // val options = FirebaseVisionOnDeviceImageLabelerOptions.Builder()
   //     .setConfidenceThreshold(0.7f)
   //     .build()
   // val labeler = FirebaseVision.getInstance().getOnDeviceImageLabeler(options)
   

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

   Java

   FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
       .getCloudImageLabeler();
   
   // Or, to set the minimum confidence required:
   // FirebaseVisionCloudImageLabelerOptions options =
   //     new FirebaseVisionCloudImageLabelerOptions.Builder()
   //         .setConfidenceThreshold(0.7f)
   //         .build();
   // FirebaseVisionImageLabeler labeler = FirebaseVision.getInstance()
   //     .getCloudImageLabeler(options);
   

   Kotlin

   val labeler = FirebaseVision.getInstance().getCloudImageLabeler()
   
   // Or, to set the minimum confidence required:
   // val options = FirebaseVisionCloudImageLabelerOptions.Builder()
   //     .setConfidenceThreshold(0.7f)
   //     .build()
   // val labeler = FirebaseVision.getInstance().getCloudImageLabeler(options)
   

2. Затем передайте изображение методуprocessImage processImage() :

   Java

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

   Kotlin

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

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

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

Java

for (FirebaseVisionImageLabel label: labels) {
  String text = label.getText();
  String entityId = label.getEntityId();
  float confidence = label.getConfidence();
}

Kotlin

for (label in labels) {
  val text = label.text
  val entityId = label.entityId
  val confidence = label.confidence
}

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

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

• Регулирование вызовов средства разметки изображений. Если новый видеокадр становится доступным во время работы средства разметки изображений, удалите этот кадр.
• Если вы используете выходные данные средства разметки изображений для наложения графики на входное изображение, сначала получите результат из ML Kit, затем визуализируйте изображение и наложите его за один шаг. При этом вы выполняете рендеринг на поверхность дисплея только один раз для каждого входного кадра.

• Если вы используете API Camera2, захватывайте изображения в формате ImageFormat.YUV_420_888 .

  Если вы используете более старый API камеры, захватывайте изображения в формате ImageFormat.NV21 .

Следующие шаги

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