Python 的臉孔地標偵測指南

MediaPipe Face Landmarker 工作可讓你在 圖片、圖片和影片你可以使用這項工作辨識人類臉部表情 以及套用臉部濾鏡和特效，製作虛擬虛擬化身。這項工作使用 可以使用單一圖片或連續性模型的機器學習 (ML) 模型 一流的圖片這項工作會輸出 3D 臉部地標、混合形狀 分數 (代表臉部表情的係數) 以推斷詳細的臉部 並透過轉換矩陣執行 效果轉譯所需的轉換

如需上述指示中所述的程式碼範例，請前往 GitHub。 進一步瞭解功能、模型和設定選項 請參閱總覽。

程式碼範例

這個範例程式碼提供了這項功能的完整實作 執行相關作業這個程式碼可協助您測試這項工作 開始自己建立自己的臉部地標 您可以查看、執行及編輯 臉部標記工具範例 程式碼 只要使用網路瀏覽器即可。

如果您要為 Raspberry Pi 實作臉部地標，請參閱 Raspberry Pi 範例 app。

設定

本節說明設定開發環境的重要步驟，以及 程式碼專案如需 設定開發環境以使用 MediaPipe 工作，包括： 平台版本需求，請參閱這份指南 Python。

套件

MediaPipe Face Landmarker 工作需要 mediapipe PyPI 套件。您可以安裝 透過下列指令匯入這些依附元件：

$ python -m pip install mediapipe

匯入

匯入下列類別來存取臉部地標工作函式：

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

型號

MediaPipe Face 標誌 er 工作需要經過訓練且與這個模型相容的模型 工作。如要進一步瞭解適用於臉部地標的已訓練模型，請參閱： 工作總覽的「模型」一節。

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

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

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

建立工作

MediaPipe Face 地標 er 工作會使用 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 設定任務的執行模式。在架構中 模式：

圖片：單一圖片輸入模式。

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 設定 Face Marker 是否輸出臉部混合。 臉部混合形狀是用來算繪 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)

執行工作

臉部地標使用 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 地標 er 工作會傳回 而且不會封鎖目前的執行緒。就會叫用結果 每次處理完 輸入影格如果在臉部地標工作時呼叫偵測功能 工作正忙於處理另一個影格，該工作會忽略新的輸入框。

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

處理及顯示結果

Face 地標會針對每個偵測傳回 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]
    ...

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

臉部地標範例程式碼示範如何顯示傳回的結果 請參閱程式碼 示例 。