ImageCapture


public final class ImageCapture extends UseCase


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

public final class ImageCapture.Builder implements ExtendableBuilder

Builder for an ImageCapture.

public final class ImageCapture.Metadata

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.

public interface ImageCapture.ScreenFlash

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

static final int

Optimizes capture pipeline to prioritize image quality over latency.

static final int

Optimizes capture pipeline to prioritize latency over image quality.

static final int

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

static final int

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

static final int

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

static final int

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

static final int

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

static final int

An unknown error occurred.

static final int

Auto flash.

static final int

No flash.

static final int

Always flash.

static final int

Screen flash.

static final int

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

static final int

Captures Ultra HDR compressed images using the JPEG_R image format.

static final int

Captures raw images in the RAW_SENSOR image format.

static final int

Captures raw images in the RAW_SENSOR and JPEG image formats.

Public methods

int

Returns the set capture mode.

int

Get the flash mode.

static @NonNull 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.

@Nullable ResolutionSelector

Returns the ResolutionSelector used to select the postview size.

@NonNull ImageCaptureLatencyEstimate

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

@Nullable ResolutionInfo

Gets selected resolution information of the ImageCapture.

@Nullable ResolutionSelector

Returns the resolution selector setting.

@Nullable 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.

void

Sets target cropping aspect ratio for output image.

void
setFlashMode(int flashMode)

Set the flash mode.

void

Sets ScreenFlash for subsequent photo capture requests.

void
setTargetRotation(int rotation)

Sets the desired rotation of the output image.

void

Captures a new still image for in memory access.

void
takePicture(
    @NonNull ImageCapture.OutputFileOptions outputFileOptions,
    @NonNull Executor executor,
    @NonNull ImageCapture.OnImageSavedCallback imageSavedCallback
)

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

void
takePicture(
    @NonNull ImageCapture.OutputFileOptions rawOutputFileOptions,
    @NonNull ImageCapture.OutputFileOptions jpegOutputFileOptions,
    @NonNull Executor executor,
    @NonNull ImageCapture.OnImageSavedCallback imageSavedCallback
)

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

@NonNull String

Extension functions

final @NonNull ImageProxy
ImageCaptureExtKt.takePicture(
    @NonNull ImageCapture receiver,
    Function0<Unit> onCaptureStarted,
    Function1<@NonNull IntegerUnit> onCaptureProcessProgressed,
    Function1<@NonNull BitmapUnit> onPostviewBitmapAvailable
)

Captures a new still image for in memory access.

final @NonNull ImageCapture.OutputFileResults
ImageCaptureExtKt.takePicture(
    @NonNull ImageCapture receiver,
    @NonNull ImageCapture.OutputFileOptions outputFileOptions,
    Function0<Unit> onCaptureStarted,
    Function1<@NonNull IntegerUnit> onCaptureProcessProgressed,
    Function1<@NonNull BitmapUnit> onPostviewBitmapAvailable
)

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

Inherited methods

From androidx.camera.core.UseCase
static int
snapToSurfaceRotation(@IntRange(from = 0, to = 359) int orientation)

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
public static final int CAPTURE_MODE_MAXIMIZE_QUALITY = 0

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
public static final int CAPTURE_MODE_MINIMIZE_LATENCY = 1

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
public static final int CAPTURE_MODE_ZERO_SHUTTER_LAG = 2

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
public static final int ERROR_CAMERA_CLOSED = 3

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

ERROR_CAPTURE_FAILED

Added in 1.0.0
public static final int ERROR_CAPTURE_FAILED = 2

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

ERROR_FILE_IO

Added in 1.0.0
public static final int ERROR_FILE_IO = 1

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
public static final int ERROR_INVALID_CAMERA = 4

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

ERROR_UNKNOWN

Added in 1.0.0
public static final int ERROR_UNKNOWN = 0

An unknown error occurred.

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

FLASH_MODE_AUTO

Added in 1.0.0
public static final int FLASH_MODE_AUTO = 0

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
public static final int FLASH_MODE_OFF = 2

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

FLASH_MODE_ON

Added in 1.0.0
public static final int FLASH_MODE_ON = 1

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

FLASH_MODE_SCREEN

Added in 1.4.0
public static final int FLASH_MODE_SCREEN = 3

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
public static final int OUTPUT_FORMAT_JPEG = 0

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

OUTPUT_FORMAT_JPEG_ULTRA_HDR

Added in 1.4.0
public static final int OUTPUT_FORMAT_JPEG_ULTRA_HDR = 1

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
public static final int OUTPUT_FORMAT_RAW = 2

Captures raw images in the RAW_SENSOR image format.

OUTPUT_FORMAT_RAW_JPEG

Added in 1.5.0-beta02
public static final int OUTPUT_FORMAT_RAW_JPEG = 3

Captures raw images in the RAW_SENSOR and JPEG image formats.

Public methods

getCaptureMode

Added in 1.0.0
public int getCaptureMode()

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
public int getFlashMode()

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
public static @NonNull ImageCaptureCapabilities getImageCaptureCapabilities(@NonNull CameraInfo cameraInfo)

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();
}

getJpegQuality

Added in 1.1.0
public @IntRange(from = 1, to = 100) int getJpegQuality()

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
public int getOutputFormat()

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
public @Nullable ResolutionSelector getPostviewResolutionSelector()

Returns the ResolutionSelector used to select the postview size.

getRealtimeCaptureLatencyEstimate