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

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

Python 的姿勢地標偵測指南

MediaPipe Pose Landmarker 工作可讓您在圖片或影片中偵測人體地標。您可以使用這項工作來找出身體的重要位置、分析姿勢，以及分類動作。這項工作會使用機器學習 (ML) 模型，這些模型可處理單張圖片或影片。這項工作會以圖片座標和 3D 世界座標輸出人體姿勢地標。

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

程式碼範例

姿勢地標的程式碼範例會提供 Python 中此工作的完整實作方式，供您參考。這個程式碼可協助您測試這項工作，並開始建構自己的姿勢地標。您可以只使用網頁瀏覽器，查看、執行及編輯 Pose Landmarker 範例程式碼。

如果您要為 Raspberry Pi 實作姿勢地標，請參閱 Raspberry Pi 範例應用程式。

設定

本節將說明設定開發環境和程式碼專案的關鍵步驟，以便使用 Pose 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 姿勢標記器工作需要訓練的模型，且必須與此工作相容。如要進一步瞭解可用訓練模型的姿勢地標，請參閱工作總覽的「模型」一節。

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

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

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

建立工作

MediaPipe Pose Landmarker 工作會使用 create_from_options 函式設定工作。create_from_options 函式會接受設定選項的值，以便處理。詳情請參閱「設定選項」。

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

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

圖片

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
PoseLandmarker = mp.tasks.vision.PoseLandmarker
PoseLandmarkerOptions = mp.tasks.vision.PoseLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

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

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

影片

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
PoseLandmarker = mp.tasks.vision.PoseLandmarker
PoseLandmarkerOptions = mp.tasks.vision.PoseLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

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

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

直播

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
PoseLandmarker = mp.tasks.vision.PoseLandmarker
PoseLandmarkerOptions = mp.tasks.vision.PoseLandmarkerOptions
PoseLandmarkerResult = mp.tasks.vision.PoseLandmarkerResult
VisionRunningMode = mp.tasks.vision.RunningMode

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

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

with PoseLandmarker.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_poses`	Pose Landmarker 可偵測的姿勢數量上限。	`Integer > 0`	`1`
`min_pose_detection_confidence`	系統判定姿勢偵測成功的最低可信度分數。	`Float [0.0,1.0]`	`0.5`
`min_pose_presence_confidence`	姿勢地標偵測中姿勢存在分數的最低可信度分數。	`Float [0.0,1.0]`	`0.5`
`min_tracking_confidence`	系統判定姿勢追蹤成功的最低可信度分數。	`Float [0.0,1.0]`	`0.5`
`output_segmentation_masks`	是否為偵測到的姿勢輸出區隔遮罩。	`Boolean`	`False`
`result_callback`	在 Pose Landmarker 處於即時串流模式時，將結果事件監聽器設為以非同步方式接收地標結果。只有在執行模式設為 `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)

執行工作

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

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

圖片

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

影片

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

直播

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

注意事項：

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

如需在圖像上執行姿勢地標的完整範例，請參閱程式碼範例。

處理及顯示結果

Pose Landmarker 會針對每次偵測作業傳回 poseLandmarkerResult 物件。結果物件包含每個姿勢地標的座標。

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

PoseLandmarkerResult:
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : 0.129959
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
      visibility   : 0.999909
      presence     : 0.999958
    ... (33 landmarks per pose)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
      visibility   : 0.999976
      presence     : 0.999998
    ... (33 world landmarks per pose)
  SegmentationMasks:
    ... (pictured below)

輸出結果會包含每個地標的歸一化座標 (Landmarks) 和世界座標 (WorldLandmarks)。

輸出內容包含下列標準化座標 (Landmarks)：

x 和 y：以圖片寬度 (x) 和高度 (y) 為基準，將地標座標正規化為介於 0.0 和 1.0 之間的值。
z：地標深度，以臀部中點的深度做為原點。值越小，地標離相機越近。z 的大小會使用與 x 大致相同的比例。
visibility：地標在圖片中顯示的可能性。

輸出內容包含下列世界座標 (WorldLandmarks)：

x、y 和 z：以公尺為單位的實際 3D 座標，以臀部中點做為原點。
visibility：地標在圖片中顯示的可能性。

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

一名女子正在打坐冥想。她的姿勢以線框標示，指出四肢和軀幹的位置

選用的分割遮罩代表每個像素屬於偵測到的人物的可能性。以下圖片是工作輸出的區隔遮罩：

上一個圖片的區隔遮罩，勾勒出女性的形狀

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