在 Android 上使用 ML Kit 偵測臉孔

您可以使用 ML Kit 偵測圖片和影片中的臉部。

功能未綁定組合
導入作業模型會透過 Google Play 服務動態下載。模型會在建構時靜態連結至應用程式。
應用程式大小大小增加約 800 KB。大小增加約 6.9 MB。
初始化時間首次使用前可能需要等待模型下載完成。模型會立即提供

立即試用

事前準備

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

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

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

    dependencies {
  // ...
  // Use this dependency to bundle the model with your app
  implementation 'com.google.mlkit:face-detection:16.1.7'
}

    如要在 Google Play 服務中使用模型：

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

  3. 如果選擇在 Google Play 服務中使用模型，您可以設定應用程式，在從 Play 商店安裝後自動將模型下載至裝置。如要這麼做，請在應用程式的 AndroidManifest.xml 檔案中加入以下宣告：

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

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

    如果您未啟用安裝時模型下載功能或要求明確下載，模型會在您首次執行偵測器時下載。在下載完成前提出的要求不會產生任何結果。

輸入圖片規範

如要進行臉部辨識，請使用尺寸至少為 480x360 像素的圖片。 如要讓 ML Kit 準確偵測臉部，輸入圖片必須包含臉部，且臉部有足夠的像素資料。一般來說，圖片中要偵測的每個臉部至少應為 100x100 像素。如要偵測臉部輪廓，ML Kit 需要較高解析度的輸入內容：每個臉部至少應為 200x200 像素。

如果您在即時應用程式中偵測到臉部，可能也需要考量輸入圖片的整體尺寸。較小的圖片處理速度較快，因此如要縮短延遲時間，請以較低的解析度拍攝圖片，但請注意上述準確度規定，並確保主體的臉部盡可能占滿圖片。另請參閱提升即時效能的訣竅。

圖片對焦不佳也會影響準確度。如果結果不符合要求，請要求使用者重新拍攝圖片。

臉部相對於攝影機的方向也會影響 ML Kit 偵測到的臉部特徵。請參閱「臉部偵測概念」。

1. 設定臉部偵測器

將臉部偵測套用至圖片前，如要變更臉部偵測器的任何預設設定，請使用 FaceDetectorOptions 物件指定這些設定。你可以變更下列設定：

設定
setPerformanceMode PERFORMANCE_MODE_FAST (預設) | � PERFORMANCE_MODE_ACCURATE

偵測臉孔時，偏好速度或準確度。
setLandmarkMode LANDMARK_MODE_NONE (預設) | � LANDMARK_MODE_ALL

是否嘗試辨識臉部「地標」：眼睛、耳朵、鼻子、臉頰、嘴巴等。
setContourMode CONTOUR_MODE_NONE (預設) | � CONTOUR_MODE_ALL

是否要偵測臉部特徵的輪廓。系統只會偵測圖片中最顯眼的臉部輪廓。
setClassificationMode CLASSIFICATION_MODE_NONE (預設) | CLASSIFICATION_MODE_ALL

是否要將臉部分類，例如「微笑」和「睜開眼睛」。
setMinFaceSize float (預設值：0.1f)

設定所需最小臉部大小，以頭部寬度與圖片寬度的比例表示。
enableTracking false (預設) | true

是否要為臉部分配 ID，以便追蹤圖片中的臉部。

請注意，啟用輪廓偵測功能後，系統只會偵測到一張臉，因此臉部追蹤功能不會產生實用結果。因此，為提升偵測速度，請勿同時啟用輪廓偵測和臉部追蹤功能。

例如：

Kotlin

// High-accuracy landmark detection and face classification
val highAccuracyOpts = FaceDetectorOptions.Builder()
        .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_ACCURATE)
        .setLandmarkMode(FaceDetectorOptions.LANDMARK_MODE_ALL)
        .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
        .build()

// Real-time contour detection
val realTimeOpts = FaceDetectorOptions.Builder()
        .setContourMode(FaceDetectorOptions.CONTOUR_MODE_ALL)
        .build()
FaceDetectionActivity.kt

Java

// High-accuracy landmark detection and face classification
FaceDetectorOptions highAccuracyOpts =
        new FaceDetectorOptions.Builder()
                .setPerformanceMode(FaceDetectorOptions.PERFORMANCE_MODE_ACCURATE)
                .setLandmarkMode(FaceDetectorOptions.LANDMARK_MODE_ALL)
                .setClassificationMode(FaceDetectorOptions.CLASSIFICATION_MODE_ALL)
                .build();

// Real-time contour detection
FaceDetectorOptions realTimeOpts =
        new FaceDetectorOptions.Builder()
                .setContourMode(FaceDetectorOptions.CONTOUR_MODE_ALL)
                .build();
FaceDetectionActivity.java

2. 準備輸入圖片

如要在圖片中偵測臉部，請從 Bitmap、media.Image、ByteBuffer、位元組陣列或裝置上的檔案建立 InputImage 物件。然後，將 InputImage 物件傳遞至 FaceDetector 的 process 方法。

如要進行臉部偵測，請使用尺寸至少為 480x360 像素的圖片。如果您要即時偵測臉部，以這個最低解析度擷取影格有助於縮短延遲時間。

您可以從不同來源建立 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 物件和旋轉角度表示。

3. 取得 FaceDetector 的執行個體

Kotlin

val detector = FaceDetection.getClient(options)
// Or, to use the default option:
// val detector = FaceDetection.getClient();
FaceDetectionActivity.kt

Java

FaceDetector detector = FaceDetection.getClient(options);
// Or use the default options:
// FaceDetector detector = FaceDetection.getClient();
FaceDetectionActivity.java

4. 處理圖片

將圖片傳遞至 process 方法：

Kotlin

val result = detector.process(image)
        .addOnSuccessListener { faces ->
            // Task completed successfully
            // ...
        }
        .addOnFailureListener { e ->
            // Task failed with an exception
            // ...
        }
FaceDetectionActivity.kt

Java

Task<List<Face>> result =
        detector.process(image)
                .addOnSuccessListener(
                        new OnSuccessListener<List<Face>>() {
                            @Override
                            public void onSuccess(List<Face> faces) {
                                // Task completed successfully
                                // ...
                            }
                        })
                .addOnFailureListener(
                        new OnFailureListener() {
                            @Override
                            public void onFailure(@NonNull Exception e) {
                                // Task failed with an exception
                                // ...
                            }
                        });
FaceDetectionActivity.java

5. 取得偵測到的臉部資訊

如果臉部偵測作業成功，系統會將 Face 物件清單傳遞至成功事件監聽器。每個 Face 物件代表圖片中偵測到的臉部。您可以取得輸入圖片中每個臉部的邊界座標，以及您設定臉部偵測器要尋找的任何其他資訊。例如：

Kotlin

for (face in faces) {
    val bounds = face.boundingBox
    val rotY = face.headEulerAngleY // Head is rotated to the right rotY degrees
    val rotZ = face.headEulerAngleZ // Head is tilted sideways rotZ degrees

    // If landmark detection was enabled (mouth, ears, eyes, cheeks, and
    // nose available):
    val leftEar = face.getLandmark(FaceLandmark.LEFT_EAR)
    leftEar?.let {
        val leftEarPos = leftEar.position
    }

    // If contour detection was enabled:
    val leftEyeContour = face.getContour(FaceContour.LEFT_EYE)?.points
    val upperLipBottomContour = face.getContour(FaceContour.UPPER_LIP_BOTTOM)?.points

    // If classification was enabled:
    if (face.smilingProbability != null) {
        val smileProb = face.smilingProbability
    }
    if (face.rightEyeOpenProbability != null) {
        val rightEyeOpenProb = face.rightEyeOpenProbability
    }

    // If face tracking was enabled:
    if (face.trackingId != null) {
        val id = face.trackingId
    }
}
FaceDetectionActivity.kt

Java

for (Face face : faces) {
    Rect bounds = face.getBoundingBox();
    float rotY = face.getHeadEulerAngleY();  // Head is rotated to the right rotY degrees
    float rotZ = face.getHeadEulerAngleZ();  // Head is tilted sideways rotZ degrees

    // If landmark detection was enabled (mouth, ears, eyes, cheeks, and
    // nose available):
    FaceLandmark leftEar = face.getLandmark(FaceLandmark.LEFT_EAR);
    if (leftEar != null) {
        PointF leftEarPos = leftEar.getPosition();
    }

    // If contour detection was enabled:
    List<PointF> leftEyeContour =
            face.getContour(FaceContour.LEFT_EYE).getPoints();
    List<PointF> upperLipBottomContour =
            face.getContour(FaceContour.UPPER_LIP_BOTTOM).getPoints();

    // If classification was enabled:
    if (face.getSmilingProbability() != null) {
        float smileProb = face.getSmilingProbability();
    }
    if (face.getRightEyeOpenProbability() != null) {
        float rightEyeOpenProb = face.getRightEyeOpenProbability();
    }

    // If face tracking was enabled:
    if (face.getTrackingId() != null) {
        int id = face.getTrackingId();
    }
}
FaceDetectionActivity.java

臉部輪廓範例

啟用臉部輪廓偵測功能後，系統會列出偵測到的每個臉部特徵點。這些點代表特徵的形狀。如要進一步瞭解輪廓的表示方式，請參閱臉部偵測概念。

下圖說明這些點如何對應至臉部，按一下圖片即可放大：

偵測到的臉部輪廓網格範例

即時臉部偵測

如要在即時應用程式中使用臉部偵測功能，請遵循下列準則，盡可能提高影格速率：

  • 設定臉部偵測器，使用臉部輪廓偵測或分類和地標偵測，但不能同時使用這兩種功能：

    輪廓偵測
    地標偵測
    分類
    地標偵測和分類
    輪廓偵測和地標偵測
    輪廓偵測和分類
    輪廓偵測、地標偵測和分類

  • 啟用 FAST 模式 (預設為啟用)。

  • 建議您以較低的解析度拍攝圖片。不過，也請注意此 API 的圖片尺寸規定。

  • 如果您使用 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 格式擷取圖片。
    •