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.OnImageCapturedCallback
.
Summary
Nested classes | |
---|---|
class |
ImageCapture.Builder
Builder for an |
@interface |
ImageCapture.CaptureMode
Capture mode options for ImageCapture. |
@interface |
ImageCapture.ImageCaptureError
Describes the error that occurred during an image capture operation (such as |
class |
ImageCapture.Metadata
Holder class for metadata that will be saved with captured images. |
class |
ImageCapture.OnImageCapturedCallback
Callback for when an image capture has completed. |
interface |
ImageCapture.OnImageSavedCallback
Listener containing callbacks for image file I/O events. |
Public methods | |
---|---|
int
|
getFlashMode()
Get the flash mode. |
void
|
setFlashMode(int 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.OnImageSavedCallback imageSavedCallback)
Captures a new still image and saves to a file. |
void
|
takePicture(File saveLocation, ImageCapture.Metadata metadata, Executor executor, ImageCapture.OnImageSavedCallback imageSavedCallback)
Captures a new still image and saves to a file along with application specified metadata. |
void
|
takePicture(Executor executor, ImageCapture.OnImageCapturedCallback callback)
Captures a new still image for in memory access. |
String
|
toString()
|
Inherited methods | |
---|---|
Public methods
setFlashMode
public void setFlashMode (int flashMode)
Set the flash mode.
The flash control for the subsequent photo capture requests. See
FlashMode
for the optional settings. Applications can check if there is a flash unit
via CameraInfo.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 FlashMode.OFF
.
When the torch is enabled via CameraControl.enableTorch(boolean)
, 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)
.
Parameters | |
---|---|
flashMode |
int : 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, OnImageCapturedCallback)
.
This crops the saved image when calling
takePicture(File, Executor, OnImageSavedCallback)
or
takePicture(File, Metadata, Executor, OnImageSavedCallback)
.
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.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 ImageCapture.Builder.setTargetRotation(int)
, using
setTargetRotation(int)
allows the target rotation to be set dynamically.
In general, it is best to use an 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 setTargetRotation(int)
to set target rotation dynamically according to
the OrientationEventListener
, without re-creating the use case. Note
the OrientationEventListener output of degrees in the range [0..359] should be converted to
a surface rotation, i.e. one of Surface.ROTATION_0
, Surface.ROTATION_90
,
Surface.ROTATION_180
, or Surface.ROTATION_270
.
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.
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
Surface.ROTATION_0 , Surface.ROTATION_90 ,
Surface.ROTATION_180 , or Surface.ROTATION_270 .
|
takePicture
public void takePicture (File saveLocation, Executor executor, ImageCapture.OnImageSavedCallback imageSavedCallback)
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. |
imageSavedCallback |
ImageCapture.OnImageSavedCallback : Callback to be called for the newly captured image.
|
takePicture
public void takePicture (File saveLocation, ImageCapture.Metadata metadata, Executor executor, 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.
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 callback methods will be run. |
imageSavedCallback |
ImageCapture.OnImageSavedCallback : Callback to be called for the newly captured image.
|
takePicture
public void takePicture (Executor executor, 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 Image.close()
on the returned image.
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
|
toString
public String toString ()
Returns | |
---|---|
String |
Content and code samples on this page are subject to the licenses described in the Content License. Java is a registered trademark of Oracle and/or its affiliates.