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

在 Android 上使用 ML Kit 偵測臉孔

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

功能	未組合	組合
實作中	模型會透過 Google Play 服務動態下載。	模型會在建構期間以靜態方式連結至應用程式。
應用程式大小	大小大約增加 800 KB。	大小上限為 6.9 MB。
初始化時間	可能必須先等待模型下載才能使用。	可立即使用型號

立即體驗

如要查看此 API 的範例，請搭配範例應用程式。
透過程式碼研究室嘗試自行編寫程式碼。

事前準備

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

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

將 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.5'
}

在 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 明確檢查模型可用性及要求下載。

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

輸入圖片規範

臉部辨識時必須使用大小至少為 480x360 像素的圖片。為讓機器學習套件能準確偵測臉部，輸入圖片必須包含充足的像素資料代表的臉孔。一般來說，在圖片中要偵測到的每張臉孔都必須至少 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 方法。

臉部偵測至少應為 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

注意：如果您使用的是 CameraX API，請務必在使用完成後關閉 ImageProxy，例如，將 OnCompleteListener 新增至 process 方法傳回的 Task 中。如需查看範例，請參閱快速入門導覽課程範例應用程式中的 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`