Skip to content
com.iristick.smartglass.core.camera

Class CaptureResult


public abstract class CaptureResult
extends Object

The results of a single image capture from the image sensor.

CaptureResults are produced by a CaptureSession after processing a CaptureRequest. CaptureResult objects are immutable.

Nested Class Summary

Modifier and Type Class and Description
static class  CaptureResult.Key<T>
This class allows to define type-safe keys to designate capture result fields.

Field Summary

Modifier and Type Field and Description
static CaptureResult.Key<Float> COLOR_CORRECTION_GAIN_BLUE
Gain applied to the blue Bayer raw color channel for white-balance relative to the green channel.
static CaptureResult.Key<Float> COLOR_CORRECTION_GAIN_RED
Gain applied to the red Bayer raw color channel for white-balance relative to the green channel.
static CaptureResult.Key<Integer> CONTROL_AF_STATE
Current state of auto-focus (AF) algorithm.
static int CONTROL_AF_STATE_ACTIVE_SCAN
AF is performing an AF scan because it was triggered by AF trigger.
static int CONTROL_AF_STATE_FOCUSED_LOCKED
AF believes it is focused correctly and has locked focus.
static int CONTROL_AF_STATE_INACTIVE
AF is off or has not yet tried to scan/been asked to scan.
static int CONTROL_AF_STATE_NOT_FOCUSED_LOCKED
AF has failed to focus successfully and has locked focus.
static int CONTROL_AF_STATE_PASSIVE_FOCUSED
AF currently believes it is in focus, but may restart scanning at any time.
static int CONTROL_AF_STATE_PASSIVE_SCAN
AF is currently performing an AF scan initiated by the camera itself in a continuous auto-focus mode.
static int CONTROL_AF_STATE_PASSIVE_UNFOCUSED
AF finished a passive scan without finding focus, and may restart scanning at any time.
static CaptureResult.Key<Point> LASER_POINT
The last known position of the laser pointer within the frame.
static CaptureResult.Key<Point> LASER_POINT_OFFSET
The last known position of the laser pointer on the sensor, as an offset with respect to the sensor center.
static CaptureResult.Key<Float> LENS_FOCUS_DISTANCE
The distance to plane of sharpest focus.
static CaptureResult.Key<Barcode[]> POSTPROCESS_BARCODES
List of the barcodes detected through the barcode detection and decoding system.
static CaptureResult.Key<Long> SENSOR_EXPOSURE_TIME
Duration each pixel has been exposed to light.
static CaptureResult.Key<Float> SENSOR_GAIN
Analog gain.
static CaptureResult.Key<Long> SENSOR_TIMESTAMP
Time at start of image capture.

Constructor Summary

Constructor and Description
CaptureResult() 

Method Summary

Modifier and Type Method and Description
abstract boolean containsKey(CaptureResult.Key<?> key)
Determine whether this capture result has a value set for key.
abstract <T> T get(CaptureResult.Key<T> key)
Get a capture result field value.
<T> T get(CaptureResult.Key<T> key, T defaultValue)
Get a capture result field value.
abstract long getFrameNumber()
Gets the frame number associated with this result.
abstract List<CaptureResult.Key<?>> getKeys()
Return a list of the keys contained in this map.
abstract CaptureRequest getRequest()
Gets the request associated with this result.
abstract int getSequenceId()
Gets the sequence ID for this failed capture that was returned by the CaptureSession.capture family of functions.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SENSOR_TIMESTAMP

public static final CaptureResult.Key<Long> SENSOR_TIMESTAMP

Time at start of image capture.

Units:
Nanoseconds

CONTROL_AF_STATE

public static final CaptureResult.Key<Integer> CONTROL_AF_STATE
Current state of auto-focus (AF) algorithm.

The state in the result is the state for this image (in sync with this image): if AF state becomes FOCUSED, then the image data associated with this result should be sharp.

The camera device may perform several state transitions between two results, if it is allowed by the state transition table. For example, INACTIVE may never actually be seen in a result.

Switching between or enabling AF modes always resets the AF state to INACTIVE.

Below are the state transition tables for different AF modes.

When AF mode is OFF:

State Transition cause New state Notes
INACTIVE INACTIVE Never changes

When AF mode is AUTO or LASER_ASSISTED:

State Transition cause New state Notes
INACTIVE AF_TRIGGER ACTIVE_SCAN Start AF sweep, lens now moving
ACTIVE_SCAN AF sweep done FOCUSED_LOCKED Focused, lens now locked
ACTIVE_SCAN AF sweep done NOT_FOCUSED_LOCKED Not focused, lens now locked
ACTIVE_SCAN AF_CANCEL INACTIVE Cancel/reset AF, lens now locked
FOCUSED_LOCKED AF_TRIGGER ACTIVE_SCAN Start new sweep, lens now moving
FOCUSED_LOCKED AF_CANCEL INACTIVE Cancel/reset AF
NOT_FOCUSED_LOCKED AF_TRIGGER ACTIVE_SCAN Start new sweep, lens now moving
NOT_FOCUSED_LOCKED AF_CANCEL INACTIVE Cancel/reset AF

When AF mode is CONTINUOUS_PICTURE:

State Transition cause New state Notes
INACTIVE New scan PASSIVE_SCAN Start AF sweep, lens now moving
INACTIVE AF_TRIGGER NOT_FOCUSED_LOCKED AF state query, lens now locked
PASSIVE_SCAN AF sweep done PASSIVE_FOCUSED Focused, lens now locked
PASSIVE_SCAN AF sweep done PASSIVE_UNFOCUSED Not focused, lens now locked
PASSIVE_SCAN AF_TRIGGER FOCUSED_LOCKED Immediate transition, if focus is good, lens now locked
PASSIVE_SCAN AF_TRIGGER NOT_FOCUSED_LOCKED Immediate transition, if focus is bad, lens now locked
PASSIVE_SCAN AF_CANCEL INACTIVE Cancel/reset AF, lens now locked
PASSIVE_FOCUSED New scan PASSIVE_SCAN Start AF sweep, lens now moving
PASSIVE_UNFOCUSED New scan PASSIVE_SCAN Start AF sweep, lens now moving
PASSIVE_FOCUSED AF_TRIGGER FOCUSED_LOCKED Immediate transition, lens now locked
PASSIVE_UNFOCUSED AF_TRIGGER NOT_FOCUSED_LOCKED Immediate transition, lens now locked
FOCUSED_LOCKED AF_TRIGGER FOCUSED_LOCKED No effect
FOCUSED_LOCKED AF_CANCEL INACTIVE Restart AF scan
NOT_FOCUSED_LOCKED AF_TRIGGER NOT_FOCUSED_LOCKED No effect
NOT_FOCUSED_LOCKED AF_CANCEL INACTIVE Restart AF scan

Possible values:

See Also:
CaptureRequest.CONTROL_AF_MODE, CaptureRequest.CONTROL_AF_TRIGGER

CONTROL_AF_STATE_INACTIVE

public static final int CONTROL_AF_STATE_INACTIVE
AF is off or has not yet tried to scan/been asked to scan.

When a camera is opened, it starts in this state. This is a transient state, the camera may skip reporting this state in capture results.

See Also:
CONTROL_AF_STATE

CONTROL_AF_STATE_PASSIVE_SCAN

public static final int CONTROL_AF_STATE_PASSIVE_SCAN
AF is currently performing an AF scan initiated by the camera itself in a continuous auto-focus mode.

Only used for CONTINUOUS_* AF modes. This is a transient state, the camera may skip reporting this state in capture results.

See Also:
CONTROL_AF_STATE

CONTROL_AF_STATE_PASSIVE_FOCUSED

public static final int CONTROL_AF_STATE_PASSIVE_FOCUSED
AF currently believes it is in focus, but may restart scanning at any time.

Only used for CONTINUOUS_* AF modes. This is a transient state, the camera may skip reporting this state in capture results.

See Also:
CONTROL_AF_STATE

CONTROL_AF_STATE_ACTIVE_SCAN

public static final int CONTROL_AF_STATE_ACTIVE_SCAN
AF is performing an AF scan because it was triggered by AF trigger.

Only used for AUTO, MACRO and LASER_ASSISTED AF modes. This is a transient state, the camera may skip reporting this state in capture results.

See Also:
CONTROL_AF_STATE

CONTROL_AF_STATE_FOCUSED_LOCKED

public static final int CONTROL_AF_STATE_FOCUSED_LOCKED
AF believes it is focused correctly and has locked focus.

This state is reached only after an explicit START AF trigger has been sent, when good focus has been obtained.

The lens wil remain stationary until the AF mode is changed or a new AF trigger is sent to the camera.

See Also:
CONTROL_AF_STATE

CONTROL_AF_STATE_NOT_FOCUSED_LOCKED

public static final int CONTROL_AF_STATE_NOT_FOCUSED_LOCKED
AF has failed to focus successfully and has locked focus.

This state is reached only after an explicit START AF trigger has been sent, when good focus cannot be obtained.

The lens wil remain stationary until the AF mode is changed or a new AF trigger is sent to the camera.

See Also:
CONTROL_AF_STATE

CONTROL_AF_STATE_PASSIVE_UNFOCUSED

public static final int CONTROL_AF_STATE_PASSIVE_UNFOCUSED
AF finished a passive scan without finding focus, and may restart scanning at any time.

Only used for CONTINUOUS_* AF modes. This is a transient state, the camera may skip reporting this state in capture results.

See Also:
CONTROL_AF_STATE

LENS_FOCUS_DISTANCE

public static final CaptureResult.Key<Float> LENS_FOCUS_DISTANCE

The distance to plane of sharpest focus.

A value of 0.0f means infinity focus.

Units:
Diopters (1/meter)

COLOR_CORRECTION_GAIN_BLUE

public static final CaptureResult.Key<Float> COLOR_CORRECTION_GAIN_BLUE

Gain applied to the blue Bayer raw color channel for white-balance relative to the green channel.

Units:
Unit-less (multiplier)

Since:
1.2

COLOR_CORRECTION_GAIN_RED

public static final CaptureResult.Key<Float> COLOR_CORRECTION_GAIN_RED

Gain applied to the red Bayer raw color channel for white-balance relative to the green channel.

Units:
Unit-less (multiplier)

Since:
1.2

SENSOR_EXPOSURE_TIME

public static final CaptureResult.Key<Long> SENSOR_EXPOSURE_TIME

Duration each pixel has been exposed to light.

Units:
Nanoseconds

See Also:
CameraCharacteristics.SENSOR_MIN_EXPOSURE_TIME, CameraCharacteristics.SENSOR_MAX_EXPOSURE_TIME

SENSOR_GAIN

public static final CaptureResult.Key<Float> SENSOR_GAIN

Analog gain.

Units:
Unit-less (multiplier)

See Also:
CameraCharacteristics.SENSOR_MAX_GAIN

LASER_POINT

public static final CaptureResult.Key<Point> LASER_POINT
The last known position of the laser pointer within the frame.

This result is only present when Laser-Assisted Auto-Focus is enabled and the auto-focus algorithm has been triggered at least once. If the laser pointer could not be found or the algorithm failed in another way, this result key will not be present.

Units:
Frame pixels

See Also:
LASER_POINT_OFFSET, CaptureRequest.CONTROL_AF_MODE_LASER_ASSISTED

LASER_POINT_OFFSET

public static final CaptureResult.Key<Point> LASER_POINT_OFFSET
The last known position of the laser pointer on the sensor, as an offset with respect to the sensor center.

This result is only present when Laser-Assisted Auto-Focus is enabled and the auto-focus algorithm has been triggered at least once. If the laser pointer could not be found or the algorithm failed in another way, this result key will not be present.

The value of this result can be passed to the SCALER_OFFSET capture request setting to digitally zoom in on the region targeted by the laser.

Units:
Sensor pixels

See Also:
LASER_POINT, CaptureRequest.CONTROL_AF_MODE_LASER_ASSISTED, CaptureRequest.SCALER_OFFSET

POSTPROCESS_BARCODES

public static final CaptureResult.Key<Barcode[]> POSTPROCESS_BARCODES
Since:
1.2

Constructor Detail

CaptureResult

public CaptureResult()

Method Detail

get

@CheckResult
 @Nullable
public abstract <T> T get(@NonNull
                                                  CaptureResult.Key<T> key)
Get a capture result field value.
Type Parameters:
T - The key type.
Parameters:
key - The field to read (keys are defined as constants in CaptureResult.
Returns:
The value of the key, or null if the field is not set.

get

@CheckResult
 @NonNull
public <T> T get(@NonNull
                                        CaptureResult.Key<T> key,
                                        @NonNull
                                        T defaultValue)
Get a capture result field value.
Type Parameters:
T - The key type.
Parameters:
key - The field to read (keys are defined as constants in CaptureResult.
defaultValue - The default value to return if the field is not set.
Returns:
The value of the key, or defaultValue if the field is not set.

getKeys

@CheckResult
 @NonNull
public abstract List<CaptureResult.Key<?>> getKeys()

Return a list of the keys contained in this map.

The list returned is not modifiable, so any attempts to modify it will throw an UnsupportedOperationException.

All values retrieved by a key from this list with get(Key) are guaranteed to be non-null. Each key is only listed once in the list. The order of the keys is undefined.

Returns:
A list of the keys contained in this capture result.

containsKey

@CheckResult
public abstract boolean containsKey(@NonNull
                                                 CaptureResult.Key<?> key)
Determine whether this capture result has a value set for key.
Parameters:
key - The field to check.
Returns:
Whether this map contains a value for key.

getRequest

@CheckResult
 @NonNull
public abstract CaptureRequest getRequest()

Gets the request associated with this result.

This is the same request as the one passed as second argument of CaptureListener.onCaptureCompleted(CaptureSession, CaptureRequest, CaptureResult). In particular,

camera.capture(someRequest, new CaptureAdapter() {
      @Override
     void onCaptureCompleted(CameraSession camera, CaptureRequest request, CaptureResult result) {
         assert(result.getRequest().equals(request) == true);
     }
 }, null);

Returns:
The request associated with this result. Never null.

getSequenceId

@CheckResult
public abstract int getSequenceId()

Gets the sequence ID for this failed capture that was returned by the CaptureSession.capture family of functions.

The sequence ID is a unique monotonically increasing value starting from 0, incremented every time a new group of requests is submitted to the CameraSession.

Returns:
The ID for the sequence of requests that this capture result is part of.

getFrameNumber

@CheckResult
public abstract long getFrameNumber()

Gets the frame number associated with this result.

Whenever a request has been processed, regardless of its outcome, it gets a unique frame number assigned to its future result/failed capture.

This value increases monotonically, starting with 0, for every new result or failure; and the scope is the lifetime of the CameraDevice.

Returns:
The frame number.