Platform Android Studio Google Play Jetpack Kotlin Docs News
Overview Guides Reference Samples Design & Quality
Android Dev Summit, October 23-24: two days of technical content, directly from the Android team. Sign-up for livestream updates.

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

Summary

Nested classes

enum ImageCapture.CaptureMode

Capture mode options for ImageCapture. 

enum ImageCapture.ImageCaptureError

Describes the error that occurred during an image capture operation (such as ImageCapture.takePicture(Executor, OnImageCapturedListener)). 

class ImageCapture.Metadata

Holder class for metadata that will be saved with captured images. 

class ImageCapture.OnImageCapturedListener

Listener called when an image capture has completed. 

interface ImageCapture.OnImageSavedListener

Listener containing callbacks for image file I/O events. 

Public constructors

ImageCapture(ImageCaptureConfig userConfig)

Creates a new image capture use case from the given configuration.

Public methods

FlashMode getFlashMode()

Get the flash mode.

void setFlashMode(FlashMode 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.OnImageSavedListener imageSavedListener)

Captures a new still image and saves to a file.

void takePicture(Executor executor, ImageCapture.OnImageCapturedListener listener)

Captures a new still image for in memory access.

void takePicture(File saveLocation, ImageCapture.Metadata metadata, Executor executor, ImageCapture.OnImageSavedListener imageSavedListener)

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

String toString()

Protected methods

void onCameraControlReady(String cameraId)

Configures flash mode to CameraControlInternal once it is ready.

Inherited methods

Public constructors

ImageCapture

public ImageCapture (ImageCaptureConfig userConfig)

Creates a new image capture use case from the given configuration.

Parameters
userConfig ImageCaptureConfig: for this use case instance
Throws
IllegalArgumentException if the configuration is invalid.

Public methods

getFlashMode

public FlashMode getFlashMode ()

Get the flash mode.

Returns
FlashMode the FlashMode.

setFlashMode

public void setFlashMode (FlashMode flashMode)

Set the flash mode.

Parameters
flashMode FlashMode: the FlashMode.

setTargetAspectRatioCustom

public void setTargetAspectRatioCustom (Rational aspectRatio)

Sets target aspect ratio.

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

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

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 rotation value returned by ImageCapture.OnImageCapturedListener.

In most cases this should be set to the current rotation returned by Display.getRotation(). In that case, the output rotation from takePicture calls will be the rotation, which if applied to the output image, will make it match the display orientation.

While rotation can also be set via ImageCaptureConfig.Builder.setTargetRotation(int), using setTargetRotation(int) allows the target rotation to be set dynamically. This can be useful if an app locks itself to portrait, and uses the orientation sensor to set rotation to take landscape images when the device is rotated.

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.

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

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.
imageSavedListener ImageCapture.OnImageSavedListener: Listener to be called for the newly captured image.

takePicture

public void takePicture (Executor executor, 
                ImageCapture.OnImageCapturedListener listener)

Captures a new still image for in memory access.

The listener's 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 listener callback methods will be run.
listener ImageCapture.OnImageCapturedListener: Listener to be called for the newly captured image

takePicture

public void takePicture (File saveLocation, 
                ImageCapture.Metadata metadata, 
                Executor executor, 
                ImageCapture.OnImageSavedListener imageSavedListener)

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

The listener's 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 listener callback methods will be run.
imageSavedListener ImageCapture.OnImageSavedListener: Listener to be called for the newly captured image.

toString

public String toString ()

Returns
String

Protected methods

onCameraControlReady

protected void onCameraControlReady (String cameraId)

Configures flash mode to CameraControlInternal once it is ready.

Parameters
cameraId String