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

在 Android 上使用 ML Kit 偵測臉部

您可以使用機器學習套件偵測圖片和影片中的臉孔。

功能	未分類郵件	組合
實作	系統會透過 Google Play 服務動態下載模型。	模型會在建構期間以靜態方式連結至您的應用程式。
應用程式大小	大小增加約 800 KB。	大小增加約 6.9 MB。
初始化時間	可能必須先等待模型下載完成才能使用。	可立即使用模型

立即體驗

請試用範例應用程式，查看這個 API 的使用範例。
透過程式碼研究室自行測試程式碼。

事前準備

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

在專案層級的 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.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 像素的圖片。為了讓機器學習套件準確偵測臉部，輸入圖片必須包含以足夠像素資料呈現的臉孔。一般而言，您想要在圖片中偵測的臉孔大小至少須為 100x100 像素。如要偵測臉部的輪廓，機器學習套件需提供高解析度的輸入值：每個臉孔至少須為 200x200 像素。

如果在即時應用程式中偵測臉孔，建議您考慮輸入圖片的整體尺寸。較小的圖片處理速度較快，因此能縮短延遲時間、以較低解析度擷取圖片，但請留意上述的準確率要求，並盡量讓拍攝主體的臉孔佔滿圖片。另請參閱改善即時效能的訣竅。

圖片品質不佳也可能會影響準確率。如果未收到可接受的結果，請要求使用者擷取圖片。

臉部相對於臉部的方向也可能影響機器學習套件偵測到的臉部特徵。請參閱臉部偵測概念一文。

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`