隆重推出 LiteRT：Google 為裝置端 AI (舊稱 TensorFlow Lite) 打造的高效能執行階段。

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

Python 的臉孔地標偵測指南

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

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

程式碼範例

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

如果您要為 Raspberry Pi 實作人臉標記功能，請參閱 Raspberry Pi 範例應用程式。

設定

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

套件

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

$ python -m pip install mediapipe

匯入

匯入下列類別，即可存取臉部標記器工作函式：

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

型號

MediaPipe 臉部標記工作需要與此工作相容的訓練模型。如要進一步瞭解 Face Landmarker 可用的訓練模型，請參閱工作總覽的「模型」一節。

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

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

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

建立工作

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

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

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

圖片

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceLandmarker = mp.tasks.vision.FaceLandmarker
FaceLandmarkerOptions = mp.tasks.vision.FaceLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

options = FaceLandmarkerOptions(
    base_options=BaseOptions(model_asset_path=model_path),
    running_mode=VisionRunningMode.IMAGE)

with FaceLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...

影片

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceLandmarker = mp.tasks.vision.FaceLandmarker
FaceLandmarkerOptions = mp.tasks.vision.FaceLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a face landmarker instance with the video mode:
options = FaceLandmarkerOptions(
    base_options=BaseOptions(model_asset_path=model_path),
    running_mode=VisionRunningMode.VIDEO)

with FaceLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...

直播

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
FaceLandmarker = mp.tasks.vision.FaceLandmarker
FaceLandmarkerOptions = mp.tasks.vision.FaceLandmarkerOptions
FaceLandmarkerResult = mp.tasks.vision.FaceLandmarkerResult
VisionRunningMode = mp.tasks.vision.RunningMode

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

options = FaceLandmarkerOptions(
    base_options=BaseOptions(model_asset_path=model_path),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)

with FaceLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...

如需建立臉部標記以供圖片使用，請參閱完整範例程式碼範例。

設定選項

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

選項名稱	說明	值範圍	預設值
`running_mode`	設定工作執行模式。共有三種模式： IMAGE：單一圖片輸入模式。 VIDEO：影片解碼影格模式。 LIVE_STREAM：輸入資料 (例如來自攝影機的資料) 的直播模式。在這個模式中，必須呼叫 resultListener，才能設定事件監聽器，以非同步方式接收結果。	{`IMAGE, VIDEO, LIVE_STREAM`}	`IMAGE`
`num_faces`	`FaceLandmarker` 可偵測的臉孔數量上限。只有在 `num_faces` 設為 1 時才會套用平滑處理。	`Integer > 0`	`1`
`min_face_detection_confidence`	系統判定臉部偵測成功的最低可信度分數。	`Float [0.0,1.0]`	`0.5`
`min_face_presence_confidence`	臉部特徵偵測中臉部存在分數的最低可信度分數。	`Float [0.0,1.0]`	`0.5`
`min_tracking_confidence`	系統判定臉部追蹤成功的最低可信度分數。	`Float [0.0,1.0]`	`0.5`
`output_face_blendshapes`	臉部特徵點偵測器是否會輸出臉部混合形狀。臉部混合形狀用於算繪 3D 臉部模型。	`Boolean`	`False`
`output_facial_transformation_matrixes`	FaceLandmarker 是否會輸出臉部轉換矩陣。FaceLandmarker 會使用矩陣，將臉部標記從標準臉部模型轉換為偵測到的臉部，方便使用者在偵測到的標記上套用效果。	`Boolean`	`False`
`result_callback`	在 FaceLandmarker 處於即時串流模式時，將結果事件監聽器設為以非同步方式接收地標結果。只有在執行模式設為 `LIVE_STREAM` 時，才能使用	`ResultListener`	`N/A`

準備資料

將輸入內容設為圖片檔案或 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)

執行工作

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

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

圖片

# Perform face landmarking on the provided single image.
# The face landmarker must be created with the image mode.
face_landmarker_result = landmarker.detect(mp_image)

影片

# Perform face landmarking on the provided single image.
# The face landmarker must be created with the video mode.
face_landmarker_result = landmarker.detect_for_video(mp_image, frame_timestamp_ms)

直播

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

注意事項：

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

如需在圖片上執行 Face Landmarker 的完整範例，請參閱程式碼範例。

處理及顯示結果

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]
    ...

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

一名男子的臉部區域以幾何圖形繪製，用來表示臉部形狀和尺寸

臉部地標程式碼範例說明如何顯示工作傳回的結果，詳情請參閱程式碼範例。