MediaPipe 臉部偵測器工作可讓你偵測圖片或影片中的臉孔。您可以使用這項工作找出影格中的臉孔和臉部特徵。這項工作使用的機器學習 (ML) 模型搭配單一圖片或連續圖片串流。這項工作會輸出臉部位置和下列臉部關鍵點：左眼、右眼、鼻子小費、嘴巴、左眼腹部和右眼對焦。
GitHub 提供本文中說明的程式碼範例。如要進一步瞭解這項工作的功能、模型和設定選項，請參閱總覽。
程式碼範例
MediaPipe Tasks 範例程式碼是 Android 臉部偵測器應用程式的簡易實作方式。這個範例使用 Android 實體裝置的相機，偵測連續影片串流中的臉孔。此外，應用程式也能在裝置圖片庫中偵測圖片和影片的臉孔。
您可以將該應用程式做為開發 Android 應用程式的起點，也可以在修改現有應用程式時參照。臉部偵測器範例程式碼由 GitHub 代管。
下載程式碼
以下操作說明說明如何使用 git 指令列工具建立範例程式碼的本機副本。
如要下載範例程式碼，請按照下列步驟操作：
- 使用下列指令複製 Git 存放區：
git clone https://github.com/google-ai-edge/mediapipe-samples
- 您可以選擇將 Git 執行個體設為使用稀疏檢查，因此只有臉部偵測器範例應用程式的檔案：
cd mediapipe git sparse-checkout init --cone git sparse-checkout set examples/face_detector/android
建立範例程式碼的本機版本後，您可以將專案匯入 Android Studio 並執行應用程式。如需操作說明，請參閱「Android 設定指南」。
重要元件
下列檔案包含此臉部偵測範例應用程式的重要程式碼：
- FaceDetectorHelper.kt：初始化臉部偵測工具並處理模型並委派選取。
- CameraFragment.kt - 處理裝置相機，並處理圖片和影片輸入資料。
- GalleryFragment.kt - 與
OverlayView互動，顯示輸出圖片或影片。 - OverlayView.kt - 為偵測到的臉孔實作含有定界框的螢幕。
設定
本節說明設定開發環境的重要步驟，以及專門針對使用臉部偵測器的程式碼專案編寫程式碼。如需瞭解如何設定開發環境以使用 MediaPipe 工作 (包括平台版本需求)，請參閱「Android 設定指南」。
依附元件
臉部偵測器工作會使用 com.google.mediapipe:tasks-vision 程式庫。將此依附元件新增至 Android 應用程式的 build.gradle 檔案：
dependencies {
implementation 'com.google.mediapipe:tasks-vision:latest.release'
}
型號
MediaPipe 臉部偵測器工作需要與這項工作相容的已訓練模型組合。如要進一步瞭解臉部偵測器的可用已訓練模型，請參閱工作總覽「模型」一節。
選取並下載模型，並儲存在專案目錄中：
<dev-project-root>/src/main/assets
在 ModelAssetPath 參數中指定模型的路徑。在這個範例程式碼中，模型會在 FaceDetectorHelper.kt 檔案中定義：
val modelName = "face_detection_short_range.tflite"
baseOptionsBuilder.setModelAssetPath(modelName)
建立工作
MediaPipe 臉部偵測器工作會使用 createFromOptions() 函式設定工作。createFromOptions() 函式可接受設定選項的值。如要進一步瞭解設定選項，請參閱「設定選項」一文。
臉部偵測器支援下列輸入資料類型：靜態圖片、影片檔案和直播影片串流。您在建立工作時，需要指定與輸入資料類型相對應的執行模式。請選擇與輸入資料類型對應的分頁，瞭解如何建立工作並執行推論。
圖片
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(modelName)
val baseOptions = baseOptionBuilder.build()
val optionsBuilder =
FaceDetector.FaceDetectorOptions.builder()
.setBaseOptions(baseOptionsBuilder.build())
.setMinDetectionConfidence(threshold)
.setRunningMode(RunningMode.IMAGE)
val options = optionsBuilder.build()
FaceDetector =
FaceDetector.createFromOptions(context, options)
影片
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(modelName)
val baseOptions = baseOptionBuilder.build()
val optionsBuilder =
FaceDetector.FaceDetectorOptions.builder()
.setBaseOptions(baseOptionsBuilder.build())
.setMinDetectionConfidence(threshold)
.setRunningMode(RunningMode.VIDEO)
val options = optionsBuilder.build()
FaceDetector =
FaceDetector.createFromOptions(context, options)
直播
val baseOptionsBuilder = BaseOptions.builder().setModelAssetPath(modelName)
val baseOptions = baseOptionBuilder.build()
val optionsBuilder =
FaceDetector.FaceDetectorOptions.builder()
.setBaseOptions(baseOptionsBuilder.build())
.setMinDetectionConfidence(threshold)
.setResultListener(this::returnLivestreamResult)
.setErrorListener(this::returnLivestreamError)
.setRunningMode(RunningMode.LIVE_STREAM)
val options = optionsBuilder.build()
FaceDetector =
FaceDetector.createFromOptions(context, options)
臉部偵測器程式碼範例實作可讓使用者切換處理模式。這種做法會讓工作建立程式碼變得更加複雜，並且可能不適合您的用途。您可以在 FaceDetectorHelper.kt 檔案的 setupFaceDetector() 函式中看到此程式碼。
設定選項
這項工作的 Android 應用程式設定選項如下：
| 選項名稱 | 說明 | 值範圍 | 預設值 |
|---|---|---|---|
runningMode |
設定工作的執行模式。共有三種模式： IMAGE：單一圖片輸入的模式。 影片：影片已解碼影格的模式。 LIVE_STREAM：輸入資料串流 (例如攝影機) 的直播模式。在這個模式下，必須呼叫 resultListener 才能設定事件監聽器，以非同步方式接收結果。 |
{IMAGE, VIDEO, LIVE_STREAM} |
IMAGE |
minDetectionConfidence |
系統會將臉部偵測判定為成功的最低可信度分數。 | Float [0,1] |
0.5 |
minSuppressionThreshold |
系統會將臉部偵測判定為重疊的非最大抑制門檻。 | Float [0,1] |
0.3 |
resultListener |
設定結果事件監聽器，在臉部偵測器處於直播模式時，以非同步方式接收偵測結果。只能在執行模式設為 LIVE_STREAM 時使用。 |
N/A |
Not set |
errorListener |
設定選用的錯誤事件監聽器。 | N/A |
Not set |
準備資料
臉部偵測器支援圖片、影片檔案和即時影像串流。工作會處理資料輸入的預先處理作業，包括調整大小、旋轉和值正規化。
以下程式碼示範如何傳送資料以進行處理。這些範例包含如何處理圖片、影片檔案和直播影片串流的資料。
圖片
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()
在臉部偵測器的範例程式碼中，資料準備是在 FaceDetectorHelper.kt 檔案中處理。
執行工作
視處理的資料類型而定，請使用該資料類型專屬的 faceDetector.detect...() 方法。針對個別圖片使用 detect()，detectForVideo() 用於影片檔案中的影格，detectAsync() 用於影片串流。在影片串流中執行偵測時，請務必在另一個執行緒上執行偵測，以免封鎖使用者介面執行緒。
以下程式碼範例顯示如何在這些不同的資料模式中執行臉部偵測器的簡易範例：
圖片
val result = faceDetector.detect(mpImage)
影片
val timestampMs = i * inferenceIntervalMs
faceDetector.detectForVideo(mpImage, timestampMs)
.let { detectionResult ->
resultList.add(detectionResult)
}
直播
val mpImage = BitmapImageBuilder(rotatedBitmap).build()
val frameTime = SystemClock.uptimeMillis()
faceDetector.detectAsync(mpImage, frameTime)
注意事項：
- 以影片模式或直播模式執行時，您必須在臉部偵測器工作中提供輸入影格的時間戳記。
- 以圖片或影片模式執行時，臉部偵測器工作會封鎖目前的執行緒，直到完成輸入圖片或影格的處理為止。如要避免封鎖使用者介面，請在背景執行緒中執行處理作業。
- 以直播模式執行時，臉部偵測器工作會立即回傳，且不會封鎖目前的執行緒。每當它處理完輸入影格時，就會透過偵測結果叫用結果監聽器。如果臉部偵測器工作正在忙於處理其他影格時呼叫偵測功能，則任務會忽略新的輸入影格。
在臉部偵測器的範例程式碼中，detect、detectForVideo 和 detectAsync 函式是在 FaceDetectorHelper.kt 檔案中定義。
處理並顯示結果
臉部偵測器每次執行時，都會傳回 FaceDetectorResult 物件。結果物件會包含偵測到的臉孔的定界框，以及每個偵測到的臉孔可信度分數。
以下為這項工作的輸出資料範例：
FaceDetectionResult:
Detections:
Detection #0:
BoundingBox:
origin_x: 126
origin_y: 100
width: 463
height: 463
Categories:
Category #0:
index: 0
score: 0.9729152917861938
NormalizedKeypoints:
NormalizedKeypoint #0:
x: 0.18298381567001343
y: 0.2961040139198303
NormalizedKeypoint #1:
x: 0.3302789330482483
y: 0.29289937019348145
... (6 keypoints for each face)
Detection #1:
BoundingBox:
origin_x: 616
origin_y: 193
width: 430
height: 430
Categories:
Category #0:
index: 0
score: 0.9251380562782288
NormalizedKeypoints:
NormalizedKeypoint #0:
x: 0.6151331663131714
y: 0.3713381886482239
NormalizedKeypoint #1:
x: 0.7460576295852661
y: 0.38825345039367676
... (6 keypoints for each face)
下圖以視覺化方式呈現工作輸出內容：
如果圖片沒有定界框，請參閱原始圖片。
臉部偵測器範例程式碼示範如何顯示工作傳回的結果，詳情請參閱 OverlayView 類別。