ImageCapture

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 types

Builder for an ImageCapture.

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

Callback for image capture events.

Listener containing callbacks for image file I/O events.

Options for saving newly captured image.

Builder class for OutputFileOptions.

Info about the saved image file.

Interface to do the application changes required for screen flash operations.

Callback listener for discovering when the application has completed its changes for a screen flash image capture.

Constants
const Int

Optimizes capture pipeline to prioritize image quality over latency.
const Int

Optimizes capture pipeline to prioritize latency over image quality.
const Int

Optimizes capture pipeline to have better latency while keeping good image quality.
const Int

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

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

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

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

An unknown error occurred.
const Int

Auto flash.
const Int

No flash.
const Int

Always flash.
const Int

Screen flash.
const Int

Captures 8-bit standard dynamic range (SDR) images using the JPEG image format.
const Int

Captures Ultra HDR compressed images using the JPEG_R image format.
const Int

Captures raw images in the RAW_SENSOR image format.
const Int

Captures raw images in the RAW_SENSOR and JPEG image formats.

Public functions
Int

Returns the set capture mode.
Int

Get the flash mode.
java-static ImageCaptureCapabilities

Returns ImageCaptureCapabilities to query ImageCapture capability of the given CameraInfo.
@IntRange(from = 1, to = 100) Int

Returns the JPEG quality setting.
Int

Returns the output format setting.
ResolutionSelector?

Returns the ResolutionSelector used to select the postview size.
ImageCaptureLatencyEstimate

Returns an estimate of the capture and processing sequence duration based on the current camera configuration and scene conditions.
ResolutionInfo?

Gets selected resolution information of the ImageCapture.
ResolutionSelector?

Returns the resolution selector setting.
ImageCapture.ScreenFlash?

Returns the ScreenFlash instance currently set, null if none.
Int

Returns the desired rotation of the output image.
Boolean

Returns if postview is enabled or not.
Unit

Sets target cropping aspect ratio for output image.
Unit
setFlashMode(flashMode: Int)

Set the flash mode.
Unit

Sets ScreenFlash for subsequent photo capture requests.
Unit

Sets the desired rotation of the output image.
Unit
takePicture(
    executor: Executor,
    callback: ImageCapture.OnImageCapturedCallback
)

Captures a new still image for in memory access.
Unit
takePicture(
    outputFileOptions: ImageCapture.OutputFileOptions,
    executor: Executor,
    imageSavedCallback: ImageCapture.OnImageSavedCallback
)

Captures a new still image and saves to a file along with application specified metadata.
Unit
takePicture(
    rawOutputFileOptions: ImageCapture.OutputFileOptions,
    jpegOutputFileOptions: ImageCapture.OutputFileOptions,
    executor: Executor,
    imageSavedCallback: ImageCapture.OnImageSavedCallback
)

Captures two still images simultaneously and saves to a file along with application specified metadata.
String

Extension functions
suspend ImageProxy
ImageCapture.takePicture(
    onCaptureStarted: (() -> Unit)?,
    onCaptureProcessProgressed: ((Int) -> Unit)?,
    onPostviewBitmapAvailable: ((Bitmap) -> Unit)?
)

Captures a new still image for in memory access.
suspend ImageCapture.OutputFileResults
ImageCapture.takePicture(
    outputFileOptions: ImageCapture.OutputFileOptions,
    onCaptureStarted: (() -> Unit)?,
    onCaptureProcessProgressed: ((Int) -> Unit)?,
    onPostviewBitmapAvailable: ((Bitmap) -> Unit)?
)

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

Inherited functions
From androidx.camera.core.UseCase
java-static Int
snapToSurfaceRotation(orientation: @IntRange(from = 0, to = 359) Int)

A utility function that can convert the orientation degrees of OrientationEventListener to the nearest Surface rotation.

Constants

CAPTURE_MODE_MAXIMIZE_QUALITY

Added in 1.0.0
const val CAPTURE_MODE_MAXIMIZE_QUALITY = 0: 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.

CAPTURE_MODE_MINIMIZE_LATENCY

Added in 1.0.0
const val CAPTURE_MODE_MINIMIZE_LATENCY = 1: 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.

CAPTURE_MODE_ZERO_SHUTTER_LAG

Added in 1.2.0
@ExperimentalZeroShutterLag
const val CAPTURE_MODE_ZERO_SHUTTER_LAG = 2: Int

Optimizes capture pipeline to have better latency while keeping good image quality. When the capture mode is set to ZERO_SHUTTER_LAG, the latency between the shutter button is clicked and the picture is taken is expected to be minimized, compared with other capture modes.

ZERO_SHUTTER_LAG mode is aiming to provide the minimum latency for instant capture. It caches intermediate results and deliver the one with the closest timestamp when takePicture is invoked.

isZslSupported can be used to query the device capability to support this mode or not. However, this mode also depends on use cases configuration and flash mode settings. If VideoCapture is bound or flash mode is not OFF or OEM Extension is ON, this mode will be disabled automatically.

ERROR_CAMERA_CLOSED

Added in 1.0.0
const val ERROR_CAMERA_CLOSED = 3: Int

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

ERROR_CAPTURE_FAILED

Added in 1.0.0
const val ERROR_CAPTURE_FAILED = 2: Int

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

ERROR_FILE_IO

Added in 1.0.0
const val ERROR_FILE_IO = 1: Int

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

ERROR_INVALID_CAMERA

Added in 1.0.0
const val ERROR_INVALID_CAMERA = 4: Int

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

ERROR_UNKNOWN

Added in 1.0.0
const val ERROR_UNKNOWN = 0: Int

An unknown error occurred.

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

FLASH_MODE_AUTO

Added in 1.0.0
const val FLASH_MODE_AUTO = 0: Int

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

FLASH_MODE_OFF

Added in 1.0.0
const val FLASH_MODE_OFF = 2: Int

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

FLASH_MODE_ON

Added in 1.0.0
const val FLASH_MODE_ON = 1: Int

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

FLASH_MODE_SCREEN

Added in 1.4.0
const val FLASH_MODE_SCREEN = 3: Int

Screen flash. Display screen brightness will be used as alternative to flash when taking a picture with front camera.

This flash mode can be set via setFlashMode after setting a non-null ScreenFlash instance with setScreenFlash. This mode will always invoke all the necessary operations for a screen flash image capture, i.e. it is similar to FLASH_MODE_ON, not FLASH_MODE_AUTO.

The following code snippet shows an example implementation of how this flash mode can be set to an ImageCapture instance. 

imageCapture.setScreenFlash(new ImageCapture.ScreenFlash() {
    
    public void apply(long expirationTimeMillis,
            ScreenFlashListener screenFlashListener) {
        whiteColorOverlayView.setVisibility(View.VISIBLE);
        maximizeScreenBrightness();
        screenFlashListener.onCompleted();
    }

    
    public void clear() {
        restoreScreenBrightness();
        whiteColorOverlayView.setVisibility(View.INVISIBLE);
    }
});

imageCapture.setFlashMode(ImageCapture.FLASH_MODE_SCREEN);
See also
setFlashMode

OUTPUT_FORMAT_JPEG

Added in 1.4.0
const val OUTPUT_FORMAT_JPEG = 0: Int

Captures 8-bit standard dynamic range (SDR) images using the JPEG image format.

OUTPUT_FORMAT_JPEG_ULTRA_HDR

Added in 1.4.0
const val OUTPUT_FORMAT_JPEG_ULTRA_HDR = 1: Int

Captures Ultra HDR compressed images using the JPEG_R image format.

This format is backward compatible with SDR JPEG images and supports HDR rendering of content. This means that on older apps or devices, images appear seamlessly as regular JPEG; on apps and devices that have been updated to fully support the format, images appear as HDR.

For more information see Support Ultra HDR.

OUTPUT_FORMAT_RAW

Added in 1.5.0-beta02
const val OUTPUT_FORMAT_RAW = 2: Int

Captures raw images in the RAW_SENSOR image format.

OUTPUT_FORMAT_RAW_JPEG

Added in 1.5.0-beta02
const val OUTPUT_FORMAT_RAW_JPEG = 3: Int

Captures raw images in the RAW_SENSOR and JPEG image formats.

Public functions

getCaptureMode

Added in 1.0.0
fun getCaptureMode(): Int

Returns the set capture mode.

This is set when constructing an ImageCapture using setCaptureMode. This is static for an instance of ImageCapture.

getFlashMode

Added in 1.0.0
fun getFlashMode(): Int

Get the flash mode.

Returns
Int

the flashMode. Value is FLASH_MODE_AUTO, FLASH_MODE_ON, FLASH_MODE_SCREEN, or FLASH_MODE_OFF.

getImageCaptureCapabilities

Added in 1.4.0
java-static fun getImageCaptureCapabilities(cameraInfo: CameraInfo): ImageCaptureCapabilities

Returns ImageCaptureCapabilities to query ImageCapture capability of the given CameraInfo.

Some capabilities are only exposed on Extensions-enabled cameras. To get the correct capabilities when Extensions are enabled, you need to pass the CameraInfo from the Extensions-enabled Camera instance. To do this, use the CameraSelector instance retrieved from getExtensionEnabledCameraSelector to invoke bindToLifecycle where you can skip use cases arguments if you'd like to query it before opening the camera. Then, use the returned Camera to get the CameraInfo instance.

>The following code snippet demonstrates how to enable postview: 

          
CameraSelector extensionCameraSelector =
    extensionsManager.getExtensionEnabledCameraSelector(cameraSelector, ExtensionMode.NIGHT);
Camera camera = cameraProvider.bindToLifecycle(activity, extensionCameraSelector);
ImageCaptureCapabilities capabilities =
    ImageCapture.getImageCaptureCapabilities(camera.getCameraInfo());
ImageCapture imageCapture = new ImageCapture.Builder()
    .setPostviewEnabled(capabilities.isPostviewSupported())
    .build();

}
Returns
ImageCaptureCapabilities

ImageCaptureCapabilities

getJpegQuality

Added in 1.1.0
fun getJpegQuality(): @IntRange(from = 1, to = 100) Int

Returns the JPEG quality setting.

This is set when constructing an ImageCapture using setJpegQuality. If not set, a default value will be set according to the capture mode setting. JPEG compression quality 95 is set for CAPTURE_MODE_MINIMIZE_LATENCY and 100 is set for CAPTURE_MODE_MAXIMIZE_QUALITY. This is static for an instance of ImageCapture.

getOutputFormat

Added in 1.4.0
fun getOutputFormat(): Int

Returns the output format setting.

If the output format was not provided to setOutputFormat, this will return the default of OUTPUT_FORMAT_JPEG.

Returns
Int

the output format set for this ImageCapture use case.
See also
setOutputFormat

getPostviewResolutionSelector

Added in 1.4.0
fun getPostviewResolutionSelector(): ResolutionSelector?

Returns the ResolutionSelector used to select the postview size.

See also
setPostviewResolutionSelector

getRealtimeCaptureLatencyEstimate

Added in 1.4.0
fun getRealtimeCaptureLatencyEstimate(): ImageCaptureLatencyEstimate

Returns an estimate of the capture and processing sequence duration based on the current camera configuration and scene conditions. The value will vary as the scene and/or camera configuration change.

The processing estimate can vary based on device processing load.

If this method returns UNDEFINED_IMAGE_CAPTURE_LATENCY, it means that the camera HAL doesn't provide latency information. In this case, this method will consistently return UNDEFINED_IMAGE_CAPTURE_LATENCY for the current camera configuration, as long as the UseCase and camera configuration remain unchanged (e.g., extensions mode and camera settings are kept the same).

getResolutionInfo

Added in 1.1.0
fun getResolutionInfo(): ResolutionInfo?

Gets selected resolution information of the ImageCapture.

The returned ResolutionInfo will be expressed in the coordinates of the camera sensor. Note that the resolution might not be the same as the resolution of the received image by calling takePicture because the received image might have been rotated to the upright orientation using the target rotation setting by the device.

The resolution information might change if the use case is unbound and then rebound, setTargetRotation is called to change the target rotation setting, or setCropAspectRatio is called to change the crop aspect ratio setting. The application needs to call getResolutionInfo() again to get the latest ResolutionInfo for the changes.

Returns
ResolutionInfo?

the resolution information if the use case has been bound by the bindToLifecycle API, or null if the use case is not bound yet.

getResolutionSelector

Added in 1.3.0
fun getResolutionSelector(): ResolutionSelector?

Returns the resolution selector setting.

This setting is set when constructing an ImageCapture using setResolutionSelector.

getScreenFlash

Added in 1.4.0
fun getScreenFlash(): ImageCapture.ScreenFlash?

Returns the ScreenFlash instance currently set, null if none.

getTargetRotation

Added in 1.0.0
fun getTargetRotation(): Int

Returns the desired rotation of the output image.

The rotation can be set prior to constructing an ImageCapture using setTargetRotation or dynamically by calling setTargetRotation. 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.

If no target rotation is set by the application, it is set to the value of 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.

isPostviewEnabled

Added in 1.4.0
fun isPostviewEnabled(): Boolean

Returns if postview is enabled or not.

See also
setPostviewEnabled

setCropAspectRatio

Added in 1.0.0
fun setCropAspectRatio(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 getCropRect returned from takePicture.

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 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. 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 is called.

Parameters
aspectRatio: Rational

New target aspect ratio.

setFlashMode

Added in 1.0.0
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 hasFlashUnit and update UI component if necessary. If there is no flash unit and flashMode is not FLASH_MODE_SCREEN, 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 enableTorch, 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.

If FLASH_MODE_SCREEN is set, a ScreenFlash implementation must be set via setScreenFlash before calling this API. Trying to use FLASH_MODE_SCREEN without a ScreenFlash instance set or with a non-front camera will result in an IllegalArgumentException. It is the application's responsibility to change flashMode while switching the camera in case it leads to a non-supported case (e.g. switching to rear camera while FLASH_MODE_SCREEN is still on).

Parameters
flashMode: Int

the flash mode. Value is FLASH_MODE_AUTO, FLASH_MODE_ON, FLASH_MODE_SCREEN or FLASH_MODE_OFF.
Throws
java.lang.IllegalArgumentException

If flash mode is invalid or FLASH_MODE_SCREEN is used without a ScreenFlash instance or front camera.

setScreenFlash

Added in 1.4.0
fun setScreenFlash(screenFlash: ImageCapture.ScreenFlash?): Unit

Sets ScreenFlash for subsequent photo capture requests.

The calling of this API will take effect for FLASH_MODE_SCREEN only and the screenFlash instance will be ignored for other flash modes.

If the implementation provided by the user is no longer valid (e.g. due to any android.app.Activity or android.view.View reference used in the implementation becoming invalid), user needs to re-set a new valid ScreenFlash or clear the previous one with setScreenFlash(null), whichever appropriate.

Parameters
screenFlash: ImageCapture.ScreenFlash?

A ScreenFlash implementation that is used to notify API users when app side changes need to be done. This will replace the previous ScreenFlash instance set with this method.

setTargetRotation

Added in 1.0.0
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 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 setTargetRotation, using 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, set target rotation dynamically according to the android.view.OrientationEventListener, without re-creating the use case. snapToSurfaceRotation is a helper function to convert the orientation of the android.view.OrientationEventListener to a rotation value. See snapToSurfaceRotation for more information and sample code.

When this function is called, value set by setTargetResolution will be updated automatically to make sure the suitable resolution can be selected when the use case is bound. Value set by setCropAspectRatio 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 getRotation of the default display at the time the use case is bound. To return to the default value, set the value to 

context.getSystemService(WindowManager.class).getDefaultDisplay().getRotation();

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 ROTATION_0, ROTATION_90, ROTATION_180, or ROTATION_270.

takePicture

Added in 1.0.0
fun takePicture(
    executor: Executor,
    callback: ImageCapture.OnImageCapturedCallback
): Unit

Captures a new still image for in memory access.

The listener is responsible for calling close on the returned image.

For simultaneous image capture with OUTPUT_FORMAT_RAW_JPEG, the onCaptureSuccess will be triggered twice, one for RAW_SENSOR and the other for JPEG. The order of the callbacks for which image format is triggered first is not guaranteed.

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.
Throws
java.lang.IllegalArgumentException

If FLASH_MODE_SCREEN is used without a non-null ScreenFlash instance set.

takePicture

Added in 1.0.0
fun takePicture(
    outputFileOptions: ImageCapture.OutputFileOptions,
    executor: Executor,
    imageSavedCallback: ImageCapture.OnImageSavedCallback
): Unit

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

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.

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.
Throws
java.lang.IllegalArgumentException

If FLASH_MODE_SCREEN is used without a a non-null ScreenFlash instance set. Also if OUTPUT_FORMAT_RAW_JPEG is used.
See also
ViewPort

takePicture

Added in 1.5.0-beta02
fun takePicture(
    rawOutputFileOptions: ImageCapture.OutputFileOptions,
    jpegOutputFileOptions: ImageCapture.OutputFileOptions,
    executor: Executor,
    imageSavedCallback: ImageCapture.OnImageSavedCallback
): Unit

Captures two still images simultaneously and saves to a file along with application specified metadata.

Currently only OUTPUT_FORMAT_RAW_JPEG is supporting simultaneous image capture. It needs two OutputFileOptions, the first one is used for RAW_SENSOR image and the second one is for JPEG. The order of the callbacks for which image format is triggered first is not guaranteed. Check with getImageFormat in onImageSaved for the image format.

Parameters
rawOutputFileOptions: ImageCapture.OutputFileOptions

Options to store the newly captured raw image.
jpegOutputFileOptions: ImageCapture.OutputFileOptions

Options to store the newly captured jpeg 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.
Throws
java.lang.IllegalArgumentException

If FLASH_MODE_SCREEN is used without a a non-null ScreenFlash instance set. Also if non-OUTPUT_FORMAT_RAW_JPEG format is used.

toString

fun toString(): String

Extension functions

takePicture

suspend fun ImageCapture.takePicture(
    onCaptureStarted: (() -> Unit)? = null,
    onCaptureProcessProgressed: ((Int) -> Unit)? = null,
    onPostviewBitmapAvailable: ((Bitmap) -> Unit)? = null
): ImageProxy

Captures a new still image for in memory access.

The caller is responsible for calling ImageProxy.close on the returned image.

Parameters
onCaptureStarted: (() -> Unit)? = null

Callback for when the camera has started exposing the frame.
onCaptureProcessProgressed: ((Int) -> Unit)? = null

Callback to report the progress of the capture's processing.
onPostviewBitmapAvailable: ((Bitmap) -> Unit)? = null

Callback to notify that the postview bitmap is available.
See also
takePicture
ImageCapture.OnImageCapturedCallback

takePicture

suspend fun ImageCapture.takePicture(
    outputFileOptions: ImageCapture.OutputFileOptions,
    onCaptureStarted: (() -> Unit)? = null,
    onCaptureProcessProgressed: ((Int) -> Unit)? = null,
    onPostviewBitmapAvailable: ((Bitmap) -> Unit)? = null
): ImageCapture.OutputFileResults

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

Parameters
outputFileOptions: ImageCapture.OutputFileOptions

Options to store the output image file.
onCaptureStarted: (() -> Unit)? = null

Callback for when the camera has started exposing the frame.
onCaptureProcessProgressed: ((Int) -> Unit)? = null

Callback to report the progress of the capture's processing.
onPostviewBitmapAvailable: ((Bitmap) -> Unit)? = null

Callback to notify that the postview bitmap is available.
See also
takePicture
ImageCapture.OnImageSavedCallback