Google は、黒人コミュニティに対する人種平等の促進に取り組んでいます。取り組みを見る

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 backpressure strategy.

Summary

Nested classes
abstract

Interface for analyzing images.

Builder for a ImageAnalysis.

Constants
static Int

Block the producer from generating new images.

static Int

Only deliver the latest image to the analyzer, dropping images as they arrive.

Public methods
Unit

Removes a previously set analyzer.

Int

Returns the mode with which images are acquired from the image.

Int

Returns the number of images available to the camera pipeline, including the image being analyzed, for the STRATEGY_BLOCK_PRODUCER backpressure mode.

Int

Returns the rotation of the intended target for images.

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

Sets an analyzer to receive and analyze images.

Unit

Sets the target rotation.

String

Constants

STRATEGY_BLOCK_PRODUCER

static val STRATEGY_BLOCK_PRODUCER: Int

Block the producer from generating new images.

Once the producer has produced the number of images equal to the image queue depth, and none have been closed, the producer will stop producing images. Note that images may be queued internally and not be delivered to the analyzer until the last delivered image has been closed with ImageProxy#close(). These internally queued images will count towards the total number of images that the producer can provide at any one time.

When the producer stops producing images, it may also stop producing images for other use cases, such as Preview, so it is important for the analyzer to keep up with frame rate, on average. Failure to keep up with frame rate may lead to jank in the frame stream and a diminished user experience. If more time is needed for analysis on some frames, consider increasing the image queue depth with Builder#setImageQueueDepth(int).

Value: 1

STRATEGY_KEEP_ONLY_LATEST

static val STRATEGY_KEEP_ONLY_LATEST: Int

Only deliver the latest image to the analyzer, dropping images as they arrive.

This strategy ignores the value set by Builder#setImageQueueDepth(int). Only one image will be delivered for analysis at a time. If more images are produced while that image is being analyzed, they will be dropped and not queued for delivery. Once the image being analyzed is closed by calling ImageProxy#close(), the next latest image will be delivered.

Internally this strategy may make use of an internal Executor to receive and drop images from the producer. A performance-tuned executor will be created internally unless one is explicitly provided by Builder#setBackgroundExecutor(Executor). In order to ensure smooth operation of this backpressure strategy, any user supplied Executor must be able to quickly respond to tasks posted to it, so setting the executor manually should only be considered in advanced use cases.

Value: 0

Public methods

clearAnalyzer

fun clearAnalyzer(): Unit

Removes a previously set analyzer.

This will stop data from streaming to the ImageAnalysis.

getBackpressureStrategy

fun getBackpressureStrategy(): Int

Returns the mode with which images are acquired from the image.

The backpressure strategy is set when constructing an ImageAnalysis instance using ImageAnalysis.Builder#setBackpressureStrategy(int). If not set, it defaults to ImageAnalysis#STRATEGY_KEEP_ONLY_LATEST.

Return
Int The backpressure strategy applied to the image producer.

getImageQueueDepth

fun getImageQueueDepth(): Int

Returns the number of images available to the camera pipeline, including the image being analyzed, for the STRATEGY_BLOCK_PRODUCER backpressure mode.

The image queue depth is set when constructing an ImageAnalysis instance using ImageAnalysis.Builder#setImageQueueDepth(int). If not set, and this option is used by the backpressure strategy, the default will be a queue depth of 6 images.

Return
Int The image queue depth for the STRATEGY_BLOCK_PRODUCER backpressure mode.

getTargetRotation

fun getTargetRotation(): Int

Returns the rotation of the intended target for images.

The rotation can be set when constructing an ImageAnalysis instance using ImageAnalysis.Builder#setTargetRotation(int), or dynamically by calling ImageAnalysis#setTargetRotation(int). If not set, the target rotation defaults to the value of Display#getRotation() of the default display at the time the use case is created. The use case is fully created once it has been attached to a camera.

Return
Int The rotation of the intended target for images.

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) will be run.
analyzer ImageAnalysis.Analyzer: of the images.

setTargetRotation

fun setTargetRotation(rotation: Int): Unit

Sets the target rotation.

This adjust the ImageInfo#getRotationDegrees() of the ImageProxy passed to Analyzer#analyze(ImageProxy). The rotation value of ImageInfo 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. The mapping values are listed as the following.

android.view.OrientationEventListener#ORIENTATION_UNKNOWN: orientation == -1

Surface#ROTATION_0: orientation >= 315 || orientation < 45

Surface#ROTATION_90: orientation >= 225 && orientation < 315

Surface#ROTATION_180: orientation >= 135 && orientation < 225

Surface#ROTATION_270: orientation >= 45 && orientation < 135

When this function is called, value set by ImageAnalysis.Builder#setTargetResolution(Size) will be updated automatically to make sure the suitable resolution can be selected when the use case is bound.

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. The use case is fully created once it has been attached to a camera.

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