網頁的物件偵測指南

MediaPipe 物件偵測器工作可偵測多個類別的物件，以及這些物件的位置。這項工作會接收圖片資料，並輸出偵測結果清單，其中每個結果都代表圖片中識別出的物件。您只需使用網路瀏覽器，即可查看、執行及編輯 Object Detector 範例。

如要進一步瞭解這項工作的各項功能、模型和設定選項，請參閱總覽。

設定

本節說明設定開發環境的主要步驟，特別是使用物件偵測器時。如要瞭解如何設定網頁和 JavaScript 開發環境 (包括平台版本需求)，請參閱網頁設定指南。

JavaScript 套件

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

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

npm install @mediapipe/tasks-vision

如要透過內容傳遞網路 (CDN) 服務匯入工作程式碼，請在 HTML 檔案的 <head> 標記中新增下列程式碼：

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

型號

MediaPipe 物件偵測器工作需要與這項工作相容的訓練模型。如要進一步瞭解物件偵測器可用的訓練模型，請參閱「模型」部分的任務總覽。

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

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

建立工作

使用其中一個物件偵測器 ObjectDetector.createFrom...() 函式，準備執行推論作業。使用 createFromModelPath() 函式，搭配訓練好的模型檔案的相對或絕對路徑。如果模型已載入記憶體，可以使用 createFromModelBuffer() 方法。下列程式碼範例示範如何使用 createFromOptions() 函式，設定更多設定選項。如要進一步瞭解可用的設定選項，請參閱「設定選項」一節。

以下程式碼示範如何建構及設定這項工作：

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
objectDetector = await ObjectDetector.createFromOptions(vision, {
  baseOptions: {
    modelAssetPath: `https://storage.googleapis.com/mediapipe-tasks/object_detector/efficientdet_lite0_uint8.tflite`
  },
  scoreThreshold: 0.5,
  runningMode: runningMode
});

如要完整瞭解如何建立物件偵測器工作，請參閱程式碼範例。

設定選項

這項工作提供下列 Web 應用程式設定選項：

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

IMAGE：單一圖片輸入模式。

VIDEO：用於影片解碼影格的模式，或用於輸入資料的直播，例如來自攝影機的資料。		 {IMAGE, VIDEO} IMAGE
displayNamesLocale 如果工作模型的中繼資料提供顯示名稱，則設定要使用的標籤語言。英文的預設值為 en。您可以使用 TensorFlow Lite Metadata Writer API，為自訂模型的中繼資料新增本地化標籤。 地區代碼 en
maxResults 設定要傳回的最高得分偵測結果數量上限 (選用)。 任何正數 -1 (傳回所有結果)
scoreThreshold 設定預測分數門檻，覆寫模型中繼資料 (如有) 提供的門檻。低於這個值的分數會遭到拒絕。 任何浮點數 未設定
categoryAllowlist 設定允許的類別名稱選用清單。如果這個集合不為空，系統會篩除類別名稱不在這個集合中的偵測結果。系統會忽略重複或不明的類別名稱。 這個選項與 categoryDenylist 互斥，同時使用兩者會導致錯誤。 任何字串 未設定
categoryDenylist 設定選用的不允許類別名稱清單。如果這個集合不為空，系統會篩除類別名稱位於這個集合中的偵測結果。系統會忽略重複或不明的類別名稱。這個選項與 categoryAllowlist 互斥，同時使用兩者會導致錯誤。 任何字串 未設定

準備資料

Object Detector 可偵測主機瀏覽器支援的任何格式圖片中的物件。這項工作也會處理資料輸入預先處理作業，包括調整大小、旋轉和值正規化。如要偵測影片中的物件，可以使用 API 快速處理每個影格，並根據影格的時間戳記判斷手勢在影片中出現的時間。

執行工作

物件偵測工具會使用 detect() 處理單一圖片，並使用 detectForVideo() 偵測影片影格中的物件。這項工作會處理資料、嘗試辨識物件，然後回報結果。

對 detect() 和 detectForVideo() 方法的呼叫會同步執行，並封鎖使用者介面執行緒。如果辨識裝置攝影機拍攝的影片影格中的物件，每個分類都會封鎖主要執行緒。如要避免這種情況，請實作網頁工作人員，在另一個執行緒上執行偵測作業。

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

圖片

const image = document.getElementById("image") as HTMLImageElement;
const detections = objectDetector.detect(image);

影片

await objectDetector.setOptions({ runningMode: "video" });

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

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

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

如要更完整地瞭解如何執行物件偵測器工作，請參閱程式碼範例。

處理及顯示結果

Object Detector 會為每次偵測作業產生偵測結果物件。 結果物件包含偵測項目清單，每個偵測項目都包含偵測到物件的定界框和類別資訊，包括物件名稱和可信度分數。

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

ObjectDetectorResult:
 Detection #0:
  Box: (x: 355, y: 133, w: 190, h: 206)
  Categories:
   index       : 17
   score       : 0.73828
   class name  : dog
 Detection #1:
  Box: (x: 103, y: 15, w: 138, h: 369)
  Categories:
   index       : 17
   score       : 0.73047
   class name  : dog

下圖顯示工作輸出內容的視覺化效果：

以定界框標示的兩隻狗

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