網頁版的姿勢地標偵測指南

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

這些操作說明將說明如何使用 Pose Landmarker 的網頁和 JavaScript 應用程式。如要進一步瞭解這項工作的功能、模型和設定選項，請參閱總覽。

程式碼範例

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

設定

本節將說明設定開發環境的關鍵步驟，特別是使用姿勢地標功能。如要進一步瞭解如何設定網路和 JavaScript 開發環境，包括平台版本需求，請參閱網路設定指南。

JavaScript 套件

您可以透過 MediaPipe @mediapipe/tasks-vision NPM 套件取得姿勢地標程式碼。您可以按照平台設定指南中的操作說明，尋找及下載這些程式庫。

您可以使用下列指令，透過 NPM 安裝必要套件：

npm install @mediapipe/tasks-vision

如果您想透過內容傳遞網路 (CDN) 服務匯入工作程式碼，請在 HTML 檔案的 <head> 代碼中加入以下程式碼：

<!-- You can replace JSDeliver with another CDN if you prefer -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
    crossorigin="anonymous"></script>
</head>

型號

MediaPipe 姿勢標記器工作需要訓練的模型，且必須與此工作相容。如要進一步瞭解可用訓練模型的姿勢地標，請參閱工作總覽的「模型」一節。

選取並下載模型，然後將模型儲存在專案目錄中：

<dev-project-root>/app/shared/models/

建立工作

使用其中一個 Pose Landmarker createFrom...() 函式，準備執行推論的工作。使用 createFromModelPath() 函式搭配訓練模型檔案的相對或絕對路徑。如果模型已載入至記憶體，您可以使用 createFromModelBuffer() 方法。

以下程式碼範例示範如何使用 createFromOptions() 函式設定工作。createFromOptions() 函式可讓您使用設定選項自訂姿勢地標。如要進一步瞭解設定選項，請參閱「設定選項」。

以下程式碼示範如何使用自訂選項建構及設定工作：

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const poseLandmarker = await poseLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "path/to/model"
      },
      runningMode: runningMode
    });

設定選項

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

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

IMAGE：單張圖片輸入模式。

影片：解碼影片影格或輸入資料 (例如來自攝影機) 直播的模式。		 {IMAGE, VIDEO} IMAGE
numPoses Pose Landmarker 可偵測的姿勢數量上限。 Integer > 0 1
minPoseDetectionConfidence 系統判定姿勢偵測成功的最低可信度分數。 Float [0.0,1.0] 0.5
minPosePresenceConfidence 姿勢地標偵測中姿勢存在分數的最低可信度分數。 Float [0.0,1.0] 0.5
minTrackingConfidence 系統判定姿勢追蹤成功的最低可信度分數。 Float [0.0,1.0] 0.5
outputSegmentationMasks 是否為偵測到的姿勢輸出區隔遮罩。 Boolean False

準備資料

Pose Landmarker 可偵測主機瀏覽器支援的任何圖片格式中的姿勢。此工作也會處理資料輸入預先處理作業，包括調整大小、旋轉和值正規化。如要標記影片中的姿勢，您可以使用 API 一次快速處理一個影格，並利用影格的時間戳記，判斷影片中姿勢出現的時間。

執行工作

姿勢地標使用 detect() (執行模式為 IMAGE) 和 detectForVideo() (執行模式為 VIDEO) 方法觸發推論。這項工作會處理資料、嘗試標記姿勢，然後回報結果。

對 Pose Landmarker detect() 和 detectForVideo() 方法的呼叫會同步執行，並封鎖使用者插入的執行緒。如果您在裝置相機的影片影格中偵測到姿勢，每個偵測動作都會阻斷主執行緒。如要避免這種情況，您可以實作網路 worker，在另一個執行緒上執行 detect() 和 detectForVideo() 方法。

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

圖片

const image = document.getElementById("image") as HTMLImageElement;
const poseLandmarkerResult = poseLandmarker.detect(image);

影片

await poseLandmarker.setOptions({ runningMode: "VIDEO" });

let lastVideoTime = -1;
function renderLoop(): void {
  const video = document.getElementById("video");

  if (video.currentTime !== lastVideoTime) {
    const poseLandmarkerResult = poseLandmarker.detectForVideo(video);
    processResults(detections);
    lastVideoTime = video.currentTime;
  }

  requestAnimationFrame(() => {
    renderLoop();
  });
}

如要瞭解如何更完整地執行姿勢地標工作，請參閱程式碼範例。

處理及顯示結果

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：地標在圖片中顯示的可能性。

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

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

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

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

姿勢地標示例程式碼示範如何顯示工作傳回的結果，請參閱程式碼範例