ImageCapture
public
final
class
ImageCapture
extends UseCase
java.lang.Object | ||
↳ | androidx.camera.core.UseCase | |
↳ | androidx.camera.core.ImageCapture |
A use case for taking a picture.
This class is designed for basic picture taking. It provides takePicture() functions to take a picture to memory or save to a file, and provides image metadata. Pictures are taken in automatic mode after focus has converged. The flash mode can additionally be set by the application.
TakePicture returns immediately and a listener is called to provide the results after the capture completes. Multiple calls to takePicture will take pictures sequentially starting after the previous picture is captured.
Note that focus and exposure metering regions can be controlled via Preview
.
When capturing to memory, the captured image is made available through an ImageProxy
via an ImageCapture.OnImageCapturedCallback
.
Summary
Nested classes | |
---|---|
class |
ImageCapture.Builder
Builder for an |
class |
ImageCapture.Metadata
Holder class for metadata that will be saved with captured images. |
class |
ImageCapture.OnImageCapturedCallback
Callback for when an image capture has completed. |
interface |
ImageCapture.OnImageSavedCallback
Listener containing callbacks for image file I/O events. |
class |
ImageCapture.OutputFileOptions
Options for saving newly captured image. |
class |
ImageCapture.OutputFileResults
Info about the saved image file. |
Constants | |
---|---|
int |
CAPTURE_MODE_MAXIMIZE_QUALITY
Optimizes capture pipeline to prioritize image quality over latency. |
int |
CAPTURE_MODE_MINIMIZE_LATENCY
Optimizes capture pipeline to prioritize latency over image quality. |
int |
ERROR_CAMERA_CLOSED
An error indicating the request cannot be done due to camera is closed. |
int |
ERROR_CAPTURE_FAILED
An error reported by camera framework indicating the capture request is failed. |
int |
ERROR_FILE_IO
An error occurred while attempting to read or write a file, such as when saving an image to a File. |
int |
ERROR_INVALID_CAMERA
An error indicating this ImageCapture is not bound to a valid camera. |
int |
ERROR_UNKNOWN
An unknown error occurred. |
int |
FLASH_MODE_AUTO
|
int |
FLASH_MODE_OFF
No flash. |
int |
FLASH_MODE_ON
Always flash. |
Public methods | |
---|---|
int
|
getCaptureMode()
Returns the set capture mode. |
int
|
getFlashMode()
Get the flash mode. |
int
|
getTargetRotation()
Returns the desired rotation of the output image. |
void
|
setCropAspectRatio(Rational aspectRatio)
Sets target cropping aspect ratio for output image. |
void
|
setFlashMode(int flashMode)
Set the flash mode. |
void
|
setTargetRotation(int rotation)
Sets the desired rotation of the output image. |
void
|
takePicture(Executor executor, ImageCapture.OnImageCapturedCallback callback)
Captures a new still image for in memory access. |
void
|
takePicture(ImageCapture.OutputFileOptions outputFileOptions, Executor executor, ImageCapture.OnImageSavedCallback imageSavedCallback)
Captures a new still image and saves to a file along with application specified metadata. |
String
|
toString()
|
Inherited methods | |
---|---|
Constants
CAPTURE_MODE_MAXIMIZE_QUALITY
public static final int CAPTURE_MODE_MAXIMIZE_QUALITY
Optimizes capture pipeline to prioritize image quality over latency. When the capture mode is set to MAX_QUALITY, images may take longer to capture.
Constant Value: 0 (0x00000000)
CAPTURE_MODE_MINIMIZE_LATENCY
public static final int CAPTURE_MODE_MINIMIZE_LATENCY
Optimizes capture pipeline to prioritize latency over image quality. When the capture mode is set to MIN_LATENCY, images may capture faster but the image quality may be reduced.
Constant Value: 1 (0x00000001)
ERROR_CAMERA_CLOSED
public static final int ERROR_CAMERA_CLOSED
An error indicating the request cannot be done due to camera is closed.
Constant Value: 3 (0x00000003)
ERROR_CAPTURE_FAILED
public static final int ERROR_CAPTURE_FAILED
An error reported by camera framework indicating the capture request is failed.
Constant Value: 2 (0x00000002)
ERROR_FILE_IO
public static final int ERROR_FILE_IO
An error occurred while attempting to read or write a file, such as when saving an image to a File.
Constant Value: 1 (0x00000001)
ERROR_INVALID_CAMERA
public static final int ERROR_INVALID_CAMERA
An error indicating this ImageCapture is not bound to a valid camera.
Constant Value: 4 (0x00000004)
ERROR_UNKNOWN
public static final int ERROR_UNKNOWN
An unknown error occurred.
See message parameter in onError callback or log for more details.
Constant Value: 0 (0x00000000)
FLASH_MODE_AUTO
public static final int FLASH_MODE_AUTO
Constant Value: 0 (0x00000000)
FLASH_MODE_OFF
public static final int FLASH_MODE_OFF
No flash. The flash will never be used when taking a picture.
Constant Value: 2 (0x00000002)
FLASH_MODE_ON
public static final int FLASH_MODE_ON
Always flash. The flash will always be used when taking a picture.
Constant Value: 1 (0x00000001)
Public methods
getCaptureMode
public int getCaptureMode ()
Returns the set capture mode.
This is set when constructing an ImageCapture using
ImageCapture.Builder.setCaptureMode(int)
. This is static for an instance of
ImageCapture.
Returns | |
---|---|
int |
getFlashMode
public int getFlashMode ()
Get the flash mode.
Returns | |
---|---|
int |
the flashMode. Value is FLASH_MODE_AUTO , FLASH_MODE_ON , or
FLASH_MODE_OFF .
|
getTargetRotation
public int getTargetRotation ()
Returns the desired rotation of the output image.
The rotation can be set prior to constructing an ImageCapture using
ImageCapture.Builder.setTargetRotation(int)
or dynamically by calling
setTargetRotation(int)
. The rotation of an image taken is determined
by the rotation value set at the time image capture is initiated, such as when calling
takePicture(Executor, OnImageCapturedCallback)
.
If no target rotation is set by the application, it is set 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. |
setCropAspectRatio
public void setCropAspectRatio (Rational aspectRatio)
Sets target cropping aspect ratio for output image.
This aspect ratio is orientation-dependent. It should be expressed in the coordinate frame after rotating the image by the target rotation.
This sets the cropping rectangle returned by ImageProxy.getCropRect()
returned
from takePicture(Executor, OnImageCapturedCallback)
.
For example, assume the aspectRatio
of 3x4. If an image has a resolution of
480x640 after applying the target rotation, then the output ImageProxy
of
takePicture(Executor, OnImageCapturedCallback)
would have a cropping
rectangle of 480x640 after applying the rotation degrees. However, if an image has a
resolution of 640x480 after applying the target rotation, then the cropping rectangle
of the output ImageProxy
would be 360x480 after applying the rotation degrees.
This crops the saved image when calling
takePicture(OutputFileOptions, Executor, OnImageSavedCallback)
. Note
that the cropping will introduce an additional latency.
Cropping occurs around the center of the image and as though it were in the target
rotation. For example, assume the aspectRatio
of 3x4. If an image has a resolution
of 480x640 after applying the target rotation, then the saved output image would be
480x640 after applying the EXIF orientation value. However, if an image has a resolution
of 640x480 after applying the target rotation, then the saved output image would be
360x480 after applying the EXIF orientation value.
This setting value will be automatically updated to match the new target rotation value
when setTargetRotation(int)
is called.
Parameters | |
---|---|
aspectRatio |
Rational : New target aspect ratio.
|
setFlashMode
public void setFlashMode (int flashMode)
Set the flash mode.
The flash control for the subsequent photo capture requests. Applications can check if
there is a flash unit via CameraInfo.hasFlashUnit()
and update UI component if
necessary. If there is no flash unit, then calling this API will take no effect for the
subsequent photo capture requests and they will act like FLASH_MODE_OFF
.
When the torch is enabled via CameraControl.enableTorch(boolean)
, the torch
will remain enabled during photo capture regardless of flashMode setting. When
the torch is disabled, flash will function as specified by setFlashMode(int)
.
On some LEGACY devices like Samsung A3, taking pictures with FLASH_MODE_AUTO
mode could cause a crash. To workaround this CameraX will disable the auto flash behavior
internally on devices that have this issue.
Parameters | |
---|---|
flashMode |
int : the flash mode. Value is FLASH_MODE_AUTO , FLASH_MODE_ON ,
or FLASH_MODE_OFF .
|
setTargetRotation
public void setTargetRotation (int rotation)
Sets the desired rotation of the output image.
This will affect the EXIF rotation metadata in images saved by takePicture calls and the
ImageInfo.getRotationDegrees()
value of the ImageProxy
returned by
ImageCapture.OnImageCapturedCallback
. These will be set to be the rotation, which if applied to
the output image data, will make the image match target rotation specified here.
While rotation can also be set via ImageCapture.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 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
ImageCapture.Builder.setTargetResolution(Size)
will be updated automatically to make
sure the suitable resolution can be selected when the use case is bound. Value set by
setCropAspectRatio(Rational)
will also be updated automatically to
make sure the output image is cropped into expected aspect ratio.
If no target rotation is set by the application, it is set 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.
takePicture uses the target rotation at the time it begins executing (which may be delayed waiting on a previous takePicture call to complete).
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 .
|
takePicture
public void takePicture (Executor executor, ImageCapture.OnImageCapturedCallback callback)
Captures a new still image for in memory access.
The callback will be called only once for every invocation of this method. The listener
is responsible for calling Image.close()
on the returned image.
Parameters | |
---|---|
executor |
Executor : The executor in which the callback methods will be run. |
callback |
ImageCapture.OnImageCapturedCallback : Callback to be invoked for the newly captured image
|
takePicture
public void takePicture (ImageCapture.OutputFileOptions outputFileOptions, Executor executor, ImageCapture.OnImageSavedCallback imageSavedCallback)
Captures a new still image and saves to a file along with application specified metadata.
The callback will be called only once for every invocation of this method.
If the ImageCapture
is in a UseCaseGroup
where ViewPort
is
set, or setCropAspectRatio(Rational)
is used, the image may be cropped before saving to
disk which causes an additional latency.
Parameters | |
---|---|
outputFileOptions |
ImageCapture.OutputFileOptions : Options to store the newly captured image. |
executor |
Executor : The executor in which the callback methods will be run. |
imageSavedCallback |
ImageCapture.OnImageSavedCallback : Callback to be called for the newly captured image. |
See also:
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.