ImageAnalysis

class ImageAnalysis : UseCase
kotlin.Any
   ↳ androidx.camera.core.UseCase
   ↳ androidx.camera.core.ImageAnalysis

A use case providing CPU accessible images for an app to perform image analysis on.

ImageAnalysis acquires images from the camera via an ImageReader. Each image is provided to an ImageAnalysis.Analyzer function which can be implemented by application code, where it can access image data for application analysis via an ImageProxy.

The application is responsible for calling ImageProxy#close() to close the image. Failing to close the image will cause future images to be stalled or dropped depending on the BackpressureStrategy.

Summary

Nested classes

abstract

Interface for analyzing images.

How to apply backpressure to the source producing images for analysis.

Builder for a ImageAnalysis.

Public methods

Unit

Removes a previously set analyzer.

Unit
setAnalyzer(@NonNull executor: Executor, @NonNull analyzer: ImageAnalysis.Analyzer)

Sets an analyzer to receive and analyze images.

Unit

Sets the target rotation.

String

Public methods

clearAnalyzer

fun clearAnalyzer(): Unit

Removes a previously set analyzer.

This will stop data from streaming to the ImageAnalysis.

setAnalyzer

fun setAnalyzer(@NonNull executor: Executor, @NonNull analyzer: ImageAnalysis.Analyzer): Unit

Sets an analyzer to receive and analyze images.

Setting an analyzer will signal to the camera that it should begin sending data. The stream of data can be stopped by calling clearAnalyzer().

Applications can process or copy the image by implementing the Analyzer. If frames should be skipped (no analysis), the analyzer function should return, instead of disconnecting the analyzer function completely.

Setting an analyzer function replaces any previous analyzer. Only one analyzer can be set at any time.

Parameters
executor Executor: The executor in which the ImageAnalysis.Analyzer#analyze(ImageProxy, int) will be run.
analyzer Executor: of the images.

setTargetRotation

fun setTargetRotation(rotation: Int): Unit

Sets the target rotation.

This informs the use case so it can adjust the rotation value sent to Analyzer#analyze(ImageProxy, int) which provides rotation information to the analysis method. The rotation parameter sent to the analyzer will be the rotation, which if applied to the output image, will make the image match target rotation specified here.

While rotation can also be set via Builder#setTargetRotation(int), using ImageAnalysis#setTargetRotation(int) allows the target rotation to be set dynamically.

In general, it is best to use an android.view.OrientationEventListener to set the target rotation. This way, the rotation output to the Analyzer will indicate which way is down for a given image. This is important since display orientation may be locked by device default, user setting, or app configuration, and some devices may not transition to a reverse-portrait display orientation. In these cases, use ImageAnalysis#setTargetRotation to set target rotation dynamically according to the android.view.OrientationEventListener, without re-creating the use case. Note the OrientationEventListener output of degrees in the range [0..359] should be converted to a surface rotation, i.e. one of Surface#ROTATION_0, Surface#ROTATION_90, Surface#ROTATION_180, or Surface#ROTATION_270.

If not set here or by configuration, the target rotation will default to the value of Display#getRotation() of the default display at the time the use case is created.

Parameters
rotation Int: Target rotation of the output image, expressed as one of Surface#ROTATION_0, Surface#ROTATION_90, Surface#ROTATION_180, or Surface#ROTATION_270.

toString

@NonNull fun toString(): String