圖片分析

圖片分析用途可為您的應用程式提供 CPU 方便存取的圖片，以供執行圖片處理作業、電腦視覺或機器學習推論。應用程式會導入在每個影格上執行的 analyze() 方法。

如要瞭解如何整合 Google 的 ML Kit 與 CameraX 應用程式，請參閱「ML Kit 分析工具」一文。

操作模式

如果應用程式的分析管道無法達到 CameraX 的畫面更新率要求，您可以透過下列任一種方式將 CameraX 設定為捨棄影格：

  • 非封鎖 (預設)：在此模式下，應用程式分析上一張圖片時，執行程式一律會將最新的圖片快取至圖片緩衝區 (類似深度為一的佇列)。如果 CameraX 在應用程式處理完成之前收到新的圖片，系統會將其儲存至同一個緩衝區，並覆寫先前的圖片。請注意，在此情況下，ImageAnalysis.Builder.setImageQueueDepth() 不會有任何作用，而緩衝區內容一律會被覆寫。您可以利用 STRATEGY_KEEP_ONLY_LATEST 呼叫 setBackpressureStrategy() 來啟動此非封鎖模式。如要進一步瞭解執行程式的影響，請參閱 STRATEGY_KEEP_ONLY_LATEST 的參考說明文件。

  • 封鎖：在此模式下，內部執行程式可將多張圖片加入內部圖片佇列，並且僅在佇列已滿時才捨棄影格。封鎖模式適用於整個相機裝置範圍：如果相機裝置有多個已繫結的用途，則在 CameraX 處理這些圖片時，這些用途均會遭到封鎖。舉例來說，如果預覽和圖片分析均繫結至「相機」裝置，那麼當 CameraX 處理圖片時，預覽也會一併遭到封鎖。將 STRATEGY_BLOCK_PRODUCER 傳遞至 setBackpressureStrategy()，即可啟用封鎖模式。您也可以使用 ImageAnalysis.Builder.setImageQueueDepth() 設定圖片佇列深度。

利用低延遲和高效能分析工具，分析圖片的總時間少於 CameraX 影格的時間 (例如 60fps 為 16 毫秒)，任何操作模式都能讓整體運作更加順暢。封鎖模式在某些情況下仍是很實用的，例如處理非常短的系統時基誤差。

利用高延遲和高效能分析工具，需要較長佇列的封鎖模式才能彌補延遲時間。但請注意，應用程式仍可以處理所有影格。

搭配使用高延遲和耗時的分析工具時 (分析工具無法處理所有影格)，非封鎖模式可能會是更好的選擇，因為分析路徑必須捨棄影格，但其他並行的繫結用途仍能看到所有影格。

導入作業

如要在應用程式中使用圖片分析，請按照下列步驟操作：

繫結後，CameraX 會立即將圖片傳送至已註冊的分析工具。完成分析後，請呼叫 ImageAnalysis.clearAnalyzer() 或解除 ImageAnalysis 用途，以便停止分析。

建構 ImageAnalysis 用途

ImageAnalysis 將您的分析工具 (圖片使用者) 連結至 CameraX，也就是圖片製作工具。應用程式可以使用 ImageAnalysis.Builder 建構 ImageAnalysis 物件。透過 ImageAnalysis.Builder，應用程式可以設定以下項目：

應用程式可以設定解析度或長寬比，但不能同時設定兩者。確切的輸出解析度會因應用程式要求的大小 (或長寬比) 和硬體功能而異，且可能會與要求的大小或比例不同。如需解析度比對演算法的相關資訊，請參閱 setTargetResolution() 的說明文件

應用程式可將輸出圖片像素設為 YUV (預設) 或 RGBA 色域。設定 RGBA 輸出格式時，CameraX 內部會將圖片從 YUV 轉換為 RGBA 色域，並依照下列順序將圖片位元封裝為 ImageProxy 第一平面的 ByteBuffer (未使用其他兩個平面)：

ImageProxy.getPlanes()[0].buffer[0]: alpha
ImageProxy.getPlanes()[0].buffer[1]: red
ImageProxy.getPlanes()[0].buffer[2]: green
ImageProxy.getPlanes()[0].buffer[3]: blue
...

執行複雜的圖片分析作業時，如果裝置無法達到畫面更新率，您可以按照本文中操作模式一節所述的策略，將 CameraX 設定為捨棄影格。

建立分析工具

應用程式透過導入 ImageAnalysis.Analyzer 介面並覆寫 analyze(ImageProxy image) 來建立分析工具。在每個分析工具中，應用程式會收到 ImageProxy，這是 Media.Image 的包裝函式。您可以使用 ImageProxy.getFormat() 查詢圖片格式。格式是應用程式透過 ImageAnalysis.Builder 提供的下列其中一個值：

  • ImageFormat.RGBA_8888 (如果應用程式要求 OUTPUT_IMAGE_FORMAT_RGBA_8888)。
  • ImageFormat.YUV_420_888 (如果應用程式要求 OUTPUT_IMAGE_FORMAT_YUV_420_888)。

請參閱建構 ImageAnalysis 用途來瞭解色域設定，以及可以擷取像素位元組的位置。

在分析工具中，應用程式應執行以下操作：

  1. 最好在特定的畫面更新率時間限制內 (例如 30 fps 時不超過 32 毫秒)，盡快分析特定影格。如果應用程式無法快速分析影格，請考慮使用其中一種支援的影格捨棄機制。
  2. 呼叫 ImageProxy.close() 即可將 ImageProxy 發布至 CameraX。請注意，您不應呼叫已包裝的 Media.Image 關閉函式 (Media.Image.close())。

應用程式可以直接在 ImageProxy 中使用已包裝的 Media.Image。請勿呼叫已包裝圖片上的 Media.Image.close()，因為這會導致 CameraX 中的圖片分享機制中斷；請改用 ImageProxy.close() 將基礎 Media.Image 發布至 CameraX。

設定 ImageAnalysis 分析工具

建立分析工具後，請使用 ImageAnalysis.setAnalyzer() 註冊並開始分析。分析完成後，請使用 ImageAnalysis.clearAnalyzer() 移除已註冊的分析工具。

只能設定一個有效的分析工具進行圖片分析。呼叫 ImageAnalysis.setAnalyzer() 會取代註冊的分析工具 (如果已存在的話)。在繫結用途前後，應用程式可以隨時設定新的分析工具。

將 ImageAnalysis 繫結至生命週期

強烈建議您使用 ProcessCameraProvider.bindToLifecycle() 函式將 ImageAnalysis 繫結至現有的 AndroidX 生命週期。請注意，bindToLifecycle() 函式會回傳所選 Camera 裝置，該裝置可用於微調曝光等進階設定。請參閱這份指南，進一步瞭解如何控制相機輸出。

以下範例組合了前述步驟中的所有內容，將 CameraX ImageAnalysis 和 Preview 用途繫結至 lifeCycle 擁有者：

Kotlin

val imageAnalysis = ImageAnalysis.Builder()
    // enable the following line if RGBA output is needed.
    // .setOutputImageFormat(ImageAnalysis.OUTPUT_IMAGE_FORMAT_RGBA_8888)
    .setTargetResolution(Size(1280, 720))
    .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
    .build()
imageAnalysis.setAnalyzer(executor, ImageAnalysis.Analyzer { imageProxy ->
    val rotationDegrees = imageProxy.imageInfo.rotationDegrees
    // insert your code here.
    ...
    // after done, release the ImageProxy object
    imageProxy.close()
})

cameraProvider.bindToLifecycle(this as LifecycleOwner, cameraSelector, imageAnalysis, preview)

Java

ImageAnalysis imageAnalysis =
    new ImageAnalysis.Builder()
        // enable the following line if RGBA output is needed.
        //.setOutputImageFormat(ImageAnalysis.OUTPUT_IMAGE_FORMAT_RGBA_8888)
        .setTargetResolution(new Size(1280, 720))
        .setBackpressureStrategy(ImageAnalysis.STRATEGY_KEEP_ONLY_LATEST)
        .build();

imageAnalysis.setAnalyzer(executor, new ImageAnalysis.Analyzer() {
    @Override
    public void analyze(@NonNull ImageProxy imageProxy) {
        int rotationDegrees = imageProxy.getImageInfo().getRotationDegrees();
            // insert your code here.
            ...
            // after done, release the ImageProxy object
            imageProxy.close();
        }
    });

cameraProvider.bindToLifecycle((LifecycleOwner) this, cameraSelector, imageAnalysis, preview);

其他資源

如要進一步瞭解 CameraX，請參閱下列其他資源。

程式碼研究室

  • 開始使用 CameraX

    • 程式碼範例

  • CameraX 範例應用程式

    •