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

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

你可以使用 ML Kit 為圖片中辨識的物體加上標籤。ML Kit 提供的預設模型支援超過 400 個不同標籤。

功能	未分類	組合
導入作業	模型會透過 Google Play 服務動態下載。	模型在建構期間會以靜態方式連結至您的。
應用程式大小	大小增加約 200 KB。	大小增加約 5.7 MB。
初始化時間	可能需要等待模型下載完成才能開始使用。	模型可立即使用

立即體驗

試試範例應用程式，查看這個 API 的使用範例。

事前準備

這個 API 需要 Android API 級別 21 以上版本。請確認應用程式的版本檔案使用 21 以上的 minSdkVersion 值。

在專案層級的 build.gradle 檔案中，請務必在 buildscript 和 allprojects 區段中加入 Google 的 Maven 存放區。

將 ML Kit Android 程式庫的依附元件新增至模組的應用程式層級 Gradle 檔案 (通常為 app/build.gradle)。請根據您的需求選擇下列其中一種依附元件：

如要組合模型與應用程式：

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

在 Google Play 服務中使用模型的方式如下：

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

如果您選擇在 Google Play 服務中使用模型，可以設定應用程式在從 Play 商店安裝應用程式後，自動將模型下載到裝置上。為此，請在應用程式的 AndroidManifest.xml 檔案中新增下列宣告：
```
<application ...>
      ...
      <meta-data
          android:name="com.google.mlkit.vision.DEPENDENCIES"
          android:value="ica" >
      
</application>
```
您也可以明確確認模型的可用性，並透過 Google Play 服務 ModuleInstallClient API 要求下載。

如未啟用安裝期間模型下載功能或要求明確下載，系統會在您首次執行標籤工具時下載模型。在下載完成之前提出的要求不會產生任何結果。

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

1. 準備輸入圖片

從圖片建立 InputImage 物件。使用 Bitmap 時，圖片標籤器的執行速度最快；如果使用的是 camera2 API，則為 YUV_420_888 media.Image，建議您盡可能使用。

您可以從不同來源建立 InputImage 物件，以下說明每種來源。

使用 `media.Image`

如要從 media.Image 物件建立 InputImage 物件 (例如從裝置相機拍攝圖片)，請將 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

如要從檔案 URI 建立 InputImage 物件，請將應用程式結構定義和檔案 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`

如要使用 ByteBuffer 或 ByteArray 建立 InputImage 物件，請先按照先前針對 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`

如要透過 Bitmap 物件建立 InputImage 物件，請建立下列宣告：

Kotlin

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

Java

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

圖片是由 Bitmap 物件以旋轉度表示。

2. 設定並執行圖片標籤工具

如要為圖片中的物件加上標籤，請將 InputImage 物件傳遞至 ImageLabeler 的 process 方法。

首先，請取得 ImageLabeler 的例項。

如要使用裝置端圖片標籤器，請進行以下宣告：

Kotlin

// To use default options:
val labeler = ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS)

// Or, to set the minimum confidence required:
// val options = ImageLabelerOptions.Builder()
//     .setConfidenceThreshold(0.7f)
//     .build()
// val labeler = ImageLabeling.getClient(options)
ImageLabelingActivity.kt

Java

// To use default options:
ImageLabeler labeler = ImageLabeling.getClient(ImageLabelerOptions.DEFAULT_OPTIONS);

// Or, to set the minimum confidence required:
// ImageLabelerOptions options =
//     new ImageLabelerOptions.Builder()
//         .setConfidenceThreshold(0.7f)
//         .build();
// ImageLabeler labeler = ImageLabeling.getClient(options);
ImageLabelingActivity.java

然後，將圖片傳遞至 process() 方法：

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

注意：如果您使用 CameraX API，請務必在使用完畢後關閉 ImageProxy，例如將 OnCompleteListener 新增至透過 process 方法傳回的 Task。如需範例，請參閱快速入門導覽課程範例應用程式中的 VisionProcessorBase 類別。

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

如果圖片標籤作業成功，系統會將 ImageLabel 物件清單傳遞至成功事件監聽器。每個 ImageLabel 物件都代表在圖片中加上標籤的項目。基本模型支援超過 400 個不同的標籤。您可以取得每個標籤的文字說明、模型支援的所有標籤索引，以及相符項目的可信度分數。例如：

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

改善即時成效的訣竅

如要在即時應用程式中為圖片加上標籤，請按照下列指南操作，以達到最佳影格速率：

如果使用 Camera 或 camera2 API，請限制對圖片標籤器的呼叫。如果圖片標籤人員執行期間有新的影片影格，請捨棄影格。如需範例，請參閱快速入門導覽課程範例應用程式中的 VisionProcessorBase 類別。
如果您使用 CameraX API，請務必將背壓策略設為預設值 ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST。這項功能可確保一次只會傳送一張圖片進行分析。如果分析器忙碌時生成更多圖片，圖片會自動捨棄，不會排入傳送佇列。呼叫 ImageProxy.close() 來關閉要分析的映像檔後，就會傳送下一個映像檔。
如果使用圖片標籤工具的輸出內容，將圖像疊加在輸入圖片上，請先透過 ML Kit 取得結果，然後透過單一步驟算繪圖片和疊加層。這只會針對每個輸入影格算繪至螢幕介面一次。如需範例，請參閱快速入門導覽課程範例應用程式中的 CameraSourcePreview 和 GraphicOverlay 類別。
如果您使用 Camera2 API，請擷取 ImageFormat.YUV_420_888 格式的圖片。如果使用舊版 Camera API，請拍攝 ImageFormat.NV21 格式的圖片。

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

立即體驗

事前準備

1. 準備輸入圖片

使用 media.Image

Kotlin

Java

Kotlin

Java

Kotlin

Java

使用檔案 URI

Kotlin

Java

使用 ByteBuffer 或 ByteArray

Kotlin

Java

使用 Bitmap

Kotlin

Java

2. 設定並執行圖片標籤工具

Kotlin

Java

Kotlin

Java

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

Kotlin

Java

改善即時成效的訣竅

使用 `media.Image`

使用 `ByteBuffer` 或 `ByteArray`

使用 `Bitmap`