java.lang.Object | ||
↳ | android.hardware.camera2.CameraMetadata<TKey> | |
↳ | android.hardware.camera2.CaptureResult |
Known Direct Subclasses |
The subset of the results of a single image capture from the image sensor.
Contains a subset of the final configuration for the capture hardware (sensor, lens, flash), the processing pipeline, the control algorithms, and the output buffers.
CaptureResults are produced by a CameraDevice
after processing a
CaptureRequest
. All properties listed for capture requests can also
be queried on the capture result, to determine the final values used for
capture. The result also includes additional metadata about the state of the
camera device during the capture.
Not all properties returned by getAvailableCaptureResultKeys()
are necessarily available. Some results are partial
and will
not have every key set. Only total
results are guaranteed to have
every key available that was enabled by the request.
CaptureResult
objects are immutable.
Nested Classes | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
CaptureResult.Key<T> | A Key is used to do capture result field lookups with
get(CaptureResult.Key . |
[Expand]
Inherited Constants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.hardware.camera2.CameraMetadata
|
Fields | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
BLACK_LEVEL_LOCK | Whether black-level compensation is locked to its current values, or is free to vary. |
||||||||||
COLOR_CORRECTION_GAINS | Gains applying to Bayer raw color channels for white-balance. |
||||||||||
COLOR_CORRECTION_MODE | The mode control selects how the image data is converted from the sensor's native color into linear sRGB color. |
||||||||||
COLOR_CORRECTION_TRANSFORM | A color transform matrix to use to transform from sensor RGB color space to output linear sRGB color space. |
||||||||||
CONTROL_AE_ANTIBANDING_MODE | The desired setting for the camera device's auto-exposure algorithm's antibanding compensation. |
||||||||||
CONTROL_AE_EXPOSURE_COMPENSATION | Adjustment to auto-exposure (AE) target image brightness. |
||||||||||
CONTROL_AE_LOCK | Whether auto-exposure (AE) is currently locked to its latest calculated values. |
||||||||||
CONTROL_AE_MODE | The desired mode for the camera device's auto-exposure routine. |
||||||||||
CONTROL_AE_PRECAPTURE_TRIGGER | Whether the camera device will trigger a precapture metering sequence when it processes this request. |
||||||||||
CONTROL_AE_REGIONS | List of areas to use for metering. |
||||||||||
CONTROL_AE_STATE | Current state of the auto-exposure (AE) algorithm. |
||||||||||
CONTROL_AE_TARGET_FPS_RANGE | Range over which fps can be adjusted to maintain exposure. |
||||||||||
CONTROL_AF_MODE | Whether auto-focus (AF) is currently enabled, and what mode it is set to. |
||||||||||
CONTROL_AF_REGIONS | List of areas to use for focus estimation. |
||||||||||
CONTROL_AF_STATE | Current state of auto-focus (AF) algorithm. |
||||||||||
CONTROL_AF_TRIGGER | Whether the camera device will trigger autofocus for this request. |
||||||||||
CONTROL_AWB_LOCK | Whether auto-white balance (AWB) is currently locked to its latest calculated values. |
||||||||||
CONTROL_AWB_MODE | Whether auto-white balance (AWB) is currently setting the color transform fields, and what its illumination target is. |
||||||||||
CONTROL_AWB_REGIONS | List of areas to use for illuminant estimation. |
||||||||||
CONTROL_AWB_STATE | Current state of auto-white balance (AWB) algorithm. |
||||||||||
CONTROL_CAPTURE_INTENT | Information to the camera device 3A (auto-exposure, auto-focus, auto-white balance) routines about the purpose of this capture, to help the camera device to decide optimal 3A strategy. |
||||||||||
CONTROL_EFFECT_MODE | A special color effect to apply. |
||||||||||
CONTROL_MODE | Overall mode of 3A control routines. |
||||||||||
CONTROL_SCENE_MODE | A camera mode optimized for conditions typical in a particular capture setting. |
||||||||||
CONTROL_VIDEO_STABILIZATION_MODE | Whether video stabilization is active. |
||||||||||
EDGE_MODE | Operation mode for edge enhancement. |
||||||||||
FLASH_MODE | The desired mode for for the camera device's flash control. |
||||||||||
FLASH_STATE | Current state of the flash unit. |
||||||||||
HOT_PIXEL_MODE | Set operational mode for hot pixel correction. |
||||||||||
JPEG_GPS_LOCATION | A location object to use when generating image GPS metadata. |
||||||||||
JPEG_ORIENTATION | Orientation of JPEG image to write |
||||||||||
JPEG_QUALITY | Compression quality of the final JPEG image. |
||||||||||
JPEG_THUMBNAIL_QUALITY | Compression quality of JPEG thumbnail. |
||||||||||
JPEG_THUMBNAIL_SIZE | Resolution of embedded JPEG thumbnail. |
||||||||||
LENS_APERTURE | The ratio of lens focal length to the effective aperture diameter. |
||||||||||
LENS_FILTER_DENSITY | State of lens neutral density filter(s). |
||||||||||
LENS_FOCAL_LENGTH | The current lens focal length; used for optical zoom. |
||||||||||
LENS_FOCUS_DISTANCE | Distance to plane of sharpest focus, measured from frontmost surface of the lens. |
||||||||||
LENS_FOCUS_RANGE | The range of scene distances that are in sharp focus (depth of field). |
||||||||||
LENS_OPTICAL_STABILIZATION_MODE | Sets whether the camera device uses optical image stabilization (OIS) when capturing images. |
||||||||||
LENS_STATE | Current lens status. |
||||||||||
NOISE_REDUCTION_MODE | Mode of operation for the noise reduction algorithm. |
||||||||||
REQUEST_FRAME_COUNT | A frame counter set by the framework. |
||||||||||
REQUEST_PIPELINE_DEPTH | Specifies the number of pipeline stages the frame went through from when it was exposed to when the final completed result was available to the framework. |
||||||||||
SCALER_CROP_REGION | The region of the sensor to read out for this capture. |
||||||||||
SENSOR_EXPOSURE_TIME | Duration each pixel is exposed to light. |
||||||||||
SENSOR_FRAME_DURATION | Duration from start of frame exposure to start of next frame exposure. |
||||||||||
SENSOR_GREEN_SPLIT | The worst-case divergence between Bayer green channels. |
||||||||||
SENSOR_NEUTRAL_COLOR_POINT | The estimated camera neutral color in the native sensor colorspace at the time of capture. |
||||||||||
SENSOR_SENSITIVITY | The amount of gain applied to sensor data before processing. |
||||||||||
SENSOR_TEST_PATTERN_DATA | A pixel |
||||||||||
SENSOR_TEST_PATTERN_MODE | When enabled, the sensor sends a test pattern instead of doing a real exposure from the camera. |
||||||||||
SENSOR_TIMESTAMP | Time at start of exposure of first row of the image sensor, in nanoseconds. |
||||||||||
SHADING_MODE | Quality of lens shading correction applied to the image data. |
||||||||||
STATISTICS_FACES | List of the faces detected through camera face detection in this result. |
||||||||||
STATISTICS_FACE_DETECT_MODE | Control for the face detector unit. |
||||||||||
STATISTICS_HOT_PIXEL_MAP | List of |
||||||||||
STATISTICS_HOT_PIXEL_MAP_MODE | Operating mode for hotpixel map generation. |
||||||||||
STATISTICS_LENS_SHADING_CORRECTION_MAP | The shading map is a low-resolution floating-point map that lists the coefficients used to correct for vignetting, for each Bayer color channel. |
||||||||||
STATISTICS_LENS_SHADING_MAP_MODE | Whether the camera device will output the lens shading map in output result metadata. |
||||||||||
STATISTICS_SCENE_FLICKER | The camera device estimated scene illumination lighting frequency. |
||||||||||
TONEMAP_CURVE | Tonemapping / contrast / gamma curve to use when |
||||||||||
TONEMAP_MODE | High-level global contrast/gamma/tonemapping control. |
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Get a capture result field value.
| |||||||||||
Get the frame number associated with this result.
| |||||||||||
Returns a list of the keys contained in this map.
| |||||||||||
Get the request associated with this result.
| |||||||||||
The sequence ID for this failure that was returned by the
capture(CaptureRequest, CameraDevice.CaptureListener, Handler) family of functions. |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.hardware.camera2.CameraMetadata
| |||||||||||
From class
java.lang.Object
|
Whether black-level compensation is locked to its current values, or is free to vary.
Whether the black level offset was locked for this frame. Should be
ON if android.blackLevel.lock
was ON in the capture request, unless
a change in other capture settings forced the camera device to
perform a black level reset.
Gains applying to Bayer raw color channels for white-balance.
These per-channel gains are either set by the camera device
when the request android.colorCorrection.mode
is not
TRANSFORM_MATRIX, or directly by the application in the
request when the android.colorCorrection.mode
is
TRANSFORM_MATRIX.
The gains in the result metadata are the gains actually applied by the camera device to the current frame.
The mode control selects how the image data is converted from the sensor's native color into linear sRGB color.
When auto-white balance (AWB) is enabled with android.control.awbMode
, this
control is overridden by the AWB routine. When AWB is disabled, the
application controls how the color mapping is performed.
We define the expected processing pipeline below. For consistency across devices, this is always the case with TRANSFORM_MATRIX.
When either FULL or HIGH_QUALITY is used, the camera device may
do additional processing but android.colorCorrection.gains
and
android.colorCorrection.transform
will still be provided by the
camera device (in the results) and be roughly correct.
Switching to TRANSFORM_MATRIX and using the data provided from FAST or HIGH_QUALITY will yield a picture with the same white point as what was produced by the camera device in the earlier frame.
The expected processing pipeline is as follows:
The white balance is encoded by two values, a 4-channel white-balance gain vector (applied in the Bayer domain), and a 3x3 color transform matrix (applied after demosaic).
The 4-channel white-balance gains are defined as:
android.colorCorrection.gains
= [ R G_even G_odd B ]
where G_even
is the gain for green pixels on even rows of the
output, and G_odd
is the gain for green pixels on the odd rows.
These may be identical for a given camera device implementation; if
the camera device does not support a separate gain for even/odd green
channels, it will use the G_even
value, and write G_odd
equal to
G_even
in the output result metadata.
The matrices for color transforms are defined as a 9-entry vector:
android.colorCorrection.transform
= [ I0 I1 I2 I3 I4 I5 I6 I7 I8 ]
which define a transform from input sensor colors, P_in = [ r g b ]
,
to output linear sRGB, P_out = [ r' g' b' ]
,
with colors as follows:
r' = I0r + I1g + I2b
g' = I3r + I4g + I5b
b' = I6r + I7g + I8b
Both the input and output value ranges must match. Overflow/underflow values are clipped to fit within the range.
A color transform matrix to use to transform from sensor RGB color space to output linear sRGB color space.
This matrix is either set by the camera device when the request
android.colorCorrection.mode
is not TRANSFORM_MATRIX, or
directly by the application in the request when the
android.colorCorrection.mode
is TRANSFORM_MATRIX.
In the latter case, the camera device may round the matrix to account
for precision issues; the final rounded matrix should be reported back
in this matrix result metadata. The transform should keep the magnitude
of the output color values within [0, 1.0]
(assuming input color
values is within the normalized range [0, 1.0]
), or clipping may occur.
The desired setting for the camera device's auto-exposure algorithm's antibanding compensation.
Some kinds of lighting fixtures, such as some fluorescent lights, flicker at the rate of the power supply frequency (60Hz or 50Hz, depending on country). While this is typically not noticeable to a person, it can be visible to a camera device. If a camera sets its exposure time to the wrong value, the flicker may become visible in the viewfinder as flicker or in a final captured image, as a set of variable-brightness bands across the image.
Therefore, the auto-exposure routines of camera devices include antibanding routines that ensure that the chosen exposure value will not cause such banding. The choice of exposure time depends on the rate of flicker, which the camera device can detect automatically, or the expected rate can be selected by the application using this control.
A given camera device may not support all of the possible
options for the antibanding mode. The
android.control.aeAvailableAntibandingModes
key contains
the available modes for a given camera device.
The default mode is AUTO, which must be supported by all camera devices.
If manual exposure control is enabled (by setting
android.control.aeMode
or android.control.mode
to OFF),
then this setting has no effect, and the application must
ensure it selects exposure times that do not cause banding
issues. The android.statistics.sceneFlicker
key can assist
the application in this.
Adjustment to auto-exposure (AE) target image brightness.
The adjustment is measured as a count of steps, with the
step size defined by android.control.aeCompensationStep
and the
allowed range by android.control.aeCompensationRange
.
For example, if the exposure value (EV) step is 0.333, '6'
will mean an exposure compensation of +2 EV; -3 will mean an
exposure compensation of -1 EV. One EV represents a doubling
of image brightness. Note that this control will only be
effective if android.control.aeMode
!=
OFF. This control
will take effect even when android.control.aeLock
== true
.
In the event of exposure compensation value being changed, camera device
may take several frames to reach the newly requested exposure target.
During that time, android.control.aeState
field will be in the SEARCHING
state. Once the new exposure target is reached, android.control.aeState
will
change from SEARCHING to either CONVERGED, LOCKED (if AE lock is enabled), or
FLASH_REQUIRED (if the scene is too dark for still capture).
Whether auto-exposure (AE) is currently locked to its latest calculated values.
Note that even when AE is locked, the flash may be
fired if the android.control.aeMode
is ON_AUTO_FLASH / ON_ALWAYS_FLASH /
ON_AUTO_FLASH_REDEYE.
When android.control.aeExposureCompensation
is changed, even if the AE lock
is ON, the camera device will still adjust its exposure value.
If AE precapture is triggered (see android.control.aePrecaptureTrigger
)
when AE is already locked, the camera device will not change the exposure time
(android.sensor.exposureTime
) and sensitivity (android.sensor.sensitivity
)
parameters. The flash may be fired if the android.control.aeMode
is ON_AUTO_FLASH/ON_AUTO_FLASH_REDEYE and the scene is too dark. If the
android.control.aeMode
is ON_ALWAYS_FLASH, the scene may become overexposed.
See android.control.aeState
for AE lock related state transition details.
The desired mode for the camera device's auto-exposure routine.
This control is only effective if android.control.mode
is
AUTO.
When set to any of the ON modes, the camera device's
auto-exposure routine is enabled, overriding the
application's selected exposure time, sensor sensitivity,
and frame duration (android.sensor.exposureTime
,
android.sensor.sensitivity
, and
android.sensor.frameDuration
). If one of the FLASH modes
is selected, the camera device's flash unit controls are
also overridden.
The FLASH modes are only available if the camera device
has a flash unit (android.flash.info.available
is true
).
If flash TORCH mode is desired, this field must be set to
ON or OFF, and android.flash.mode
set to TORCH.
When set to any of the ON modes, the values chosen by the camera device auto-exposure routine for the overridden fields for a given capture will be available in its CaptureResult.
Whether the camera device will trigger a precapture metering sequence when it processes this request.
This entry is normally set to IDLE, or is not included at all in the request settings. When included and set to START, the camera device will trigger the autoexposure precapture metering sequence.
The precapture sequence should triggered before starting a high-quality still capture for final metering decisions to be made, and for firing pre-capture flash pulses to estimate scene brightness and required final capture flash power, when the flash is enabled.
Normally, this entry should be set to START for only a single request, and the application should wait until the sequence completes before starting a new one.
The exact effect of auto-exposure (AE) precapture trigger
depends on the current AE mode and state; see
android.control.aeState
for AE precapture state transition
details.
List of areas to use for metering.
The coordinate system is based on the active pixel array,
with (0,0) being the top-left pixel in the active pixel array, and
(android.sensor.info.activeArraySize
.width - 1,
android.sensor.info.activeArraySize
.height - 1) being the
bottom-right pixel in the active pixel array.
The weight must range from 0 to 1000, and represents a weight for every pixel in the area. This means that a large metering area with the same weight as a smaller area will have more effect in the metering result. Metering areas can partially overlap and the camera device will add the weights in the overlap region.
If all regions have 0 weight, then no specific metering area
needs to be used by the camera device. If the metering region is
outside the used android.scaler.cropRegion
returned in capture result metadata,
the camera device will ignore the sections outside the region and output the
used sections in the result metadata.
Current state of the auto-exposure (AE) algorithm.
Switching between or enabling AE modes (android.control.aeMode
) always
resets the AE state to INACTIVE. Similarly, switching between android.control.mode
,
or android.control.sceneMode
if
resets all
the algorithm states to INACTIVE.android.control.mode
== USE_SCENE_MODE
The camera device can do 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.
The state in the result is the state for this image (in sync with this image): if AE state becomes CONVERGED, then the image data associated with this result should be good to use.
Below are state transition tables for different AE modes.
State | Transition Cause | New State | Notes |
---|---|---|---|
INACTIVE | INACTIVE | Camera device auto exposure algorithm is disabled |
When android.control.aeMode
is AE_MODE_ON_*:
State | Transition Cause | New State | Notes |
---|---|---|---|
INACTIVE | Camera device initiates AE scan | SEARCHING | Values changing |
INACTIVE | android.control.aeLock is ON |
LOCKED | Values locked |
SEARCHING | Camera device finishes AE scan | CONVERGED | Good values, not changing |
SEARCHING | Camera device finishes AE scan | FLASH_REQUIRED | Converged but too dark w/o flash |
SEARCHING | android.control.aeLock is ON |
LOCKED | Values locked |
CONVERGED | Camera device initiates AE scan | SEARCHING | Values changing |
CONVERGED | android.control.aeLock is ON |
LOCKED | Values locked |
FLASH_REQUIRED | Camera device initiates AE scan | SEARCHING | Values changing |
FLASH_REQUIRED | android.control.aeLock is ON |
LOCKED | Values locked |
LOCKED | android.control.aeLock is OFF |
SEARCHING | Values not good after unlock |
LOCKED | android.control.aeLock is OFF |
CONVERGED | Values good after unlock |
LOCKED | android.control.aeLock is OFF |
FLASH_REQUIRED | Exposure good, but too dark |
PRECAPTURE | Sequence done. android.control.aeLock is OFF |
CONVERGED | Ready for high-quality capture |
PRECAPTURE | Sequence done. android.control.aeLock is ON |
LOCKED | Ready for high-quality capture |
Any state | android.control.aePrecaptureTrigger is START |
PRECAPTURE | Start AE precapture metering sequence |
For the above table, the camera device may skip reporting any state changes that happen without application intervention (i.e. mode switch, trigger, locking). Any state that can be skipped in that manner is called a transient state.
For example, for above AE modes (AE_MODE_ON_*), in addition to the state transitions listed in above table, it is also legal for the camera device to skip one or more transient states between two results. See below table for examples:
State | Transition Cause | New State | Notes |
---|---|---|---|
INACTIVE | Camera device finished AE scan | CONVERGED | Values are already good, transient states are skipped by camera device. |
Any state | android.control.aePrecaptureTrigger is START, sequence done |
FLASH_REQUIRED | Converged but too dark w/o flash after a precapture sequence, transient states are skipped by camera device. |
Any state | android.control.aePrecaptureTrigger is START, sequence done |
CONVERGED | Converged after a precapture sequence, transient states are skipped by camera device. |
CONVERGED | Camera device finished AE scan | FLASH_REQUIRED | Converged but too dark w/o flash after a new scan, transient states are skipped by camera device. |
FLASH_REQUIRED | Camera device finished AE scan | CONVERGED | Converged after a new scan, transient states are skipped by camera device. |
Range over which fps can be adjusted to maintain exposure.
Only constrains auto-exposure (AE) algorithm, not
manual control of android.sensor.exposureTime
Whether auto-focus (AF) is currently enabled, and what mode it is set to.
Only effective if android.control.mode
= AUTO and the lens is not fixed focus
(i.e.
).android.lens.info.minimumFocusDistance
> 0
If the lens is controlled by the camera device auto-focus algorithm,
the camera device will report the current AF status in android.control.afState
in result metadata.
List of areas to use for focus estimation.
The coordinate system is based on the active pixel array,
with (0,0) being the top-left pixel in the active pixel array, and
(android.sensor.info.activeArraySize
.width - 1,
android.sensor.info.activeArraySize
.height - 1) being the
bottom-right pixel in the active pixel array.
The weight must range from 0 to 1000, and represents a weight for every pixel in the area. This means that a large metering area with the same weight as a smaller area will have more effect in the metering result. Metering areas can partially overlap and the camera device will add the weights in the overlap region.
If all regions have 0 weight, then no specific metering area
needs to be used by the camera device. If the metering region is
outside the used android.scaler.cropRegion
returned in capture result metadata,
the camera device will ignore the sections outside the region and output the
used sections in the result metadata.
Current state of auto-focus (AF) algorithm.
Switching between or enabling AF modes (android.control.afMode
) always
resets the AF state to INACTIVE. Similarly, switching between android.control.mode
,
or android.control.sceneMode
if
resets all
the algorithm states to INACTIVE.android.control.mode
== USE_SCENE_MODE
The camera device can do 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.
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.
Below are state transition tables for different AF modes.
When android.control.afMode
is AF_MODE_OFF or AF_MODE_EDOF:
State | Transition Cause | New State | Notes |
---|---|---|---|
INACTIVE | INACTIVE | Never changes |
When android.control.afMode
is AF_MODE_AUTO or AF_MODE_MACRO:
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_CANCEL | INACTIVE | Cancel/reset AF |
FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep, Lens now moving |
NOT_FOCUSED_LOCKED | AF_CANCEL | INACTIVE | Cancel/reset AF |
NOT_FOCUSED_LOCKED | AF_TRIGGER | ACTIVE_SCAN | Start new sweep, Lens now moving |
Any state | Mode change | INACTIVE |
For the above table, the camera device may skip reporting any state changes that happen without application intervention (i.e. mode switch, trigger, locking). Any state that can be skipped in that manner is called a transient state.
For example, for these AF modes (AF_MODE_AUTO and AF_MODE_MACRO), in addition to the state transitions listed in above table, it is also legal for the camera device to skip one or more transient states between two results. See below table for examples:
State | Transition Cause | New State | Notes |
---|---|---|---|
INACTIVE | AF_TRIGGER | FOCUSED_LOCKED | Focus is already good or good after a scan, lens is now locked. |
INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | Focus failed after a scan, lens is now locked. |
FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | Focus is already good or good after a scan, lens is now locked. |
NOT_FOCUSED_LOCKED | AF_TRIGGER | FOCUSED_LOCKED | Focus is good after a scan, lens is not locked. |
When android.control.afMode
is AF_MODE_CONTINUOUS_VIDEO:
State | Transition Cause | New State | Notes |
---|---|---|---|
INACTIVE | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving |
INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query, Lens now locked |
PASSIVE_SCAN | Camera device completes current scan | PASSIVE_FOCUSED | End AF scan, Lens now locked |
PASSIVE_SCAN | Camera device fails current scan | PASSIVE_UNFOCUSED | End AF scan, 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 | Reset lens position, Lens now locked |
PASSIVE_FOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving |
PASSIVE_UNFOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, 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 |
When android.control.afMode
is AF_MODE_CONTINUOUS_PICTURE:
State | Transition Cause | New State | Notes |
---|---|---|---|
INACTIVE | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving |
INACTIVE | AF_TRIGGER | NOT_FOCUSED_LOCKED | AF state query, Lens now locked |
PASSIVE_SCAN | Camera device completes current scan | PASSIVE_FOCUSED | End AF scan, Lens now locked |
PASSIVE_SCAN | Camera device fails current scan | PASSIVE_UNFOCUSED | End AF scan, Lens now locked |
PASSIVE_SCAN | AF_TRIGGER | FOCUSED_LOCKED | Eventual transition once the focus is good. Lens now locked |
PASSIVE_SCAN | AF_TRIGGER | NOT_FOCUSED_LOCKED | Eventual transition if cannot find focus. Lens now locked |
PASSIVE_SCAN | AF_CANCEL | INACTIVE | Reset lens position, Lens now locked |
PASSIVE_FOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving |
PASSIVE_UNFOCUSED | Camera device initiates new scan | PASSIVE_SCAN | Start AF scan, Lens now moving |
PASSIVE_FOCUSED | AF_TRIGGER | FOCUSED_LOCKED | Immediate trans. Lens now locked |
PASSIVE_UNFOCUSED | AF_TRIGGER | NOT_FOCUSED_LOCKED | Immediate trans. 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 |
When switch between AF_MODE_CONTINUOUS_* (CAF modes) and AF_MODE_AUTO/AF_MODE_MACRO (AUTO modes), the initial INACTIVE or PASSIVE_SCAN states may be skipped by the camera device. When a trigger is included in a mode switch request, the trigger will be evaluated in the context of the new mode in the request. See below table for examples:
State | Transition Cause | New State | Notes |
---|---|---|---|
any state | CAF-->AUTO mode switch | INACTIVE | Mode switch without trigger, initial state must be INACTIVE |
any state | CAF-->AUTO mode switch with AF_TRIGGER | trigger-reachable states from INACTIVE | Mode switch with trigger, INACTIVE is skipped |
any state | AUTO-->CAF mode switch | passively reachable states from INACTIVE | Mode switch without trigger, passive transient state is skipped |
Whether the camera device will trigger autofocus for this request.
This entry is normally set to IDLE, or is not included at all in the request settings.
When included and set to START, the camera device will trigger the autofocus algorithm. If autofocus is disabled, this trigger has no effect.
When set to CANCEL, the camera device will cancel any active trigger, and return to its initial AF state.
Generally, applications should set this entry to START or CANCEL for only a single capture, and then return it to IDLE (or not set at all). Specifying START for multiple captures in a row means restarting the AF operation over and over again.
See android.control.afState
for what the trigger means for each AF mode.
Whether auto-white balance (AWB) is currently locked to its latest calculated values.
Note that AWB lock is only meaningful when
android.control.awbMode
is in the AUTO mode; in other modes,
AWB is already fixed to a specific setting.
Whether auto-white balance (AWB) is currently setting the color transform fields, and what its illumination target is.
This control is only effective if android.control.mode
is AUTO.
When set to the ON mode, the camera device's auto-white balance
routine is enabled, overriding the application's selected
android.colorCorrection.transform
, android.colorCorrection.gains
and
android.colorCorrection.mode
.
When set to the OFF mode, the camera device's auto-white balance
routine is disabled. The application manually controls the white
balance by android.colorCorrection.transform
, android.colorCorrection.gains
and android.colorCorrection.mode
.
When set to any other modes, the camera device's auto-white
balance routine is disabled. The camera device uses each
particular illumination target for white balance
adjustment. The application's values for
android.colorCorrection.transform
,
android.colorCorrection.gains
and
android.colorCorrection.mode
are ignored.
COLOR_CORRECTION_GAINS
COLOR_CORRECTION_MODE
COLOR_CORRECTION_TRANSFORM
CONTROL_MODE
CONTROL_AWB_MODE_OFF
CONTROL_AWB_MODE_AUTO
CONTROL_AWB_MODE_INCANDESCENT
CONTROL_AWB_MODE_FLUORESCENT
CONTROL_AWB_MODE_WARM_FLUORESCENT
CONTROL_AWB_MODE_DAYLIGHT
CONTROL_AWB_MODE_CLOUDY_DAYLIGHT
CONTROL_AWB_MODE_TWILIGHT
CONTROL_AWB_MODE_SHADE
List of areas to use for illuminant estimation.
The coordinate system is based on the active pixel array,
with (0,0) being the top-left pixel in the active pixel array, and
(android.sensor.info.activeArraySize
.width - 1,
android.sensor.info.activeArraySize
.height - 1) being the
bottom-right pixel in the active pixel array.
The weight must range from 0 to 1000, and represents a weight for every pixel in the area. This means that a large metering area with the same weight as a smaller area will have more effect in the metering result. Metering areas can partially overlap and the camera device will add the weights in the overlap region.
If all regions have 0 weight, then no specific metering area
needs to be used by the camera device. If the metering region is
outside the used android.scaler.cropRegion
returned in capture result metadata,
the camera device will ignore the sections outside the region and output the
used sections in the result metadata.
Current state of auto-white balance (AWB) algorithm.
Switching between or enabling AWB modes (android.control.awbMode
) always
resets the AWB state to INACTIVE. Similarly, switching between android.control.mode
,
or android.control.sceneMode
if
resets all
the algorithm states to INACTIVE.android.control.mode
== USE_SCENE_MODE
The camera device can do several state transitions between two results, if it is allowed by the state transition table. So INACTIVE may never actually be seen in a result.
The state in the result is the state for this image (in sync with this image): if AWB state becomes CONVERGED, then the image data associated with this result should be good to use.
Below are state transition tables for different AWB modes.
When
:android.control.awbMode
!= AWB_MODE_AUTO
State | Transition Cause | New State | Notes |
---|---|---|---|
INACTIVE | INACTIVE | Camera device auto white balance algorithm is disabled |
When android.control.awbMode
is AWB_MODE_AUTO:
State | Transition Cause | New State | Notes |
---|---|---|---|
INACTIVE | Camera device initiates AWB scan | SEARCHING | Values changing |
INACTIVE | android.control.awbLock is ON |
LOCKED | Values locked |
SEARCHING | Camera device finishes AWB scan | CONVERGED | Good values, not changing |
SEARCHING | android.control.awbLock is ON |
LOCKED | Values locked |
CONVERGED | Camera device initiates AWB scan | SEARCHING | Values changing |
CONVERGED | android.control.awbLock is ON |
LOCKED | Values locked |
LOCKED | android.control.awbLock is OFF |
SEARCHING | Values not good after unlock |
For the above table, the camera device may skip reporting any state changes that happen without application intervention (i.e. mode switch, trigger, locking). Any state that can be skipped in that manner is called a transient state.
For example, for this AWB mode (AWB_MODE_AUTO), in addition to the state transitions listed in above table, it is also legal for the camera device to skip one or more transient states between two results. See below table for examples:
State | Transition Cause | New State | Notes |
---|---|---|---|
INACTIVE | Camera device finished AWB scan | CONVERGED | Values are already good, transient states are skipped by camera device. |
LOCKED | android.control.awbLock is OFF |
CONVERGED | Values good after unlock, transient states are skipped by camera device. |
Information to the camera device 3A (auto-exposure, auto-focus, auto-white balance) routines about the purpose of this capture, to help the camera device to decide optimal 3A strategy.
This control (except for MANUAL) is only effective if
and any 3A routine is active.android.control.mode
!= OFF
ZERO_SHUTTER_LAG will be supported if android.request.availableCapabilities
contains ZSL. MANUAL will be supported if android.request.availableCapabilities
contains MANUAL_SENSOR.
A special color effect to apply.
When this mode is set, a color effect will be applied to images produced by the camera device. The interpretation and implementation of these color effects is left to the implementor of the camera device, and should not be depended on to be consistent (or present) across all devices.
A color effect will only be applied if
android.control.mode
!= OFF.
Overall mode of 3A control routines.
High-level 3A control. When set to OFF, all 3A control by the camera device is disabled. The application must set the fields for capture parameters itself.
When set to AUTO, the individual algorithm controls in
android.control.* are in effect, such as android.control.afMode
.
When set to USE_SCENE_MODE, the individual controls in android.control.* are mostly disabled, and the camera device implements one of the scene mode settings (such as ACTION, SUNSET, or PARTY) as it wishes. The camera device scene mode 3A settings are provided by android.control.sceneModeOverrides.
When set to OFF_KEEP_STATE, it is similar to OFF mode, the only difference is that this frame will not be used by camera device background 3A statistics update, as if this frame is never captured. This mode can be used in the scenario where the application doesn't want a 3A manual control capture to affect the subsequent auto 3A capture results.
A camera mode optimized for conditions typical in a particular capture setting.
This is the mode that that is active when
. Aside from FACE_PRIORITY,
these modes will disable android.control.mode
== USE_SCENE_MODEandroid.control.aeMode
,
android.control.awbMode
, and android.control.afMode
while in use.
The scene modes available for a given camera device are listed in
android.control.availableSceneModes
.
The interpretation and implementation of these scene modes is left to the implementor of the camera device. Their behavior will not be consistent across all devices, and any given device may only implement a subset of these modes.
CONTROL_AE_MODE
CONTROL_AF_MODE
CONTROL_AVAILABLE_SCENE_MODES
CONTROL_AWB_MODE
CONTROL_MODE
CONTROL_SCENE_MODE_DISABLED
CONTROL_SCENE_MODE_FACE_PRIORITY
CONTROL_SCENE_MODE_ACTION
CONTROL_SCENE_MODE_PORTRAIT
CONTROL_SCENE_MODE_LANDSCAPE
CONTROL_SCENE_MODE_NIGHT
CONTROL_SCENE_MODE_NIGHT_PORTRAIT
CONTROL_SCENE_MODE_THEATRE
CONTROL_SCENE_MODE_BEACH
CONTROL_SCENE_MODE_SNOW
CONTROL_SCENE_MODE_SUNSET
CONTROL_SCENE_MODE_STEADYPHOTO
CONTROL_SCENE_MODE_FIREWORKS
CONTROL_SCENE_MODE_SPORTS
CONTROL_SCENE_MODE_PARTY
CONTROL_SCENE_MODE_CANDLELIGHT
CONTROL_SCENE_MODE_BARCODE
Whether video stabilization is active.
Video stabilization automatically translates and scales images from the camera in order to stabilize motion between consecutive frames.
If enabled, video stabilization can modify the
android.scaler.cropRegion
to keep the video stream
stabilized
Operation mode for edge enhancement.
Edge/sharpness/detail enhancement. OFF means no enhancement will be applied by the camera device.
This must be set to one of the modes listed in android.edge.availableEdgeModes
.
FAST/HIGH_QUALITY both mean camera device determined enhancement will be applied. HIGH_QUALITY mode indicates that the camera device will use the highest-quality enhancement algorithms, even if it slows down capture rate. FAST means the camera device will not slow down capture rate when applying edge enhancement.
The desired mode for for the camera device's flash control.
This control is only effective when flash unit is available
(
).android.flash.info.available
== true
When this control is used, the android.control.aeMode
must be set to ON or OFF.
Otherwise, the camera device auto-exposure related flash control (ON_AUTO_FLASH,
ON_ALWAYS_FLASH, or ON_AUTO_FLASH_REDEYE) will override this control.
When set to OFF, the camera device will not fire flash for this capture.
When set to SINGLE, the camera device will fire flash regardless of the camera
device's auto-exposure routine's result. When used in still capture case, this
control should be used along with auto-exposure (AE) precapture metering sequence
(android.control.aePrecaptureTrigger
), otherwise, the image may be incorrectly exposed.
When set to TORCH, the flash will be on continuously. This mode can be used for use cases such as preview, auto-focus assist, still capture, or video recording.
The flash status will be reported by android.flash.state
in the capture result metadata.
Current state of the flash unit.
When the camera device doesn't have flash unit
(i.e.
), this state will always be UNAVAILABLE.
Other states indicate the current flash status.android.flash.info.available
== false
Set operational mode for hot pixel correction.
Valid modes for this camera device are listed in
android.hotPixel.availableHotPixelModes
.
Hotpixel correction interpolates out, or otherwise removes, pixels that do not accurately encode the incoming light (i.e. pixels that are stuck at an arbitrary value).
A location object to use when generating image GPS metadata.
Compression quality of the final JPEG image.
85-95 is typical usage range.
Resolution of embedded JPEG thumbnail.
When set to (0, 0) value, the JPEG EXIF will not contain thumbnail, but the captured JPEG will still be a valid image.
When a jpeg image capture is issued, the thumbnail size selected should have the same aspect ratio as the jpeg image.
If the thumbnail image aspect ratio differs from the JPEG primary image aspect ratio, the camera device creates the thumbnail by cropping it from the primary image. For example, if the primary image has 4:3 aspect ratio, the thumbnail image has 16:9 aspect ratio, the primary image will be cropped vertically (letterbox) to generate the thumbnail image. The thumbnail image will always have a smaller Field Of View (FOV) than the primary image when aspect ratios differ.
The ratio of lens focal length to the effective aperture diameter.
This will only be supported on the camera devices that
have variable aperture lens. The aperture value can only be
one of the values listed in android.lens.info.availableApertures
.
When this is supported and android.control.aeMode
is OFF,
this can be set along with android.sensor.exposureTime
,
android.sensor.sensitivity
, and android.sensor.frameDuration
to achieve manual exposure control.
The requested aperture value may take several frames to reach the
requested value; the camera device will report the current (intermediate)
aperture size in capture result metadata while the aperture is changing.
While the aperture is still changing, android.lens.state
will be set to MOVING.
When this is supported and android.control.aeMode
is one of
the ON modes, this will be overridden by the camera device
auto-exposure algorithm, the overridden values are then provided
back to the user in the corresponding result.
State of lens neutral density filter(s).
This will not be supported on most camera devices. On devices
where this is supported, this may only be set to one of the
values included in android.lens.info.availableFilterDensities
.
Lens filters are typically used to lower the amount of light the sensor is exposed to (measured in steps of EV). As used here, an EV step is the standard logarithmic representation, which are non-negative, and inversely proportional to the amount of light hitting the sensor. For example, setting this to 0 would result in no reduction of the incoming light, and setting this to 2 would mean that the filter is set to reduce incoming light by two stops (allowing 1/4 of the prior amount of light to the sensor).
It may take several frames before the lens filter density changes
to the requested value. While the filter density is still changing,
android.lens.state
will be set to MOVING.
The current lens focal length; used for optical zoom.
This setting controls the physical focal length of the camera device's lens. Changing the focal length changes the field of view of the camera device, and is usually used for optical zoom.
Like android.lens.focusDistance
and android.lens.aperture
, this
setting won't be applied instantaneously, and it may take several
frames before the lens can change to the requested focal length.
While the focal length is still changing, android.lens.state
will
be set to MOVING.
This is expected not to be supported on most devices.
Distance to plane of sharpest focus, measured from frontmost surface of the lens.
Should be zero for fixed-focus cameras
The range of scene distances that are in sharp focus (depth of field).
If variable focus not supported, can still report fixed depth of field range
Sets whether the camera device uses optical image stabilization (OIS) when capturing images.
OIS is used to compensate for motion blur due to small
movements of the camera during capture. Unlike digital image
stabilization (android.control.videoStabilizationMode
), OIS
makes use of mechanical elements to stabilize the camera
sensor, and thus allows for longer exposure times before
camera shake becomes apparent.
Not all devices will support OIS; see
android.lens.info.availableOpticalStabilization
for
available controls.
Current lens status.
For lens parameters android.lens.focalLength
, android.lens.focusDistance
,
android.lens.filterDensity
and android.lens.aperture
, when changes are requested,
they may take several frames to reach the requested values. This state indicates
the current status of the lens parameters.
When the state is STATIONARY, the lens parameters are not changing. This could be either because the parameters are all fixed, or because the lens has had enough time to reach the most recently-requested values. If all these lens parameters are not changable for a camera device, as listed below:
android.lens.info.minimumFocusDistance
== 0
), which means
android.lens.focusDistance
parameter will always be 0.android.lens.info.availableFocalLengths
contains single value),
which means the optical zoom is not supported.android.lens.info.availableFilterDensities
contains only 0).android.lens.info.availableApertures
contains single value).Then this state will always be STATIONARY.
When the state is MOVING, it indicates that at least one of the lens parameters is changing.
Mode of operation for the noise reduction algorithm.
Noise filtering control. OFF means no noise reduction will be applied by the camera device.
This must be set to a valid mode from
android.noiseReduction.availableNoiseReductionModes
.
FAST/HIGH_QUALITY both mean camera device determined noise filtering will be applied. HIGH_QUALITY mode indicates that the camera device will use the highest-quality noise filtering algorithms, even if it slows down capture rate. FAST means the camera device will not slow down capture rate when applying noise filtering.
A frame counter set by the framework. This value monotonically increases with every new result (that is, each new result has a unique frameCount value).
Reset on release()
Specifies the number of pipeline stages the frame went through from when it was exposed to when the final completed result was available to the framework.
Depending on what settings are used in the request, and what streams are configured, the data may undergo less processing, and some pipeline stages skipped.
See android.request.pipelineMaxDepth
for more details.
The region of the sensor to read out for this capture.
The crop region coordinate system is based off
android.sensor.info.activeArraySize
, with (0, 0)
being the
top-left corner of the sensor active array.
Output streams use this rectangle to produce their output, cropping to a smaller region if necessary to maintain the stream's aspect ratio, then scaling the sensor input to match the output's configured resolution.
The crop region is applied after the RAW to other color space (e.g. YUV) conversion. Since raw streams (e.g. RAW16) don't have the conversion stage, they are not croppable. The crop region will be ignored by raw streams.
For non-raw streams, any additional per-stream cropping will be done to maximize the final pixel area of the stream.
For example, if the crop region is set to a 4:3 aspect ratio, then 4:3 streams will use the exact crop region. 16:9 streams will further crop vertically (letterbox).
Conversely, if the crop region is set to a 16:9, then 4:3 outputs will crop horizontally (pillarbox), and 16:9 streams will match exactly. These additional crops will be centered within the crop region.
The width and height of the crop region cannot
be set to be smaller than
floor( activeArraySize.width /
and
android.scaler.availableMaxDigitalZoom
)floor( activeArraySize.height /
, respectively.android.scaler.availableMaxDigitalZoom
)
The camera device may adjust the crop region to account for rounding and other hardware requirements; the final crop region used will be included in the output capture result.
Duration each pixel is exposed to light.
If the sensor can't expose this exact duration, it should shorten the duration exposed to the nearest possible value (rather than expose longer).
Duration from start of frame exposure to start of next frame exposure.
The maximum frame rate that can be supported by a camera subsystem is a function of many factors:
Since these factors can vary greatly between different ISPs and sensors, the camera abstraction tries to represent the bandwidth restrictions with as simple a model as possible.
The model presented has the following characteristics:
The necessary information for the application, given the model above,
is provided via the android.scaler.streamConfigurationMap
field
using StreamConfigurationMap#getOutputMinFrameDuration(int, Size).
These are used to determine the maximum frame rate / minimum frame
duration that is possible for a given stream configuration.
Specifically, the application can use the following rules to determine the minimum frame duration it can request from the camera device:
S
.S
, by
looking it up in android.scaler.streamConfigurationMap
using
StreamConfigurationMap#getOutputMinFrameDuration(int, Size) (with
its respective size/format). Let this set of frame durations be called
F
.R
, the minimum frame duration allowed
for R
is the maximum out of all values in F
. Let the streams
used in R
be called S_r
.If none of the streams in S_r
have a stall time (listed in
StreamConfigurationMap#getOutputStallDuration(int,Size) using its
respective size/format), then the frame duration in
F
determines the steady state frame rate that the application will
get if it uses R
as a repeating request. Let this special kind
of request be called Rsimple
.
A repeating request Rsimple
can be occasionally interleaved
by a single capture of a new request Rstall
(which has at least
one in-use stream with a non-0 stall time) and if Rstall
has the
same minimum frame duration this will not cause a frame rate loss
if all buffers from the previous Rstall
have already been
delivered.
For more details about stalling, see StreamConfigurationMap#getOutputStallDuration(int,Size).
The worst-case divergence between Bayer green channels.
This value is an estimate of the worst case split between the Bayer green channels in the red and blue rows in the sensor color filter array.
The green split is calculated as follows:
R = max((mean_Gr + 1)/(mean_Gb + 1), (mean_Gb + 1)/(mean_Gr + 1))
The ratio R is the green split divergence reported for this property, which represents how much the green channels differ in the mosaic pattern. This value is typically used to determine the treatment of the green mosaic channels when demosaicing.
The green split value can be roughly interpreted as follows:
Optional - This value may be null
on some devices.
The estimated camera neutral color in the native sensor colorspace at the time of capture.
This value gives the neutral color point encoded as an RGB value in the native sensor color space. The neutral color point indicates the currently estimated white point of the scene illumination. It can be used to interpolate between the provided color transforms when processing raw sensor data.
The order of the values is R, G, B; where R is in the lowest index.
Optional - This value may be null
on some devices.
The amount of gain applied to sensor data before processing.
The sensitivity is the standard ISO sensitivity value, as defined in ISO 12232:2006.
The sensitivity must be within android.sensor.info.sensitivityRange
, and
if if it less than android.sensor.maxAnalogSensitivity
, the camera device
is guaranteed to use only analog amplification for applying the gain.
If the camera device cannot apply the exact sensitivity requested, it will reduce the gain to the nearest supported value. The final sensitivity used will be available in the output capture result.
A pixel [R, G_even, G_odd, B]
that supplies the test pattern
when android.sensor.testPatternMode
is SOLID_COLOR.
Each color channel is treated as an unsigned 32-bit integer. The camera device then uses the most significant X bits that correspond to how many bits are in its Bayer raw sensor output.
For example, a sensor with RAW10 Bayer output would use the 10 most significant bits from each color channel.
Optional - This value may be null
on some devices.
When enabled, the sensor sends a test pattern instead of doing a real exposure from the camera.
When a test pattern is enabled, all manual sensor controls specified by android.sensor.* will be ignored. All other controls should work as normal.
For example, if manual flash is enabled, flash firing should still occur (and that the test pattern remain unmodified, since the flash would not actually affect it).
Optional - This value may be null
on some devices.
Time at start of exposure of first row of the image sensor, in nanoseconds.
The timestamps are also included in all image buffers produced for the same capture, and will be identical on all the outputs. The timestamps measure time since an unspecified starting point, and are monotonically increasing.
They can be compared with the timestamps for other captures from the same camera device, but are not guaranteed to be comparable to any other time source.
Quality of lens shading correction applied to the image data.
When set to OFF mode, no lens shading correction will be applied by the
camera device, and an identity lens shading map data will be provided
if
. For example, for lens
shading map with size specified as android.statistics.lensShadingMapMode
== ONandroid.lens.info.shadingMapSize = [ 4, 3 ]
,
the output android.statistics.lensShadingMap for this case will be an identity map
shown below:
[ 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0,
1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0, 1.0 ]
When set to other modes, lens shading correction will be applied by the
camera device. Applications can request lens shading map data by setting
android.statistics.lensShadingMapMode
to ON, and then the camera device will provide
lens shading map data in android.statistics.lensShadingMap, with size specified
by android.lens.info.shadingMapSize; the returned shading map data will be the one
applied by the camera device for this capture request.
The shading map data may depend on the auto-exposure (AE) and AWB statistics, therefore the reliability
of the map data may be affected by the AE and AWB algorithms. When AE and AWB are in
AUTO modes(android.control.aeMode
!=
OFF and android.control.awbMode
!=
OFF),
to get best results, it is recommended that the applications wait for the AE and AWB to
be converged before using the returned shading map data.
List of the faces detected through camera face detection in this result.
Only available if android.statistics.faceDetectMode
!=
OFF.
Control for the face detector unit.
Whether face detection is enabled, and whether it
should output just the basic fields or the full set of
fields. Value must be one of the
android.statistics.info.availableFaceDetectModes
.
List of (x, y)
coordinates of hot/defective pixels on the sensor.
A coordinate (x, y)
must lie between (0, 0)
, and
(width - 1, height - 1)
(inclusive), which are the top-left and
bottom-right of the pixel array, respectively. The width and
height dimensions are given in android.sensor.info.pixelArraySize
.
This may include hot pixels that lie outside of the active array
bounds given by android.sensor.info.activeArraySize
.
Operating mode for hotpixel map generation.
If set to ON, a hotpixel map is returned in android.statistics.hotPixelMap
.
If set to OFF, no hotpixel map will be returned.
This must be set to a valid mode from android.statistics.info.availableHotPixelMapModes
.
The shading map is a low-resolution floating-point map that lists the coefficients used to correct for vignetting, for each Bayer color channel.
The least shaded section of the image should have a gain factor of 1; all other sections should have gains above 1.
When android.colorCorrection.mode
= TRANSFORM_MATRIX, the map
must take into account the colorCorrection settings.
The shading map is for the entire active pixel array, and is not affected by the crop region specified in the request. Each shading map entry is the value of the shading compensation map over a specific pixel on the sensor. Specifically, with a (N x M) resolution shading map, and an active pixel array size (W x H), shading map entry (x,y) ϵ (0 ... N-1, 0 ... M-1) is the value of the shading map at pixel ( ((W-1)/(N-1)) * x, ((H-1)/(M-1)) * y) for the four color channels. The map is assumed to be bilinearly interpolated between the sample points.
The channel order is [R, Geven, Godd, B], where Geven is the green channel for the even rows of a Bayer pattern, and Godd is the odd rows. The shading map is stored in a fully interleaved format.
The shading map should have on the order of 30-40 rows and columns, and must be smaller than 64x64.
As an example, given a very small map defined as:
width,height = [ 4, 3 ]
values =
[ 1.3, 1.2, 1.15, 1.2, 1.2, 1.2, 1.15, 1.2,
1.1, 1.2, 1.2, 1.2, 1.3, 1.2, 1.3, 1.3,
1.2, 1.2, 1.25, 1.1, 1.1, 1.1, 1.1, 1.0,
1.0, 1.0, 1.0, 1.0, 1.2, 1.3, 1.25, 1.2,
1.3, 1.2, 1.2, 1.3, 1.2, 1.15, 1.1, 1.2,
1.2, 1.1, 1.0, 1.2, 1.3, 1.15, 1.2, 1.3 ]
The low-resolution scaling map images for each channel are (displayed using nearest-neighbor interpolation):
As a visualization only, inverting the full-color map to recover an image of a gray wall (using bicubic interpolation for visual quality) as captured by the sensor gives:
Whether the camera device will output the lens shading map in output result metadata.
When set to ON, android.statistics.lensShadingMap will be provided in the output result metadata.
The camera device estimated scene illumination lighting frequency.
Many light sources, such as most fluorescent lights, flicker at a rate that depends on the local utility power standards. This flicker must be accounted for by auto-exposure routines to avoid artifacts in captured images. The camera device uses this entry to tell the application what the scene illuminant frequency is.
When manual exposure control is enabled
(
or android.control.aeMode
== OFF
), the android.control.mode
==
OFFandroid.control.aeAntibandingMode
doesn't perform
antibanding, and the application can ensure it selects
exposure times that do not cause banding issues by looking
into this metadata field. See
android.control.aeAntibandingMode
for more details.
Reports NONE if there doesn't appear to be flickering illumination.
Tonemapping / contrast / gamma curve to use when android.tonemap.mode
is CONTRAST_CURVE.
The tonemapCurve consist of three curves for each of red, green, and blue channels respectively. The following example uses the red channel as an example. The same logic applies to green and blue channel. Each channel's curve is defined by an array of control points:
curveRed =
[ P0(in, out), P1(in, out), P2(in, out), P3(in, out), ..., PN(in, out) ]
2 <= N <= android.tonemap.maxCurvePoints
These are sorted in order of increasing Pin
; it is always
guaranteed that input values 0.0 and 1.0 are included in the list to
define a complete mapping. For input values between control points,
the camera device must linearly interpolate between the control
points.
Each curve can have an independent number of points, and the number
of points can be less than max (that is, the request doesn't have to
always provide a curve with number of points equivalent to
android.tonemap.maxCurvePoints
).
A few examples, and their corresponding graphical mappings; these only specify the red channel and the precision is limited to 4 digits, for conciseness.
Linear mapping:
curveRed = [ (0, 0), (1.0, 1.0) ]
Invert mapping:
curveRed = [ (0, 1.0), (1.0, 0) ]
Gamma 1/2.2 mapping, with 16 control points:
curveRed = [
(0.0000, 0.0000), (0.0667, 0.2920), (0.1333, 0.4002), (0.2000, 0.4812),
(0.2667, 0.5484), (0.3333, 0.6069), (0.4000, 0.6594), (0.4667, 0.7072),
(0.5333, 0.7515), (0.6000, 0.7928), (0.6667, 0.8317), (0.7333, 0.8685),
(0.8000, 0.9035), (0.8667, 0.9370), (0.9333, 0.9691), (1.0000, 1.0000) ]
Standard sRGB gamma mapping, per IEC 61966-2-1:1999, with 16 control points:
curveRed = [
(0.0000, 0.0000), (0.0667, 0.2864), (0.1333, 0.4007), (0.2000, 0.4845),
(0.2667, 0.5532), (0.3333, 0.6125), (0.4000, 0.6652), (0.4667, 0.7130),
(0.5333, 0.7569), (0.6000, 0.7977), (0.6667, 0.8360), (0.7333, 0.8721),
(0.8000, 0.9063), (0.8667, 0.9389), (0.9333, 0.9701), (1.0000, 1.0000) ]
High-level global contrast/gamma/tonemapping control.
When switching to an application-defined contrast curve by setting
android.tonemap.mode
to CONTRAST_CURVE, the curve is defined
per-channel with a set of (in, out)
points that specify the
mapping from input high-bit-depth pixel value to the output
low-bit-depth value. Since the actual pixel ranges of both input
and output may change depending on the camera pipeline, the values
are specified by normalized floating-point numbers.
More-complex color mapping operations such as 3D color look-up
tables, selective chroma enhancement, or other non-linear color
transforms will be disabled when android.tonemap.mode
is
CONTRAST_CURVE.
This must be set to a valid mode in
android.tonemap.availableToneMapModes
.
When using either FAST or HIGH_QUALITY, the camera device will
emit its own tonemap curve in android.tonemap.curve
.
These values are always available, and as close as possible to the
actually used nonlinear/nonglobal transforms.
If a request is sent with CONTRAST_CURVE with the camera device's provided curve in FAST or HIGH_QUALITY, the image's tonemap will be roughly the same.
Get a capture result field value.
The field definitions can be found in CaptureResult
.
Querying the value for the same key more than once will return a value which is equal to the previous queried value.
key | The result field to read. |
---|
null
if the field is not set.
IllegalArgumentException | if the key was not valid |
---|
Get the frame number associated with this result.
Whenever a request has been processed, regardless of failure or success, it gets a unique frame number assigned to its future result/failure.
This value monotonically increments, starting with 0,
for every new result or failure; and the scope is the lifetime of the
CameraDevice
.
Returns a list of the keys contained in this map.
The list returned is not modifiable, so any attempts to modify it will throw
a UnsupportedOperationException
.
All values retrieved by a key from this list with #get
are guaranteed to be
non-null
. Each key is only listed once in the list. The order of the keys
is undefined.
Get the request associated with this result.
Whenever a request has been fully or partially captured, with
onCaptureCompleted(CameraDevice, CaptureRequest, TotalCaptureResult)
or
onCaptureProgressed(CameraDevice, CaptureRequest, CaptureResult)
, the result
's
getRequest()
will return that request
.
For example,
cameraDevice.capture(someRequest, new CaptureListener() {
@Override
void onCaptureCompleted(CaptureRequest myRequest, CaptureResult myResult) {
assert(myResult.getRequest.equals(myRequest) == true);
}
}, null);
null
.
The sequence ID for this failure that was returned by the
capture(CaptureRequest, CameraDevice.CaptureListener, Handler)
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 CameraDevice.