Google AI Edge Portal 隆重推出：大規模基準測試 Edge AI。申請在非公開預先發布版期間要求存取權。

Android 臉部地標偵測指南

MediaPipe Face Landmarker 工作可讓你偵測圖片和影片中的臉部特徵點和臉部表情。您可以使用這項工作識別人類臉部表情、套用臉部濾鏡和效果，以及建立虛擬分身。這項工作會使用機器學習 (ML) 模型，可處理單張圖片或連續圖片串流。這項工作會輸出 3D 臉部地標、混合形狀分數 (代表臉部表情的係數)，即時推斷詳細的臉部表面，以及執行效果算繪所需轉換的轉換矩陣。

您可以在 GitHub 取得這些操作說明中使用的程式碼範例。如要進一步瞭解這項工作的能力、模型和設定選項，請參閱「總覽」。

程式碼範例

MediaPipe Tasks 範例程式碼是 Android 版臉部地標應用程式的簡單實作方式。這個範例會使用實體 Android 裝置上的攝影機，偵測連續影像串流中的臉部。應用程式也能偵測裝置相片庫中的圖片和影片。

您可以將這個應用程式做為自己 Android 應用程式的基礎，或在修改現有應用程式時參考。Face Landmarker 範例程式碼位於 GitHub。

下載程式碼

以下操作說明會示範如何使用 git 指令列工具，建立範例程式碼的本機副本。

如要下載範例程式碼，請按照下列步驟操作：

使用下列指令複製 git 存放區：

git clone https://github.com/google-ai-edge/mediapipe-samples

您可以選擇設定 Git 執行個體，使用稀疏簽出，這樣就只會有 Face Landmarker 範例應用程式的檔案：
```
cd mediapipe-samples
git sparse-checkout init --cone
git sparse-checkout set examples/face_landmarker/android
```

建立範例程式碼的本機版本後，您可以將專案匯入 Android Studio 並執行應用程式。如需操作說明，請參閱「Android 設定指南」。

重要元件

下列檔案包含這個臉部地標範例應用程式的重要程式碼：

FaceLandmarkerHelper.kt - 初始化臉部地標標記器，並處理模型和委派選取項目。
CameraFragment.kt - 處理裝置攝影機，並處理圖片和影片輸入資料。
GalleryFragment.kt - 與 OverlayView 互動，顯示輸出圖片或影片。
OverlayView.kt - 實作顯示畫面，並為偵測到的臉部提供臉部網格。

設定

本節說明設定開發環境和程式碼專案的主要步驟，以便使用 Face Landmarker。如需設定開發環境以使用 MediaPipe 工作的一般資訊，包括平台版本需求，請參閱 Android 設定指南。

依附元件

Face Landmarker 工作會使用 com.google.mediapipe:tasks-vision 程式庫。將這項依附元件新增至 Android 應用程式的 build.gradle 檔案：

dependencies {
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

型號

MediaPipe Face Landmarker 工作需要與這項工作相容的訓練模型套件。如要進一步瞭解 Face Landmarker 適用的訓練模型，請參閱工作總覽的「模型」部分。

選取並下載模型，然後儲存在專案目錄中：

<dev-project-root>/src/main/assets

在 ModelAssetPath 參數中指定模型路徑。在範例程式碼中，模型是在 FaceLandmarkerHelper.kt 檔案中定義：

baseOptionsBuilder.setModelAssetPath(MP_FACE_LANDMARKER_TASK)

建立工作

MediaPipe Face Landmarker 工作會使用 createFromOptions() 函式設定工作。createFromOptions() 函式會接受設定選項的值。如要進一步瞭解設定選項，請參閱「設定選項」。

臉部地標工具支援下列輸入資料類型：靜態圖片、影片檔案和即時影片串流。建立工作時，您需要指定與輸入資料類型對應的執行模式。選擇輸入資料類型的分頁，瞭解如何建立工作及執行推論。

圖片

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_FACE_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder = 
    FaceLandmarker.FaceLandmarkerOptions.builder()
        .setBaseOptions(baseOptionsBuilder.build())
        .setMinFaceDetectionConfidence(minFaceDetectionConfidence)
        .setMinTrackingConfidence(minFaceTrackingConfidence)
        .setMinFacePresenceConfidence(minFacePresenceConfidence)
        .setNumFaces(maxNumFaces)
        .setRunningMode(RunningMode.IMAGE)

val options = optionsBuilder.build()
FaceLandmarker = FaceLandmarker.createFromOptions(context, options)

影片

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_FACE_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder = 
    FaceLandmarker.FaceLandmarkerOptions.builder()
        .setBaseOptions(baseOptionsBuilder.build())
        .setMinFaceDetectionConfidence(minFaceDetectionConfidence)
        .setMinTrackingConfidence(minFaceTrackingConfidence)
        .setMinFacePresenceConfidence(minFacePresenceConfidence)
        .setNumFaces(maxNumFaces)
        .setRunningMode(RunningMode.VIDEO)

val options = optionsBuilder.build()
FaceLandmarker = FaceLandmarker.createFromOptions(context, options)

直播

val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(MP_FACE_LANDMARKER_TASK)
val baseOptions = baseOptionBuilder.build()

val optionsBuilder = 
    FaceLandmarker.FaceLandmarkerOptions.builder()
        .setBaseOptions(baseOptionsBuilder.build())
        .setMinFaceDetectionConfidence(minFaceDetectionConfidence)
        .setMinTrackingConfidence(minFaceTrackingConfidence)
        .setMinFacePresenceConfidence(minFacePresenceConfidence)
        .setNumFaces(maxNumFaces)
        .setResultListener(this::returnLivestreamResult)
        .setErrorListener(this::returnLivestreamError)
        .setRunningMode(RunningMode.LIVE_STREAM)

val options = optionsBuilder.build()
FaceLandmarker = FaceLandmarker.createFromOptions(context, options)

使用者可以透過 Face Landmarker 範例程式碼實作，在處理模式之間切換。這個方法會讓工作建立程式碼更加複雜，可能不適合您的用途。您可以在 FaceLandmarkerHelper.kt 檔案的 setupFaceLandmarker() 函式中看到這段程式碼。

設定選項

這項工作提供下列 Android 應用程式設定選項：

選項名稱	說明	值範圍	預設值
`runningMode`	設定工作執行模式。共有三種模式： IMAGE：單一圖片輸入模式。影片：影片解碼影格的模式。 LIVE_STREAM：直播輸入資料的模式，例如來自攝影機的資料。在此模式下，必須呼叫 resultListener 來設定事件監聽器，以非同步方式接收結果。	{`IMAGE, VIDEO, LIVE_STREAM`}	`IMAGE`
`numFaces`	`FaceLandmarker` 可偵測的臉部數量上限。只有在 `num_faces` 設為 1 時，才會套用平滑處理。	`Integer > 0`	`1`
`minFaceDetectionConfidence`	臉部偵測成功所需的最低信賴分數。	`Float [0.0,1.0]`	`0.5`
`minFacePresenceConfidence`	臉部特徵偵測中，臉部出現分數的最低信賴分數。	`Float [0.0,1.0]`	`0.5`
`minTrackingConfidence`	臉部追蹤的最低信賴分數，達到這個分數才算成功。	`Float [0.0,1.0]`	`0.5`
`outputFaceBlendshapes`	Face Landmarker 是否會輸出臉部混合形狀。臉部混合形狀會用於算繪 3D 臉部模型。	`Boolean`	`False`
`outputFacialTransformationMatrixes`	是否輸出臉部轉換矩陣。FaceLandmarker 會使用矩陣，將標準臉部模型中的臉部地標轉換為偵測到的臉部，讓使用者在偵測到的地標上套用特效。	`Boolean`	`False`
`resultListener`	設定結果事件監聽器，以便在 FaceLandmarker 處於即時串流模式時，以非同步方式接收地標結果。只有在執行模式設為 `LIVE_STREAM` 時才能使用	`ResultListener`	`N/A`
`errorListener`	設定選用的錯誤監聽器。	`ErrorListener`	`N/A`

準備資料

人臉地標可處理圖片、影片檔案和即時影片串流。這項工作會處理資料輸入預先處理作業，包括調整大小、旋轉和值正規化。

以下程式碼示範如何交出資料以供處理。這些範例包括如何處理圖片、影片檔案和即時影片串流中的資料。

圖片

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(image).build()

影片

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

val argb8888Frame =
    if (frame.config == Bitmap.Config.ARGB_8888) frame
    else frame.copy(Bitmap.Config.ARGB_8888, false)

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(argb8888Frame).build()

直播

import com.google.mediapipe.framework.image.BitmapImageBuilder
import com.google.mediapipe.framework.image.MPImage

// Convert the input Bitmap object to an MPImage object to run inference
val mpImage = BitmapImageBuilder(rotatedBitmap).build()

在 Face Landmarker 範例程式碼中，資料準備工作是在 FaceLandmarkerHelper.kt 檔案中處理。

執行工作

根據您處理的資料類型，使用該資料類型專屬的 FaceLandmarker.detect...() 方法。使用 detect() 處理個別圖片、detectForVideo() 處理影片檔案中的影格，以及 detectAsync() 處理影片串流。在影片串流上執行偵測時，請務必在獨立執行緒上執行偵測，以免封鎖使用者介面執行緒。

以下程式碼範例簡單示範如何在這些不同的資料模式中執行 Face Landmarker：

圖片

val result = FaceLandmarker.detect(mpImage)

影片

val timestampMs = i * inferenceIntervalMs

FaceLandmarker.detectForVideo(mpImage, timestampMs)
    .let { detectionResult ->
        resultList.add(detectionResult)
    }

直播

val mpImage = BitmapImageBuilder(rotatedBitmap).build()
val frameTime = SystemClock.uptimeMillis()

FaceLandmarker.detectAsync(mpImage, frameTime)

注意事項：

在影片模式或直播模式下執行時，您必須向 Face Landmarker 工作提供輸入影格的時間戳記。
在圖片或影片模式下執行時，Face Landmarker 工作會封鎖目前的執行緒，直到處理完輸入的圖片或影格為止。為避免封鎖使用者介面，請在背景執行緒中執行處理作業。
在即時串流模式下執行時，Face Landmarker 工作會立即傳回，不會封鎖目前的執行緒。每當處理完輸入影格時，系統就會使用偵測結果叫用結果監聽器。

在臉部地標範例程式碼中，detect、detectForVideo 和 detectAsync 函式是在 FaceLandmarkerHelper.kt 檔案中定義。

處理及顯示結果

Face Landmarker 會針對每次偵測作業傳回 FaceLandmarkerResult 物件。結果物件會包含每個偵測到的臉部網格，以及每個臉部地標的座標。視需要，結果物件也可以包含混合形狀，表示臉部表情，以及臉部轉換矩陣，以便在偵測到的地標上套用臉部特效。

以下是這項工作的輸出資料範例：

FaceLandmarkerResult:
  face_landmarks:
    NormalizedLandmark #0:
      x: 0.5971359014511108
      y: 0.485361784696579
      z: -0.038440968841314316
    NormalizedLandmark #1:
      x: 0.3302789330482483
      y: 0.29289937019348145
      z: -0.09489090740680695
    ... (478 landmarks for each face)
  face_blendshapes:
    browDownLeft: 0.8296722769737244
    browDownRight: 0.8096957206726074
    browInnerUp: 0.00035583582939580083
    browOuterUpLeft: 0.00035752105759456754
    ... (52 blendshapes for each face)
  facial_transformation_matrixes:
    [9.99158978e-01, -1.23036895e-02, 3.91213447e-02, -3.70770246e-01]
    [1.66496094e-02,  9.93480563e-01, -1.12779640e-01, 2.27719707e+01]
    ...

下圖顯示工作輸出內容的視覺化效果：

臉部區域經過幾何對應的男子，顯示臉部形狀和尺寸

Face Landmarker 範例程式碼會說明如何顯示工作傳回的結果，詳情請參閱 OverlayView 類別。