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

使用適用於 Android 的 ML Kit 區隔主題區隔

使用 ML Kit，輕鬆在應用程式中加入主體區隔功能。

功能	詳細資料
SDK 名稱	play-services-mlkit-subject-segmentation
導入作業	未封裝：模型是使用 Google Play 服務動態下載。
應用程式大小影響	大小增加約 200 KB。
初始化時間	使用者可能要等待模型下載完畢，再開始使用該模型。

立即試用

使用範例應用程式試試請查看此 API 的使用範例。

事前準備

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

在專案層級的 build.gradle 檔案中，請務必在 buildscript 和 allprojects 區段中納入 Google 的 Maven 存放區。
將 ML Kit 主體區隔程式庫的依附元件新增至模組的應用程式層級 Gradle 檔案，通常為 app/build.gradle：

dependencies {
   implementation 'com.google.android.gms:play-services-mlkit-subject-segmentation:16.0.0-beta1'
}

如上所述，模型是由 Google Play 服務提供。您可以設定應用程式，自動將模型下載到裝置使用者從 Play 商店安裝應用程式後若要執行此操作，請新增下列程式碼新增至應用程式的 AndroidManifest.xml 檔案：

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

您也可以透過 ModuleInstallClient API 明確檢查型號是否可用，並要求透過 Google Play 服務下載。

未啟用安裝期間模型下載功能或要求明確下載模型會在您初次執行區隔器時下載您提出的要求就無法取得任何結果。

1. 準備輸入圖片

如要對圖片執行區隔，請建立 InputImage 物件從 Bitmap、media.Image、ByteBuffer、位元組陣列或裝置。

您可以建立InputImage 不同來源的 ANR 物件，說明如下。

使用 `media.Image`

如要建立InputImage 物件，例如從 media.Image 物件擷取圖片裝置的相機，請傳遞 media.Image 物件和映像檔的旋轉為 InputImage.fromMediaImage()。

如果您使用 CameraX 程式庫、OnImageCapturedListener 和 ImageAnalysis.Analyzer 類別會計算旋轉值不必確保憑證管理是否適當因為 Google Cloud 會為您管理安全性

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

如要建立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`

如要建立InputImage ByteBuffer 或 ByteArray 的物件，請先計算圖片與先前 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`

如要建立InputImage 物件中，Bitmap 物件，請做出以下宣告：

Kotlin

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

Java

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

圖像以 Bitmap 物件和旋轉角度表示。

2. 建立 SubjectSegmenter 例項

定義區隔選項

如要區隔圖片，請先建立 SubjectSegmenterOptions 的執行個體，做為追蹤：

Kotlin

val options = SubjectSegmenterOptions.Builder()
       // enable options
       .build()

Java

SubjectSegmenterOptions options = new SubjectSegmenterOptions.Builder()
        // enable options
        .build();

每個選項的詳細資訊如下：

前景可信度遮罩

前景可信度遮罩可區分前景主體和背景工作。

呼叫選項中的 enableForegroundConfidenceMask() 以便稍後擷取前景遮罩，方法是呼叫 getForegroundMask()，處理圖片後傳回 SubjectSegmentationResult 物件。

Kotlin

val options = SubjectSegmenterOptions.Builder()
        .enableForegroundConfidenceMask()
        .build()

Java

SubjectSegmenterOptions options = new SubjectSegmenterOptions.Builder()
        .enableForegroundConfidenceMask()
        .build();

前景點陣圖

同樣地，您也可以取得前景主題的點陣圖。

呼叫選項中的 enableForegroundBitmap() 以便稍後擷取在前景點陣圖上呼叫 getForegroundBitmap() 處理圖片後傳回 SubjectSegmentationResult 物件。

Kotlin

val options = SubjectSegmenterOptions.Builder()
        .enableForegroundBitmap()
        .build()

Java

SubjectSegmenterOptions options = new SubjectSegmenterOptions.Builder()
        .enableForegroundBitmap()
        .build();

多重主體的可信度遮罩

如同前景選項，您可以使用 SubjectResultOptions 啟用每個前景主體的可信度遮罩如下：

Kotlin

val subjectResultOptions = SubjectSegmenterOptions.SubjectResultOptions.Builder()
    .enableConfidenceMask()
    .build()

val options = SubjectSegmenterOptions.Builder()
    .enableMultipleSubjects(subjectResultOptions)
    .build()

Java

SubjectResultOptions subjectResultOptions =
        new SubjectSegmenterOptions.SubjectResultOptions.Builder()
            .enableConfidenceMask()
            .build()

SubjectSegmenterOptions options = new SubjectSegmenterOptions.Builder()
      .enableMultipleSubjects(subjectResultOptions)
      .build()

多主體點陣圖

同樣地，您也可以為每個主題啟用點陣圖：

Kotlin

val subjectResultOptions = SubjectSegmenterOptions.SubjectResultOptions.Builder()
    .enableSubjectBitmap()
    .build()

val options = SubjectSegmenterOptions.Builder()
    .enableMultipleSubjects(subjectResultOptions)
    .build()

Java

SubjectResultOptions subjectResultOptions =
      new SubjectSegmenterOptions.SubjectResultOptions.Builder()
        .enableSubjectBitmap()
        .build()

SubjectSegmenterOptions options = new SubjectSegmenterOptions.Builder()
      .enableMultipleSubjects(subjectResultOptions)
      .build()

建立主題片段

指定 SubjectSegmenterOptions 選項後，請建立 SubjectSegmenter 執行個體呼叫 getClient()，並將選項做為參數：

Kotlin

val segmenter = SubjectSegmentation.getClient(options)

Java

SubjectSegmenter segmenter = SubjectSegmentation.getClient(options);

3. 處理圖片

傳遞事先準備的 InputImage 新增至 SubjectSegmenter 的 process 方法：

Kotlin

segmenter.process(inputImage)
    .addOnSuccessListener { result ->
        // Task completed successfully
        // ...
    }
    .addOnFailureListener { e ->
        // Task failed with an exception
        // ...
    }

Java

segmenter.process(inputImage)
    .addOnSuccessListener(new OnSuccessListener() {
            @Override
            public void onSuccess(SubjectSegmentationResult result) {
                // Task completed successfully
                // ...
            }
        })
        .addOnFailureListener(new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                // Task failed with an exception
                // ...
            }
        });

4. 取得主體區隔結果

擷取前景遮罩和點陣圖

處理完畢後，您可以擷取圖片呼叫的前景遮罩 getForegroundConfidenceMask()，如下所示：

Kotlin

val colors = IntArray(image.width * image.height)

val foregroundMask = result.foregroundConfidenceMask
for (i in 0 until image.width * image.height) {
  if (foregroundMask[i] > 0.5f) {
    colors[i] = Color.argb(128, 255, 0, 255)
  }
}

val bitmapMask = Bitmap.createBitmap(
  colors, image.width, image.height, Bitmap.Config.ARGB_8888
)

Java

int[] colors = new int[image.getWidth() * image.getHeight()];

FloatBuffer foregroundMask = result.getForegroundConfidenceMask();
for (int i = 0; i < image.getWidth() * image.getHeight(); i++) {
  if (foregroundMask.get() > 0.5f) {
    colors[i] = Color.argb(128, 255, 0, 255);
  }
}

Bitmap bitmapMask = Bitmap.createBitmap(
      colors, image.getWidth(), image.getHeight(), Bitmap.Config.ARGB_8888
);

您也可以透過呼叫 getForegroundBitmap() 擷取圖片前景的點陣圖：

Kotlin

val foregroundBitmap = result.foregroundBitmap

Java

Bitmap foregroundBitmap = result.getForegroundBitmap();

擷取每個主題的遮罩和點陣圖

同樣地，您也可以呼叫每個主旨的getConfidenceMask()，如下所示：

Kotlin

val subjects = result.subjects

val colors = IntArray(image.width * image.height)
for (subject in subjects) {
  val mask = subject.confidenceMask
  for (i in 0 until subject.width * subject.height) {
    val confidence = mask[i]
    if (confidence > 0.5f) {
      colors[image.width * (subject.startY - 1) + subject.startX] =
          Color.argb(128, 255, 0, 255)
    }
  }
}

val bitmapMask = Bitmap.createBitmap(
  colors, image.width, image.height, Bitmap.Config.ARGB_8888
)

Java

List subjects = result.getSubjects();

int[] colors = new int[image.getWidth() * image.getHeight()];
for (Subject subject : subjects) {
  FloatBuffer mask = subject.getConfidenceMask();
  for (int i = 0; i < subject.getWidth() * subject.getHeight(); i++) {
    float confidence = mask.get();
    if (confidence > 0.5f) {
      colors[width * (subject.getStartY() - 1) + subject.getStartX()]
          = Color.argb(128, 255, 0, 255);
    }
  }
}

Bitmap bitmapMask = Bitmap.createBitmap(
  colors, image.width, image.height, Bitmap.Config.ARGB_8888
);

您也可以按照下列步驟存取每個區隔主題的點陣圖：

Kotlin

val bitmaps = mutableListOf()
for (subject in subjects) {
  bitmaps.add(subject.bitmap)
}

Java

List bitmaps = new ArrayList<>();
for (Subject subject : subjects) {
  bitmaps.add(subject.getBitmap());
}

提升成效的訣竅

在每個應用程式工作階段，第一次推論的速度通常都比後續程序慢推論過程如果延遲時間極短，請考慮呼叫「虛擬」推論 Pod

結果的品質取決於輸入圖片的品質：

為了讓 ML Kit 取得準確的區隔結果，圖片至少應為 512 x 512 像素。
圖像對焦品質不佳也可能會影響準確度。如果您未能取得可接受的結果，請要求使用者重新拍攝圖片。

使用適用於 Android 的 ML Kit 區隔主題區隔

立即試用

事前準備

1. 準備輸入圖片

使用 media.Image

Kotlin

Java

Kotlin

Java

Kotlin

Java

使用檔案 URI

Kotlin

Java

使用 ByteBuffer 或 ByteArray

Kotlin

Java

使用 Bitmap

Kotlin

Java

2. 建立 SubjectSegmenter 例項

定義區隔選項

Kotlin

Java

前景可信度遮罩

Kotlin

Java

前景點陣圖

Kotlin

Java

多重主體的可信度遮罩

Kotlin

Java

多主體點陣圖

Kotlin

Java

建立主題片段

Kotlin

Java

3. 處理圖片

Kotlin

Java

4. 取得主體區隔結果

擷取前景遮罩和點陣圖

Kotlin

Java

Kotlin

Java

擷取每個主題的遮罩和點陣圖

Kotlin

Java

Kotlin

Java

提升成效的訣竅

使用 `media.Image`

使用 `ByteBuffer` 或 `ByteArray`

使用 `Bitmap`