Python 的臉部偵測指南

MediaPipe 臉孔偵測器工作可讓您偵測圖片或影片中的臉孔。您可以使用這個任務，找出影格內的臉部和臉部特徵。這項工作會使用機器學習 (ML) 模型，該模型可處理單張圖片或連續圖片串流。這項工作會輸出臉部位置，以及下列臉部要點：左眼、右眼、鼻尖、嘴巴、左眼外眥和右眼外眥。

您可以在 GitHub 上找到這些操作說明中所述的程式碼範例。如要進一步瞭解這項工作的功能、模型和設定選項，請參閱總覽。

程式碼範例

臉部偵測器的範例程式碼會在 Python 中提供此工作的完整實作方式，供您參考。這段程式碼可協助您測試此工作，並開始建構自己的臉部偵測器。您可以只使用網頁瀏覽器，查看、執行及編輯 人臉偵測器範例程式碼。

如果您要為 Raspberry Pi 實作臉部偵測器，請參閱 Raspberry Pi 範例應用程式。

設定

本節將說明設定開發環境和程式碼專案的關鍵步驟，以便使用 Face Detector。如要進一步瞭解如何設定開發環境以使用 MediaPipe 工作，包括平台版本需求，請參閱 Python 設定指南。

套件

MediaPipe 臉部偵測器工作需要 mediapipe PyPI 套件。您可以透過下列方式安裝及匯入這些依附元件：

$ python -m pip install mediapipe

匯入

匯入下列類別，以存取 Face Detector 工作函式：

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

型號

MediaPipe 臉部偵測器工作需要訓練的模型，且必須與此工作相容。如要進一步瞭解可用的臉部偵測器訓練模型，請參閱任務總覽的「模型」一節。

選取並下載模型，然後將其儲存在本機目錄中：

model_path = '/absolute/path/to/face_detector.task'

使用 BaseOptions 物件的 model_asset_path 參數，指定要使用的模型路徑。如需程式碼範例，請參閱下一節。

建立工作

MediaPipe 臉部偵測器工作會使用 create_from_options 函式設定工作。create_from_options 函式會接受設定選項的值，以便處理。如要進一步瞭解設定選項，請參閱「設定選項」。

以下程式碼示範如何建構及設定此工作。

這些範例也說明瞭圖片、影片檔案和直播的任務建構變化。

圖片

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceDetector = mp.tasks.vision.FaceDetector
FaceDetectorOptions = mp.tasks.vision.FaceDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face detector instance with the image mode:
options = FaceDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with FaceDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...

影片

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceDetector = mp.tasks.vision.FaceDetector
FaceDetectorOptions = mp.tasks.vision.FaceDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face detector instance with the video mode:
options = FaceDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with FaceDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...

直播

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceDetector = mp.tasks.vision.FaceDetector
FaceDetectorOptions = mp.tasks.vision.FaceDetectorOptions
FaceDetectorResult = mp.tasks.vision.FaceDetectorResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face detector instance with the live stream mode:
def print_result(result: FaceDetectorResult, output_image: mp.Image, timestamp_ms: int):
    print('face detector result: {}'.format(result))

options = FaceDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)
with FaceDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...

如需建立臉部偵測器的完整範例，以便搭配圖片使用，請參閱程式碼範例。

設定選項

此工作包含下列 Python 應用程式的設定選項：

選項名稱 說明 值範圍 預設值
running_mode 設定工作執行模式。共有三種模式：

IMAGE：單一圖片輸入模式。

VIDEO：影片解碼影格模式。

LIVE_STREAM：輸入資料 (例如來自攝影機的資料) 的直播模式。在這個模式中，必須呼叫 resultListener，才能設定事件監聽器，以非同步方式接收結果。		 {IMAGE, VIDEO, LIVE_STREAM} IMAGE
min_detection_confidence 系統判定臉部偵測成功的最低可信度分數。 Float [0,1] 0.5
min_suppression_threshold 臉部偵測系統判定為重疊的非最大抑制門檻下限。 Float [0,1] 0.3
result_callback 在 Face Detector 處於即時串流模式時，將結果事件監聽器設為以非同步方式接收偵測結果。只有在執行模式設為 LIVE_STREAM 時才能使用。 N/A Not set

準備資料

將輸入內容設為圖片檔案或 Numpy 陣列，然後轉換為 mediapipe.Image 物件。如果輸入內容是網路攝影機的影片檔案或直播內容，您可以使用 OpenCV 等外部程式庫，將輸入影格載入為 Numpy 陣列。

圖片

import mediapipe as mp

# Load the input image from an image file.
mp_image = mp.Image.create_from_file('/path/to/image')

# Load the input image from a numpy array.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_image)

影片

import mediapipe as mp

# Use OpenCV’s VideoCapture to load the input video.

# Load the frame rate of the video using OpenCV’s CV_CAP_PROP_FPS
# You’ll need it to calculate the timestamp for each frame.

# Loop through each frame in the video using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)

直播

import mediapipe as mp

# Use OpenCV’s VideoCapture to start capturing from the webcam.

# Create a loop to read the latest frame from the camera using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)

執行工作

臉部偵測器會使用 detect、detect_for_video 和 detect_async 函式觸發推論。對於臉部偵測，這包括預先處理輸入資料，以及偵測圖片中的臉孔。

以下程式碼示範如何使用工作模型執行處理作業。

圖片

# Perform face detection on the provided single image.
# The face detector must be created with the image mode.
face_detector_result = detector.detect(mp_image)

影片

# Perform face detection on the provided single image.
# The face detector must be created with the video mode.
face_detector_result = detector.detect_for_video(mp_image, frame_timestamp_ms)

直播

# Send live image data to perform face detection.
# The results are accessible via the `result_callback` provided in
# the `FaceDetectorOptions` object.
# The face detector must be created with the live stream mode.
detector.detect_async(mp_image, frame_timestamp_ms)

注意事項：

  • 在影片模式或直播模式下執行時，請一併提供 Face Detector 工作單元輸入影格時間戳記。
  • 在圖片或影片模型中執行時，臉部偵測器工作會封鎖目前的執行緒，直到處理完輸入圖片或影格為止。
  • 在直播模式下執行時，臉部偵測器工作會立即傳回，且不會封鎖目前的執行緒。每次處理完輸入影格時，它都會使用偵測結果叫用結果事件監聽器。如果在 Face Detector 工作單元忙於處理其他影格時呼叫偵測函式，該工作單元會忽略新的輸入影格。

如需在圖片上執行臉部偵測器的完整範例，請參閱程式碼範例。

處理及顯示結果

臉部偵測器會為每次偵測作業傳回 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)

下圖是工作輸出內容的視覺化呈現：

兩名孩童的臉部有邊框

如需不含定界框的圖片，請參閱原始圖片。

臉部偵測器範例程式碼示範如何顯示工作傳回的結果，詳情請參閱程式碼範例。