Python 的物件偵測指南

MediaPipe 物件偵測器工作可讓您偵測多個 物件的種類。以下操作說明將示範如何使用物件偵測器 用 Python 執行一項工作如需上述操作說明中的程式碼範例，請參閱 GitHub。

您可以前往 Web 示範 查看這項工作的實際操作體驗。如要進一步瞭解功能、模型 請參閱總覽一文。

程式碼範例

物件偵測器的範例程式碼提供了 執行相關作業這個程式碼可協助您測試這項工作 並開始打造自己的文字分類應用程式您可以查看、執行 編輯物件偵測器範例程式碼 只要使用網路瀏覽器即可。

如果您要為 Raspberry Pi 實作物件偵測器，請參閱 Raspberry Pi 範例 app。

設定

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

套件

物件偵測器工作需要 mediapipe pip 套件。如要安裝 搭配下列指令：

$ 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/lite-model_efficientdet_lite0_detection_metadata_1.tflite'

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

建立工作

使用 create_from_options 函式建立工作。 create_from_options 函式接受設定選項，包括執行中 模式, 顯示名稱語言代碼, 結果數量上限, 可信度門檻 類別許可清單和拒絕清單如果沒有指定設定選項， 工作會使用預設值如要進一步瞭解設定選項 請參閱「設定選項」一節。

物件偵測器工作支援多種輸入資料類型：靜態圖片、影片 例如檔案和直播影片串流選擇與輸入資料對應的分頁 輸入瞭解如何建立工作並執行推論。

圖片

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
ObjectDetector = mp.tasks.vision.ObjectDetector
ObjectDetectorOptions = mp.tasks.vision.ObjectDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

options = ObjectDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.tflite'),
    max_results=5,
    running_mode=VisionRunningMode.IMAGE)

with ObjectDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...

影片

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
ObjectDetector = mp.tasks.vision.ObjectDetector
ObjectDetectorOptions = mp.tasks.vision.ObjectDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

options = ObjectDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.tflite'),
    max_results=5,
    running_mode=VisionRunningMode.VIDEO)

with ObjectDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...

直播

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
DetectionResult = mp.tasks.components.containers.detections.DetectionResult
ObjectDetector = mp.tasks.vision.ObjectDetector
ObjectDetectorOptions = mp.tasks.vision.ObjectDetectorOptions
VisionRunningMode = mp.tasks.vision.RunningMode

def print_result(result: DetectionResult, output_image: mp.Image, timestamp_ms: int):
    print('detection result: {}'.format(result))

options = ObjectDetectorOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.tflite'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    max_results=5,
    result_callback=print_result)

with ObjectDetector.create_from_options(options) as detector:
  # The detector is initialized. Use it here.
  # ...

如需建立物件偵測工具以與圖片搭配使用的完整範例，請參閱 程式碼範例。

設定選項

這項工作有下列 Python 應用程式設定選項：

選項名稱 說明 值範圍 預設值
running_mode 設定任務的執行模式。在架構中 模式：

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

VIDEO：影片已解碼的影格模式。

LIVE_STREAM：輸入串流模式 擷取的資訊等。在此模式下， resultListener 設定接聽程式來接收結果 以非同步方式載入物件		 {IMAGE, VIDEO, LIVE_STREAM} IMAGE
display_names 設定標籤語言，供 工作模型的中繼資料 (如有)。以下項目的預設值為 en： 英語。您可以在自訂模型的中繼資料中加入經本地化的標籤 使用 TensorFlow Lite Metadata Writer API 語言代碼 en
max_results 將最高分數偵測結果的選用數量上限設為 傳回。 任何正數 -1 (傳回所有結果)
score_threshold 設定預測分數門檻，此門檻會覆寫 模型中繼資料 (如有)低於這個值的結果遭到拒絕。 任何浮點值 未設定
category_allowlist 設定允許使用的類別名稱清單 (選用)。如果非空白 如果偵測結果出的類別名稱不在這個組合中，系統就會將其 過濾掉。系統會忽略重複或不明的類別名稱。 這個選項與 category_denylist 互斥， 這兩個都會造成錯誤。 任何字串 未設定
category_denylist 設定不允許使用的類別名稱清單 (選填)。如果 非空白的偵測結果，如果偵測結果中屬於這個組合的類別名稱，系統就會加以篩選 。系統會忽略重複或不明的類別名稱。這個選項會互相影響 只使用 category_allowlist 且同時使用兩者都會發生錯誤。 任何字串 未設定

準備資料

準備輸入圖片檔案或 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)

執行工作

您可以呼叫其中一個偵測工具來觸發推論。物件 偵測器工作會傳回在輸入圖片或影格中偵測到的物件。

圖片

# Perform object detection on the provided single image.
detection_result = detector.detect(mp_image)

影片

# Calculate the timestamp of the current frame
frame_timestamp_ms = 1000 * frame_index / video_file_fps

# Perform object detection on the video frame.
detection_result = detector.detect_for_video(mp_image, frame_timestamp_ms)

直播

# Send the latest frame to perform object detection.
# Results are sent to the `result_callback` provided in the `ObjectDetectorOptions`.
detector.detect_async(mp_image, frame_timestamp_ms)

如需對圖片執行物件偵測器的完整範例，請參閱 程式碼範例。

注意事項：

  • 以錄影模式或直播模式執行時，你也必須 提供物件偵測器工作，做為輸入影格的時間戳記。
  • 在圖片或影片模型中執行時，物件偵測器工作 封鎖目前的執行緒，直到處理完成輸入圖片， 相框。
  • 在直播模式下執行時，物件偵測器工作不會封鎖 但會立即傳回這會叫用結果 並傳送偵測結果 輸入影格如果在物件偵測器工作時呼叫了偵測工具 正忙於處理其他影格，系統會忽略新的輸入框。

處理及顯示結果

執行推論時，物件偵測器工作會傳回 ObjectDetectionResult 物件，用來說明在物件中找到的物件 生成圖片

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

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

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

物件偵測器程式碼範例示範如何顯示偵測作業 查看工作傳回的結果 程式碼範例 。