ImageCapture

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

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. 

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

Auto flash.

int FLASH_MODE_OFF

No flash.

int FLASH_MODE_ON

Always flash.

Public methods

int getFlashMode()

Get the flash mode.

void setFlashMode(int flashMode)

Set the flash mode.

void setTargetAspectRatioCustom(Rational aspectRatio)

Sets target aspect ratio.

void setTargetRotation(int rotation)

Sets the desired rotation of the output image.

void takePicture(File saveLocation, Executor executor, ImageCapture.OnImageSavedCallback imageSavedCallback)

Captures a new still image and saves to a file.

void takePicture(File saveLocation, ImageCapture.Metadata metadata, Executor executor, ImageCapture.OnImageSavedCallback imageSavedCallback)

Captures a new still image and saves to a file along with application specified metadata.

void takePicture(Executor executor, ImageCapture.OnImageCapturedCallback callback)

Captures a new still image for in memory access.

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

Auto flash. The flash will be used according to the camera system's determination when taking a picture.

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

getFlashMode

public int getFlashMode ()

Get the flash mode.

Returns
int the flashMode.

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).

Parameters
flashMode int: the flash mode.

setTargetAspectRatioCustom

public void setTargetAspectRatioCustom (Rational aspectRatio)

Sets target aspect ratio.

This sets the cropping rectangle returned by ImageProxy.getCropRect() returned from takePicture(Executor, OnImageCapturedCallback).

This crops the saved image when calling takePicture(File, Executor, OnImageSavedCallback) or takePicture(File, Metadata, Executor, OnImageSavedCallback).

Cropping occurs around the center of the image and as though it were in the target rotation.

Parameters
aspectRatio Rational: New target aspect ratio.

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, i.e. one of Surface.ROTATION_0, Surface.ROTATION_90, Surface.ROTATION_180, or Surface.ROTATION_270.

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.

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 (File saveLocation, 
                Executor executor, 
                ImageCapture.OnImageSavedCallback imageSavedCallback)

Captures a new still image and saves to a file.

The listener's callback will be called only once for every invocation of this method.

Parameters
saveLocation File: Location to store the newly captured image.
executor Executor: The executor in which the listener callback methods will be run.
imageSavedCallback ImageCapture.OnImageSavedCallback: Callback to be called for the newly captured image.

takePicture

public void takePicture (File saveLocation, 
                ImageCapture.Metadata metadata, 
                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.

This function accepts metadata as a parameter from application code. For JPEGs, this metadata will be included in the EXIF.

Parameters
saveLocation File: Location to store the newly captured image.
metadata ImageCapture.Metadata: Metadata to be stored with the saved image. For JPEG this will be included in the EXIF.
executor Executor: The executor in which the callback methods will be run.
imageSavedCallback ImageCapture.OnImageSavedCallback: Callback to be called for the newly captured image.

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

toString

public String toString ()

Returns
String