ImageAnalysis
public
final
class
ImageAnalysis
extends UseCase
java.lang.Object | ||
↳ | 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 | |
---|---|
interface |
ImageAnalysis.Analyzer
Interface for analyzing images. |
class |
ImageAnalysis.Builder
Builder for a |
Constants | |
---|---|
int |
STRATEGY_BLOCK_PRODUCER
Block the producer from generating new images. |
int |
STRATEGY_KEEP_ONLY_LATEST
Only deliver the latest image to the analyzer, dropping images as they arrive. |
Public methods | |
---|---|
void
|
clearAnalyzer()
Removes a previously set analyzer. |
int
|
getBackpressureStrategy()
Returns the mode with which images are acquired from the image producer. |
int
|
getImageQueueDepth()
Returns the number of images available to the camera pipeline, including the image being
analyzed, for the |
int
|
getTargetRotation()
Returns the rotation of the intended target for images. |
void
|
setAnalyzer(Executor executor, ImageAnalysis.Analyzer analyzer)
Sets an analyzer to receive and analyze images. |
void
|
setTargetRotation(int rotation)
Sets the target rotation. |
String
|
toString()
|
Inherited methods | |
---|---|
Constants
STRATEGY_BLOCK_PRODUCER
public static final int STRATEGY_BLOCK_PRODUCER
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
ImageAnalysis.Builder.setImageQueueDepth(int)
.
Constant Value: 1 (0x00000001)
STRATEGY_KEEP_ONLY_LATEST
public static final int STRATEGY_KEEP_ONLY_LATEST
Only deliver the latest image to the analyzer, dropping images as they arrive.
This strategy ignores the value set by ImageAnalysis.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
ImageAnalysis.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.
Constant Value: 0 (0x00000000)
Public methods
clearAnalyzer
public void clearAnalyzer ()
Removes a previously set analyzer.
This will stop data from streaming to the ImageAnalysis
.
getBackpressureStrategy
public int getBackpressureStrategy ()
Returns the mode with which images are acquired from the image producer.
The backpressure strategy is set when constructing an ImageAnalysis
instance using
ImageAnalysis.Builder.setBackpressureStrategy(int)
. If not set, it defaults to
STRATEGY_KEEP_ONLY_LATEST
.
Returns | |
---|---|
int |
The backpressure strategy applied to the image producer. |
getImageQueueDepth
public int getImageQueueDepth ()
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.
Returns | |
---|---|
int |
The image queue depth for the STRATEGY_BLOCK_PRODUCER backpressure mode. |
getTargetRotation
public int getTargetRotation ()
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
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.
Returns | |
---|---|
int |
The rotation of the intended target for images. |
See also:
setAnalyzer
public void setAnalyzer (Executor executor, ImageAnalysis.Analyzer analyzer)
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 ImageAnalysis.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
public void setTargetRotation (int rotation)
Sets the target rotation.
This adjust the ImageInfo.getRotationDegrees()
of the ImageProxy
passed
to ImageAnalysis.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 ImageAnalysis.Builder.setTargetRotation(int)
, using
setTargetRotation(int)
allows the target rotation to be set
dynamically.
In general, it is best to use an 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
setTargetRotation(int)
to set target rotation dynamically according to
the 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.
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
public String toString ()
Returns | |
---|---|
String |
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2021-02-24 UTC.