ImageCapture

CAPTURE_MODE_MAXIMIZE_QUALITY

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

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

@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

public static final int ERROR_CAMERA_CLOSED = 3

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

ERROR_CAPTURE_FAILED

public static final int ERROR_CAPTURE_FAILED = 2

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

ERROR_FILE_IO

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

public static final int ERROR_INVALID_CAMERA = 4

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

ERROR_UNKNOWN

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

public static final int FLASH_MODE_AUTO = 0

FLASH_MODE_OFF

public static final int FLASH_MODE_OFF = 2

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

FLASH_MODE_ON

public static final int FLASH_MODE_ON = 1

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

getCaptureMode

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

public int getFlashMode()

Get the flash mode.

getJpegQuality

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.

getResolutionInfo

public @Nullable ResolutionInfo getResolutionInfo()

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.

getTargetRotation

public int getTargetRotation()

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 or setTargetRotationDegrees. 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.

setCropAspectRatio

public void setCropAspectRatio(@NonNull Rational aspectRatio)

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.

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

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 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, use setTargetRotationDegrees to set target rotation dynamically according to the android.view.OrientationEventListener, without re-creating the use case. See setTargetRotationDegrees for more information.

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

setTargetRotationDegrees

public void setTargetRotationDegrees(int degrees)

Sets the desired rotation of the output image in degrees.

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, use setTargetRotationDegrees() to set target rotation dynamically according to the android.view.OrientationEventListener, without re-creating the use case. The sample code is as below:

public class CameraXActivity extends AppCompatActivity {

    private OrientationEventListener mOrientationEventListener;

    
    protected void onStart() {
        super.onStart();
        if (mOrientationEventListener == null) {
            mOrientationEventListener = new OrientationEventListener(this) {
                
                public void onOrientationChanged(int orientation) {
                    if (orientation == OrientationEventListener.ORIENTATION_UNKNOWN) {
                        return;
                    }
                    mImageCapture.setTargetRotationDegrees(orientation);
                }
            };
        }
        mOrientationEventListener.enable();
    }

    
    protected void onStop() {
        super.onStop();
        mOrientationEventListener.disable();
    }
}

setTargetRotationDegrees() cannot rotate the camera image to an arbitrary angle, instead it maps the angle to one of ROTATION_0, ROTATION_90, ROTATION_180 and ROTATION_270 as the input of setTargetRotation. The rule is as follows:

If the input degrees is not in the range [0..359], it will be converted to the equivalent degrees in the range [0..359]. And then take the following mapping based on the input degrees.

degrees >= 315 || degrees <45 ->ROTATION_0

degrees >= 225 &°rees; <315 ->ROTATION_90

degrees >= 135 &°rees; <225 ->ROTATION_180

degrees >= 45 &°rees; <135 ->ROTATION_270

The rotation value can be obtained by getTargetRotation. This means the rotation previously set by setTargetRotation will be overridden by setTargetRotationDegrees(int), and vice versa.

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.

takePicture uses the target rotation at the time it begins executing (which may be delayed waiting on a previous takePicture call to complete).

takePicture

public void takePicture(
    @NonNull Executor executor,
    @NonNull 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 close on the returned image.

takePicture

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

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

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.

toString

public @NonNull String toString()