本頁面由 Cloud Translation API 翻譯而成。

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

您可以使用 Firebase ML 為圖片中辨識出的物件加上標籤。詳情請參閱總覽，進一步瞭解這個 API 接著介紹網際網路通訊層包括兩項主要的安全防護功能

，瞭解如何調查及移除這項存取權。

事前準備

如果還沒試過將 Firebase 新增至您的 Android 專案。
在模組 (應用程式層級) Gradle 檔案中 (通常為 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle)、為 Android 專用的 Firebase ML Vision 程式庫新增依附元件。建議您使用 Firebase Android BoM敬上管理程式庫版本管理
```
dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.3.0"))

    // Add the dependency for the Firebase ML Vision library
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-ml-vision'
}
```
只要使用 Firebase Android BoM，應用程式一律會使用相容的 Firebase Android 程式庫版本。
(替代做法) 新增 Firebase 程式庫依附元件，「不使用」 BoM

如果選擇不使用 Firebase BoM，請指定各個 Firebase 程式庫版本都屬於依附元件行

請注意，如果您在應用程式中使用多個 Firebase 程式庫，強烈建議您建議使用 BoM 管理程式庫版本，確保所有版本相容。
```
dependencies {
    // Add the dependency for the Firebase ML Vision library
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation 'com.google.firebase:firebase-ml-vision:24.1.0'
}
```
敬上
在尋找 Kotlin 專用的程式庫模組嗎？距離開始還有 2023 年 10 月 (Firebase BoM 32.5.0)，Kotlin 和 Java 開發人員皆可依附於主要程式庫模組 (詳情請參閱這項計畫的常見問題)。
如果您尚未為專案啟用雲端式 API，請先啟用現在：
1. 開啟 Firebase ML Firebase 控制台的 API 頁面。
2. 如果您尚未將專案升級至 Blaze 定價方案，請按一下如要這麼做，請升級。(只有在您的專案並未採用 Blaze 方案)。
  
  只有 Blaze 層級的專案可以使用以雲端為基礎的 API。
3. 如果尚未啟用雲端式 API，請按一下「Enable Cloud-based API」(啟用雲端式 API) API
，瞭解如何調查及移除這項存取權。
部署至使用 Cloud API 的正式版應用程式之前，您應先完成防範及降低

您現在可以開始為圖片加上標籤。

1. 準備輸入圖片

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

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

如果您使用 CameraX 程式庫、OnImageCapturedListener 和 ImageAnalysis.Analyzer 類別會計算旋轉值因此，您只需將旋轉角度轉換為 Firebase ML 的呼叫前 ROTATION_ 常數 FirebaseVisionImage.fromMediaImage():

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

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

如果您沒有使用相機程式庫來提供圖像旋轉角度，可根據裝置旋轉角度和相機方向計算感應器：

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

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

然後，請傳遞 media.Image 物件和將旋轉值轉換為 FirebaseVisionImage.fromMediaImage()：

Kotlin+KTX

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

Java

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

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

Kotlin+KTX

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

Java

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

要使用 FirebaseVisionImage 物件 ByteBuffer 或位元組陣列，請先計算圖片旋轉 (方法如上所述) media.Image 輸入欄位。

接著建立 FirebaseVisionImageMetadata 物件包含圖片的高度、寬度、色彩編碼格式和輪替金鑰

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

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

使用緩衝區或陣列和中繼資料物件 FirebaseVisionImage 物件：

Kotlin+KTX

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

Java

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

要使用 FirebaseVisionImage 物件 Bitmap 物件：

Kotlin+KTX

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

Java

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

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

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

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

首先，請取得 FirebaseVisionImageLabeler。

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)

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);

接著，將圖片傳遞至 processImage() 方法：

Kotlin+KTX

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

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

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

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

Kotlin+KTX

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

Java

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

後續步驟

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