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

在 Android 上使用 ML Kit 偵測臉孔

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

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

立即試用

請試用範例應用程式，瞭解這個 API 的使用範例。
您可以透過程式碼研究室親自嘗試這段程式碼。

事前準備

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

在專案層級的 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: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'
}

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

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

輸入圖片規範

如要進行臉部辨識，請使用至少 480 x 360 像素的圖片。為了讓 ML Kit 準確偵測臉孔，輸入圖片必須包含由足夠像素資料代表的臉孔。一般來說，您要在圖片中偵測的每張臉部圖片，至少應為 100 x 100 像素。如果您想偵測臉孔輪廓，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 方法。

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

您可以從不同來源建立 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

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

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 格式擷取圖片。

在 Android 上使用 ML Kit 偵測臉孔

立即試用

事前準備

輸入圖片規範

1. 設定臉部偵測器

Kotlin

Java

2. 準備輸入圖片

使用 media.Image

Kotlin

Java

Kotlin

Java

Kotlin

Java

使用檔案 URI

Kotlin

Java

使用 ByteBuffer 或 ByteArray

Kotlin

Java

使用 Bitmap

Kotlin

Java

3. 取得 FaceDetector 例項

Kotlin

Java

4. 處理圖片

Kotlin

Java

5. 取得偵測到的臉孔相關資訊

Kotlin

Java

臉部輪廓示例

即時臉部偵測

使用 `media.Image`

使用 `ByteBuffer` 或 `ByteArray`

使用 `Bitmap`