ImageCapture

Kotlin |Java

class ImageCapture : UseCase

kotlin.Any
↳	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
	Builder Builder for an ImageCapture.
	Metadata Holder class for metadata that will be saved with captured images.
abstract	OnImageCapturedCallback Callback for when an image capture has completed.
abstract	OnImageSavedCallback Listener containing callbacks for image file I/O events.
	OutputFileOptions Options for saving newly captured image.
	OutputFileResults Info about the saved image file.

Constants
static Int	CAPTURE_MODE_MAXIMIZE_QUALITY Optimizes capture pipeline to prioritize image quality over latency.
static Int	CAPTURE_MODE_MINIMIZE_LATENCY Optimizes capture pipeline to prioritize latency over image quality.
static Int	ERROR_CAMERA_CLOSED An error indicating the request cannot be done due to camera is closed.
static Int	ERROR_CAPTURE_FAILED An error reported by camera framework indicating the capture request is failed.
static Int	ERROR_FILE_IO An error occurred while attempting to read or write a file, such as when saving an image to a File.
static Int	ERROR_INVALID_CAMERA An error indicating this ImageCapture is not bound to a valid camera.
static Int	ERROR_UNKNOWN An unknown error occurred.
static Int	FLASH_MODE_AUTO
static Int	FLASH_MODE_OFF No flash.
static 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.
Unit	setCropAspectRatio(@NonNull aspectRatio: Rational) Sets target cropping aspect ratio for output image.
Unit	setFlashMode(flashMode: Int) Set the flash mode.
Unit	setTargetRotation(rotation: Int) Sets the desired rotation of the output image.
Unit	takePicture(@NonNull executor: Executor, @NonNull callback: ImageCapture.OnImageCapturedCallback) Captures a new still image for in memory access.
Unit	takePicture(@NonNull outputFileOptions: ImageCapture.OutputFileOptions, @NonNull executor: Executor, @NonNull imageSavedCallback: ImageCapture.OnImageSavedCallback) Captures a new still image and saves to a file along with application specified metadata.
String	toString()

Constants

CAPTURE_MODE_MAXIMIZE_QUALITY

static val CAPTURE_MODE_MAXIMIZE_QUALITY: Int

Optimizes capture pipeline to prioritize image quality over latency. When the capture mode is set to MAX_QUALITY, images may take longer to capture.

Value: 0

CAPTURE_MODE_MINIMIZE_LATENCY

static val CAPTURE_MODE_MINIMIZE_LATENCY: Int

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.

Value: 1

ERROR_CAMERA_CLOSED

static val ERROR_CAMERA_CLOSED: Int

An error indicating the request cannot be done due to camera is closed.

Value: 3

ERROR_CAPTURE_FAILED

static val ERROR_CAPTURE_FAILED: Int

An error reported by camera framework indicating the capture request is failed.

Value: 2

ERROR_FILE_IO

static val ERROR_FILE_IO: Int

An error occurred while attempting to read or write a file, such as when saving an image to a File.

Value: 1

ERROR_INVALID_CAMERA

static val ERROR_INVALID_CAMERA: Int

An error indicating this ImageCapture is not bound to a valid camera.

Value: 4

ERROR_UNKNOWN

static val ERROR_UNKNOWN: Int

An unknown error occurred.

See message parameter in onError callback or log for more details.

Value: 0

FLASH_MODE_AUTO

static val FLASH_MODE_AUTO: Int

Value: 0

FLASH_MODE_OFF

static val FLASH_MODE_OFF: Int

No flash. The flash will never be used when taking a picture.

Value: 2

FLASH_MODE_ON

static val FLASH_MODE_ON: Int

Always flash. The flash will always be used when taking a picture.

Value: 1

Public methods

getCaptureMode

fun getCaptureMode(): Int

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.

getFlashMode

fun getFlashMode(): Int

Get the flash mode.

Return
Int	the flashMode. Value is FLASH_MODE_AUTO, FLASH_MODE_ON, or FLASH_MODE_OFF.

getTargetRotation

fun getTargetRotation(): Int

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 ImageCapture#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.

Return
Int	The rotation of the intended target.

setCropAspectRatio

fun setCropAspectRatio(@NonNull aspectRatio: Rational): Unit

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 ImageCapture#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 ImageCapture#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 ImageCapture#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 ImageCapture#setTargetRotation(int) is called.

Parameters
aspectRatio	Rational: New target aspect ratio.

setFlashMode

fun setFlashMode(flashMode: Int): Unit

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

fun setTargetRotation(rotation: Int): Unit

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 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 Builder#setTargetRotation(int), using ImageCapture#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 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 ImageCapture#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 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 ImageCapture#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

fun takePicture(
    @NonNull executor: Executor, 
    @NonNull callback: ImageCapture.OnImageCapturedCallback
): Unit

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

fun takePicture(
    @NonNull outputFileOptions: ImageCapture.OutputFileOptions, 
    @NonNull executor: Executor, 
    @NonNull imageSavedCallback: ImageCapture.OnImageSavedCallback
): Unit

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 is used, the image may be cropped before saving to disk which causes an additional latency.

Before triggering the image capture pipeline, if the save location is a File or MediaStore, it is first verified to ensure it's valid and writable. A File is verified by attempting to open a java.io.FileOutputStream to it, whereas a location in MediaStore is validated by creating a new row in the user defined table, retrieving a Uri pointing to it, then attempting to open an OutputStream to it. The newly created row is deleted at the end of the verification. On Huawei devices, this deletion results in the system displaying a notification informing the user that a photo has been deleted. In order to avoid this, validating the image capture save location in android.provider.MediaStore is skipped on Huawei devices.

If the validation of the save location fails, OnImageSavedCallback's error callback is invoked with an ImageCaptureException.

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

• ViewPort

toString

@NonNull fun toString(): String