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

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

Summary

Nested classes

Capture mode options for ImageCapture.

Describes the error that occurred during an image capture operation (such as ).

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

Listener called when an image capture has completed.
abstract

Listener containing callbacks for image file I/O events.

Public constructors
<init>(@NonNull userConfig: ImageCaptureConfig)

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

Public methods
open FlashMode!

Get the flash mode.
open Unit
setFlashMode(flashMode: FlashMode!)

Set the flash mode.
open Unit

Sets target aspect ratio.
open Unit

Sets the desired rotation of the output image.
open Unit
takePicture(@NonNull executor: Executor, @NonNull listener: ImageCapture.OnImageCapturedListener)

Captures a new still image for in memory access.
open Unit
takePicture(@NonNull saveLocation: File, @NonNull executor: Executor, @NonNull imageSavedListener: ImageCapture.OnImageSavedListener)

Captures a new still image and saves to a file.
open Unit
takePicture(@NonNull saveLocation: File, @NonNull metadata: ImageCapture.Metadata, @NonNull executor: Executor, @NonNull imageSavedListener: ImageCapture.OnImageSavedListener)

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

Protected methods
open Unit

Configures flash mode to CameraControlInternal once it is ready.

Inherited functions

Public constructors

<init>

ImageCapture(@NonNull userConfig: ImageCaptureConfig)

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

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

Public methods

getFlashMode

open fun getFlashMode(): FlashMode!

Get the flash mode.

Return
FlashMode!: the FlashMode.

setFlashMode

open fun setFlashMode(flashMode: FlashMode!): Unit

Set the flash mode.

Parameters
flashMode FlashMode!: the FlashMode.

setTargetAspectRatioCustom

open fun setTargetAspectRatioCustom(aspectRatio: Rational!): Unit

Sets target aspect ratio.

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

This crops the saved image when calling ImageCapture#takePicture(File, Executor, OnImageSavedListener) or ImageCapture#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

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

In most cases this should be set to the current rotation returned by . 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 ImageCapture#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

open fun takePicture(@NonNull executor: Executor, @NonNull listener: ImageCapture.OnImageCapturedListener): Unit

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 Executor: Listener to be called for the newly captured image

takePicture

open fun takePicture(@NonNull saveLocation: File, @NonNull executor: Executor, @NonNull imageSavedListener: ImageCapture.OnImageSavedListener): Unit

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 File: The executor in which the listener callback methods will be run.
imageSavedListener File: Listener to be called for the newly captured image.

takePicture

open fun takePicture(@NonNull saveLocation: File, @NonNull metadata: ImageCapture.Metadata, @NonNull executor: Executor, @NonNull imageSavedListener: ImageCapture.OnImageSavedListener): Unit

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 File: Metadata to be stored with the saved image. For JPEG this will be included in the EXIF.
executor File: The executor in which the listener callback methods will be run.
imageSavedListener File: Listener to be called for the newly captured image.

toString

@NonNull open fun toString(): String

Protected methods

onCameraControlReady

protected open fun onCameraControlReady(cameraId: String!): Unit

Configures flash mode to CameraControlInternal once it is ready.