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

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

Android 物件偵測指南

「物件偵測器」工作可讓您偵測多個實體是否存在和位置物件的種類。舉例來說，物件偵測器可以找出圖片。下列操作說明示範如何在以下項目中使用物件偵測器工作： Android。如需上述指示中所述的程式碼範例，請前往 GitHub。您可以查看這項工作，瞭解這項工作的實際運作情形網頁示範。進一步瞭解功能、模型和設定選項請參閱總覽。

程式碼範例

MediaPipe 工作範例程式碼是物件偵測器的簡易實作方式 App Engine 應用程式這個範例會使用實體 Android 裝置上的相機執行以下動作：會持續偵測物件，也可使用靜態偵測物件

您可以將應用程式做為起點，當做 Android 應用程式的起點，也可以參照應用程式做出決定物件偵測器程式碼範例 GitHub。

下載程式碼

以下說明如何建立範例的本機副本 git 指令列工具編寫程式碼。

如要下載範例程式碼，請按照下列步驟操作：

使用下列指令複製 git 存放區：

git clone https://github.com/google-ai-edge/mediapipe-samples

您也可以選擇設定 Git 執行個體，以使用稀疏結帳功能。因此，您只擁有物件偵測器範例應用程式的檔案：
```
cd mediapipe
git sparse-checkout init --cone
git sparse-checkout set examples/object_detection/android
```

建立範例程式碼的本機版本後，您可以匯入專案然後執行應用程式如需操作說明，請參閱 Android 設定指南。

重要元件

下列檔案包含物件偵測器的重要程式碼應用程式範例：

ObjectDetectorHelper.kt：初始化物件偵測工具並處理模型與委派選項
MainActivity.kt：實作應用程式並組合使用者介面元件
OverlayView.kt - 處理並顯示結果

設定

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

依附元件

物件偵測器會使用 com.google.mediapipe:tasks-vision 程式庫。新增此項目 build.gradle 檔案的依附元件 Android 應用程式開發專案。使用下列指令匯入必要的依附元件下列程式碼：

dependencies {
    implementation 'com.google.mediapipe:tasks-vision:latest.release'
}

型號

MediaPipe 物件偵測器工作需要與這個模型相容的已訓練模型工作。如要進一步瞭解物件偵測工具可用的已訓練模型，請參閱：工作總覽的「模型」一節。

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

<dev-project-root>/src/main/assets

使用 BaseOptions.Builder.setModelAssetPath() 方法指定路徑以便訓練模型如需程式碼範例，請參閱下一節。

建立工作

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

物件偵測器工作支援 3 種輸入資料類型：靜態圖片、影片檔案和即時影像串流您必須指定相應的執行模式輸入資料類型請選擇與輸入資料類型，瞭解如何建立工作及執行推論。

圖片

ObjectDetectorOptions options =
  ObjectDetectorOptions.builder()
    .setBaseOptions(BaseOptions.builder().setModelAssetPath(‘model.tflite’).build())
    .setRunningMode(RunningMode.IMAGE)
    .setMaxResults(5)
    .build();
objectDetector = ObjectDetector.createFromOptions(context, options);

影片

ObjectDetectorOptions options =
  ObjectDetectorOptions.builder()
    .setBaseOptions(BaseOptions.builder().setModelAssetPath(‘model.tflite’).build())
    .setRunningMode(RunningMode.VIDEO)
    .setMaxResults(5)
    .build();
objectDetector = ObjectDetector.createFromOptions(context, options);

直播

ObjectDetectorOptions options =
  ObjectDetectorOptions.builder()
    .setBaseOptions(BaseOptions.builder().setModelAssetPath(‘model.tflite’).build())
    .setRunningMode(RunningMode.LIVE_STREAM)
    .setMaxResults(5)
    .setResultListener((result, inputImage) -> {
      // Process the detection result here.
    })
    .setErrorListener((result, inputImage) -> {
      // Process the classification errors here.
    })
   .build();
objectDetector = ObjectDetector.createFromOptions(context, options);

物件偵測器程式碼範例導入方式可讓使用者切換使用處理模式這種方法使得工作建立程式碼變得更加複雜，可能會不適合您的用途您可以在 ObjectDetectorHelper敬上 setupObjectDetector() 類別函式。

設定選項

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

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

準備資料

您需要將輸入圖片或影格轉換為 com.google.mediapipe.framework.image.MPImage 物件，然後再將該物件傳送至物件偵測器。

以下範例說明如何準備資料，以便進行處理每種可用資料類型：

圖片

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load an image on the user’s device as a Bitmap object using BitmapFactory.

// Convert an Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(bitmap).build();

影片

import com.google.mediapipe.framework.image.BitmapImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Load a video file on the user's device using MediaMetadataRetriever

// From the video’s metadata, load the METADATA_KEY_DURATION and
// METADATA_KEY_VIDEO_FRAME_COUNT values. Use these values
// to calculate the timestamp of each frame later.

// Loop through the video and load each frame as a Bitmap object.

// Convert the Android’s Bitmap object to a MediaPipe’s Image object.
Image mpImage = new BitmapImageBuilder(frame).build();

直播

import com.google.mediapipe.framework.image.MediaImageBuilder;
import com.google.mediapipe.framework.image.MPImage;

// Create a CameraX’s ImageAnalysis to continuously receive frames
// from the device’s camera. Configure it to output frames in RGBA_8888
// format to match with what is required by the model.

// For each Android’s ImageProxy object received from the ImageAnalysis,
// extract the encapsulated Android’s Image object and convert it to
// a MediaPipe’s Image object.
android.media.Image mediaImage = imageProxy.getImage()
MPImage mpImage = new MediaImageBuilder(mediaImage).build();

在物件偵測器程式碼範例中，資料準備會在 ObjectDetectorHelper敬上 detectImage()、detectVideoFile()、detectLivestreamFrame() 中的類別函式。

執行工作

請根據您處理的資料類型使用該資料類型專屬的 ObjectDetector.detect...() 方法。使用 detect() 適用於個別映像檔， detectForVideo() 適用於影片檔案中的影格 detectAsync() 代表影片串流。當您對某個網路類型執行偵測時影片串流，請務必在另外的執行緒執行偵測，以免並封鎖使用者介面執行緒

下列程式碼範例顯示瞭如何執行物件偵測工具的簡易範例分別是

圖片

ObjectDetectorResult detectionResult = objectDetector.detect(image);

影片

// Calculate the timestamp in milliseconds of the current frame.
long frame_timestamp_ms = 1000 * video_duration * frame_index / frame_count;

// Run inference on the frame.
ObjectDetectorResult detectionResult =
    objectDetector.detectForVideo(image, frameTimestampMs);

直播

// Run inference on the frame. The detection results will be available
// via the `resultListener` provided in the `ObjectDetectorOptions` when
// the object detector was created.
objectDetector.detectAsync(image, frameTimestampMs);

物件偵測器程式碼範例會顯示詳細介紹模式 detect()、 detectVideoFile(), 和 detectAsync()。程式碼範例可讓使用者切換處理模式但這不一定是你的用途

注意事項：

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

處理及顯示結果

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

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

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

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

物件偵測器程式碼範例示範如何顯示偵測作業查看工作傳回的結果 OverlayView敬上類別，取得更多詳細資訊。