網頁的物件偵測指南

MediaPipe 物件偵測工具工作可讓您偵測多個物件類別是否存在，以及其位置。這項工作會擷取圖片資料並輸出偵測結果清單，每個清單都代表圖片中識別的物件。如需這些操作說明所述的程式碼範例，請前往 CodePen。

如要查看這項工作的運作情形，請查看示範。如要進一步瞭解這項工作的功能、模型和設定選項，請參閱總覽。

程式碼範例

物件偵測工具的範例程式碼提供這項工作的完整實作方式 (以 JavaScript 表示)。這個程式碼可協助您測試這項工作，並開始建構您自己的文字分類應用程式。您可以使用網路瀏覽器來檢視、執行及編輯物件偵測工具範例程式碼。

設定

本節將特別說明設定開發環境的重要步驟，以便使用物件偵測工具。如需瞭解如何設定網站和 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 to -->
<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/

建立工作

使用其中一個物件偵測工具 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
});

如需建立物件偵測工具工作的完整實作方式，請參閱程式碼範例。

設定選項

這項工作的網頁應用程式設定選項如下：

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

準備資料

物件偵測工具可以偵測主機瀏覽器所支援任何格式的圖片物件，這項工作也會處理資料輸入預先處理，包括調整大小、旋轉和值正規化。如要偵測影片中的物件，您可以使用 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();
  });
}

如需更完整的實作物件偵測工具工作實作，請參閱程式碼範例。

處理並顯示結果

物件偵測工具會在每次執行偵測時產生偵測結果物件，結果物件包含偵測清單，其中每項偵測都含有與偵測到的物件相關的定界框和類別資訊，包括物體名稱和可信度分數。

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

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

下圖以視覺化方式呈現工作輸出內容：

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