在 Android 上使用 ML Kit 為圖片加上標籤

本頁面說明舊版 Image Labeling API，這是 Firebase 專用機器學習套件的一部分。這項 API 的功能已分割為 兩個新的 API (瞭解詳情)：

• 使用裝置 image labeling 屬於新的獨立 ML Kit SDK 的一部分，可與 (或) 搭配使用 沒有 Firebase。
• Cloud image labeling 是 Firebase ML 的一部分，其中包含 Firebase 的所有雲端 ML 功能。

您可以使用 ML Kit 為圖片中辨識出的物件加上標籤， 例如裝置端模型或雲端模式詳情請參閱 總覽，以瞭解 。

使用 ML Kit 存取 Cloud ML 功能時必須遵循 Google Cloud Platform 授權 協議和服務 專屬條款並據此收費。如需帳單資訊，請參閱 Firebase 的「定價」頁面。

事前準備

1. 如果還沒試過 將 Firebase 新增至您的 Android 專案。
2. 將 ML Kit Android 程式庫的依附元件新增至模組 (應用程式層級) 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，請設定 應用程式，在應用程式完成更新後，自動將機器學習模型下載至裝置 安裝

   方法是在應用程式的 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. 開啟 ML Kit Firebase 控制台的 API 頁面。

   2. 如果您尚未將專案升級至 Blaze 定價方案，請按一下 如要這麼做，請升級。(只有在您的 專案並未採用 Blaze 方案)。

      只有 Blaze 層級的專案可以使用以雲端為基礎的 API。

   3. 如果尚未啟用雲端式 API，請按一下「Enable Cloud-based API」(啟用雲端式 API) API
   ，瞭解如何調查及移除這項存取權。
   部署至使用 Cloud API 的正式版應用程式之前，您應先完成 防範及降低 未經授權 API 存取的影響

   如果只想使用裝置端模型，可以略過這個步驟。

您現在可以使用裝置上的模型或 雲端式模型

1. 準備輸入圖片

使用圖片建立 FirebaseVisionImage 物件。 當您使用 Bitmap 或 camera2 API 是 JPEG 格式的 media.Image，建議在

• 要使用 FirebaseVisionImage 物件 media.Image 物件，例如從 裝置的相機，請傳遞 media.Image 物件和圖片的 旋轉至 FirebaseVisionImage.fromMediaImage()。

  如果您使用 CameraX 程式庫、OnImageCapturedListener 和 ImageAnalysis.Analyzer 類別會計算旋轉值 因此只需將旋轉模型 轉換為 ML Kit 的 呼叫前 ROTATION_ 常數 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+KTX

  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+KTX

  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+KTX

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

• 如要從檔案 URI 建立 FirebaseVisionImage 物件，請傳遞 應用程式環境和檔案 URI FirebaseVisionImage.fromFilePath()。如果您要 使用 ACTION_GET_CONTENT 意圖提示使用者選取 取自圖片庫應用程式中的圖片。

  Java

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

  Kotlin+KTX

  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+KTX

  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+KTX

  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+KTX

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

  Bitmap 物件代表的圖片必須 保持直立，不用另外旋轉。

2. 設定並執行映像檔標籤工具

如要為圖片中的物件加上標籤，請將 FirebaseVisionImage 物件傳遞至 FirebaseVisionImageLabeler 的 processImage 方法。

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+KTX

   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+KTX

   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() 方法：

   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+KTX

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

3. 取得加上標籤的物件相關資訊

如果圖片標籤作業成功，系統會顯示 FirebaseVisionImageLabel 物件會傳遞到 成功事件監聽器每個 FirebaseVisionImageLabel 物件都代表一個 預先在圖片中加上標籤的文字您可以看到每個標籤的文字 說明、其 知識圖譜實體 ID 以及比對結果的可信度分數。例如：

Java

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

Kotlin+KTX

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

即時效能改善訣竅

如要在即時應用程式中為圖片加上標籤，請按照下列步驟操作： 實現最佳影格速率：

• 限制對圖片標籤人員的呼叫。如果新的影片影格 請在圖片標籤工具執行期間捨棄頁框。
• 如果您使用圖片標籤人員的輸出內容，將圖像重疊 先從 ML Kit 取得結果，然後算繪圖片 並疊加單一步驟這麼一來，您的應用程式就會算繪到顯示途徑 每個輸入影格只能建立一次

• 如果你使用 Camera2 API， ImageFormat.YUV_420_888 格式。

  如果使用舊版 Camera API，請以 ImageFormat.NV21 格式。

後續步驟

• 部署至使用 Cloud API 的正式版應用程式之前，您應先完成 防範及減少 未經授權 API 存取的影響