summaryrefslogtreecommitdiffstats
path: root/camera/docs/metadata_definitions.xml
diff options
context:
space:
mode:
Diffstat (limited to 'camera/docs/metadata_definitions.xml')
-rw-r--r--camera/docs/metadata_definitions.xml373
1 files changed, 283 insertions, 90 deletions
diff --git a/camera/docs/metadata_definitions.xml b/camera/docs/metadata_definitions.xml
index 6059fa0..ec3835d 100644
--- a/camera/docs/metadata_definitions.xml
+++ b/camera/docs/metadata_definitions.xml
@@ -686,9 +686,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
<size>area_count</size>
</array>
<description>List of metering areas to use for auto-exposure adjustment.</description>
- <units>Pixel coordinates within android.sensor.info.activeArraySize</units>
+ <units>Pixel coordinates within android.sensor.info.activeArraySize or
+ android.sensor.info.preCorrectionActiveArraySize depending on
+ distortion correction capability and mode</units>
<range>Coordinates must be between `[(0,0), (width, height))` of
- android.sensor.info.activeArraySize</range>
+ android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize
+ depending on distortion correction capability and mode</range>
<details>
Not available if android.control.maxRegionsAe is 0.
Otherwise will always be present.
@@ -696,11 +699,27 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
The maximum number of regions supported by the device is determined by the value
of android.control.maxRegionsAe.
- The coordinate system is based on the active pixel array,
- with (0,0) being the top-left pixel in the active pixel array, and
+ For devices not supporting android.distortionCorrection.mode control, the coordinate
+ system always follows that of android.sensor.info.activeArraySize, 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.
+ android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the
+ active pixel array.
+
+ For devices supporting android.distortionCorrection.mode control, the coordinate
+ system depends on the mode being set.
+ When the distortion correction mode is OFF, the coordinate system follows
+ android.sensor.info.preCorrectionActiveArraySize, with
+ `(0, 0)` being the top-left pixel of the pre-correction active array, and
+ (android.sensor.info.preCorrectionActiveArraySize.width - 1,
+ android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right
+ pixel in the pre-correction active pixel array.
+ When the distortion correction mode is not OFF, the coordinate system follows
+ android.sensor.info.activeArraySize, with
+ `(0, 0)` being the top-left pixel of the active 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 be within `[0, 1000]`, and represents a weight
for every pixel in the area. This means that a large metering area
@@ -734,6 +753,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
(xmin, ymin, xmax, ymax, weight).
The rectangle is defined to be inclusive on xmin and ymin, but
exclusive on xmax and ymax.
+ HAL must always report metering regions in the coordinate system of pre-correction
+ active array.
</hal_details>
<tag id="BC" />
</entry>
@@ -969,9 +990,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
<size>area_count</size>
</array>
<description>List of metering areas to use for auto-focus.</description>
- <units>Pixel coordinates within android.sensor.info.activeArraySize</units>
+ <units>Pixel coordinates within android.sensor.info.activeArraySize or
+ android.sensor.info.preCorrectionActiveArraySize depending on
+ distortion correction capability and mode</units>
<range>Coordinates must be between `[(0,0), (width, height))` of
- android.sensor.info.activeArraySize</range>
+ android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize
+ depending on distortion correction capability and mode</range>
<details>
Not available if android.control.maxRegionsAf is 0.
Otherwise will always be present.
@@ -979,11 +1003,28 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
The maximum number of focus areas supported by the device is determined by the value
of android.control.maxRegionsAf.
- The coordinate system is based on the active pixel array,
- with (0,0) being the top-left pixel in the active pixel array, and
+
+ For devices not supporting android.distortionCorrection.mode control, the coordinate
+ system always follows that of android.sensor.info.activeArraySize, 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.
+
+ For devices supporting android.distortionCorrection.mode control, the coordinate
+ system depends on the mode being set.
+ When the distortion correction mode is OFF, the coordinate system follows
+ android.sensor.info.preCorrectionActiveArraySize, with
+ `(0, 0)` being the top-left pixel of the pre-correction active array, and
+ (android.sensor.info.preCorrectionActiveArraySize.width - 1,
+ android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right
+ pixel in the pre-correction active pixel array.
+ When the distortion correction mode is not OFF, the coordinate system follows
+ android.sensor.info.activeArraySize, with
+ `(0, 0)` being the top-left pixel of the active array, and
(android.sensor.info.activeArraySize.width - 1,
- android.sensor.info.activeArraySize.height - 1) being the
- bottom-right pixel in the active pixel array.
+ android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the
+ active pixel array.
The weight must be within `[0, 1000]`, and represents a weight
for every pixel in the area. This means that a large metering area
@@ -1018,6 +1059,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
(xmin, ymin, xmax, ymax, weight).
The rectangle is defined to be inclusive on xmin and ymin, but
exclusive on xmax and ymax.
+ HAL must always report metering regions in the coordinate system of pre-correction
+ active array.
</hal_details>
<tag id="BC" />
</entry>
@@ -1279,9 +1322,12 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
</array>
<description>List of metering areas to use for auto-white-balance illuminant
estimation.</description>
- <units>Pixel coordinates within android.sensor.info.activeArraySize</units>
+ <units>Pixel coordinates within android.sensor.info.activeArraySize or
+ android.sensor.info.preCorrectionActiveArraySize depending on
+ distortion correction capability and mode</units>
<range>Coordinates must be between `[(0,0), (width, height))` of
- android.sensor.info.activeArraySize</range>
+ android.sensor.info.activeArraySize or android.sensor.info.preCorrectionActiveArraySize
+ depending on distortion correction capability and mode</range>
<details>
Not available if android.control.maxRegionsAwb is 0.
Otherwise will always be present.
@@ -1289,11 +1335,27 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
The maximum number of regions supported by the device is determined by the value
of android.control.maxRegionsAwb.
- The coordinate system is based on the active pixel array,
- with (0,0) being the top-left pixel in the active pixel array, and
+ For devices not supporting android.distortionCorrection.mode control, the coordinate
+ system always follows that of android.sensor.info.activeArraySize, 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.
+ android.sensor.info.activeArraySize.height - 1) being the bottom-right pixel in the
+ active pixel array.
+
+ For devices supporting android.distortionCorrection.mode control, the coordinate
+ system depends on the mode being set.
+ When the distortion correction mode is OFF, the coordinate system follows
+ android.sensor.info.preCorrectionActiveArraySize, with
+ `(0, 0)` being the top-left pixel of the pre-correction active array, and
+ (android.sensor.info.preCorrectionActiveArraySize.width - 1,
+ android.sensor.info.preCorrectionActiveArraySize.height - 1) being the bottom-right
+ pixel in the pre-correction active pixel array.
+ When the distortion correction mode is not OFF, the coordinate system follows
+ android.sensor.info.activeArraySize, with
+ `(0, 0)` being the top-left pixel of the active 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
@@ -1327,6 +1389,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
(xmin, ymin, xmax, ymax, weight).
The rectangle is defined to be inclusive on xmin and ymin, but
exclusive on xmax and ymax.
+ HAL must always report metering regions in the coordinate system of pre-correction
+ active array.
</hal_details>
<tag id="BC" />
</entry>
@@ -3410,9 +3474,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
</details>
<hal_details>
The HAL must not squeeze or stretch the downscaled primary image to generate thumbnail.
- The cropping must be done on the primary jpeg image rather than the sensor active array.
- The stream cropping rule specified by "S5. Cropping" in camera3.h doesn't apply to the
- thumbnail image cropping.
+ The cropping must be done on the primary jpeg image rather than the sensor pre-correction
+ active array. The stream cropping rule specified by "S5. Cropping" in camera3.h doesn't
+ apply to the thumbnail image cropping.
</hal_details>
<tag id="BC" />
</entry>
@@ -3896,7 +3960,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
If this device is the largest or only camera device with a given facing, then this
position will be `(0, 0, 0)`; a camera device with a lens optical center located 3 cm
from the main sensor along the +X axis (to the right from the user's perspective) will
- report `(0.03, 0, 0)`.
+ report `(0.03, 0, 0)`. Note that this means that, for many computer vision
+ applications, the position needs to be negated to convert it to a translation from the
+ camera to the origin.
To transform a pixel coordinates between two cameras facing the same direction, first
the source camera android.lens.distortion must be corrected for. Then the source
@@ -3911,7 +3977,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
image then needs to be corrected for radial distortion before comparison or sampling.
When android.lens.poseReference is GYROSCOPE, then this position is relative to
- the center of the primary gyroscope on the device.
+ the center of the primary gyroscope on the device. The axis definitions are the same as
+ with PRIMARY_CAMERA.
</details>
<tag id="DEPTH" />
</entry>
@@ -4032,14 +4099,17 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
which can then be combined with the camera pose rotation
`R` and translation `t` (android.lens.poseRotation and
- android.lens.poseTranslation, respective) to calculate the
+ android.lens.poseTranslation, respectively) to calculate the
complete transform from world coordinates to pixel
coordinates:
- P = [ K 0 * [ R t
- 0 1 ] 0 1 ]
+ P = [ K 0 * [ R -Rt
+ 0 1 ] 0 1 ]
+
+ (Note the negation of poseTranslation when mapping from camera
+ to world coordinates, and multiplication by the rotation).
- and with `p_w` being a point in the world coordinate system
+ With `p_w` being a point in the world coordinate system
and `p_s` being a point in the camera active pixel array
coordinate system, and with the mapping including the
homogeneous division by z:
@@ -4063,6 +4133,14 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
activeArraySize rectangle), to determine the final pixel
coordinate of the world point for processed (non-RAW)
output buffers.
+
+ For camera devices, the center of pixel `(x,y)` is located at
+ coordinate `(x + 0.5, y + 0.5)`. So on a device with a
+ precorrection active array of size `(10,10)`, the valid pixel
+ indices go from `(0,0)-(9,9)`, and an perfectly-built camera would
+ have an optical center at the exact center of the pixel grid, at
+ coordinates `(5.0, 5.0)`, which is the top-left corner of pixel
+ `(5,5)`.
</details>
<tag id="DEPTH" />
</entry>
@@ -5217,10 +5295,11 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
This capability requires the camera device to support the following:
- * This camera device must list the following static metadata entries in {@link
- android.hardware.camera2.CameraCharacteristics}:
- - android.logicalMultiCamera.physicalIds
- - android.logicalMultiCamera.sensorSyncType
+ * The IDs of underlying physical cameras are returned via
+ {@link android.hardware.camera2.CameraCharacteristics#getPhysicalCameraIds}.
+ * This camera device must list static metadata
+ android.logicalMultiCamera.sensorSyncType in
+ {@link android.hardware.camera2.CameraCharacteristics}.
* The underlying physical cameras' static metadata must list the following entries,
so that the application can correlate pixels from the physical streams:
- android.lens.poseReference
@@ -5577,13 +5656,24 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
</array>
<description>The desired region of the sensor to read out for this capture.</description>
<units>Pixel coordinates relative to
- android.sensor.info.activeArraySize</units>
+ android.sensor.info.activeArraySize or
+ android.sensor.info.preCorrectionActiveArraySize depending on distortion correction
+ capability and mode</units>
<details>
This control can be used to implement digital zoom.
- 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.
+ For devices not supporting android.distortionCorrection.mode control, the coordinate
+ system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being
+ the top-left pixel of the active array.
+
+ For devices supporting android.distortionCorrection.mode control, the coordinate
+ system depends on the mode being set.
+ When the distortion correction mode is OFF, the coordinate system follows
+ android.sensor.info.preCorrectionActiveArraySize, with
+ `(0, 0)` being the top-left pixel of the pre-correction active array.
+ When the distortion correction mode is not OFF, the coordinate system follows
+ android.sensor.info.activeArraySize, with
+ `(0, 0)` being the top-left pixel of the active array.
Output streams use this rectangle to produce their output,
cropping to a smaller region if necessary to maintain the
@@ -5608,11 +5698,18 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
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
+ If the coordinate system is android.sensor.info.activeArraySize, the width and height
+ of the crop region cannot be set to be smaller than
`floor( activeArraySize.width / android.scaler.availableMaxDigitalZoom )` and
`floor( activeArraySize.height / android.scaler.availableMaxDigitalZoom )`, respectively.
+ If the coordinate system is android.sensor.info.preCorrectionActiveArraySize, the width
+ and height of the crop region cannot be set to be smaller than
+ `floor( preCorrectionActiveArraySize.width / android.scaler.availableMaxDigitalZoom )`
+ and
+ `floor( preCorrectionActiveArraySize.height / android.scaler.availableMaxDigitalZoom )`,
+ respectively.
+
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
@@ -5632,30 +5729,31 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
possible.
For a set of output streams configured, if the sensor output is cropped to a smaller
- size than active array size, the HAL need follow below cropping rules:
+ size than pre-correction active array size, the HAL need follow below cropping rules:
- * The HAL need handle the cropRegion as if the sensor crop size is the effective active
- array size.More specifically, the HAL must transform the request cropRegion from
- android.sensor.info.activeArraySize to the sensor cropped pixel area size in this way:
+ * The HAL need handle the cropRegion as if the sensor crop size is the effective
+ pre-correction active array size. More specifically, the HAL must transform the request
+ cropRegion from android.sensor.info.preCorrectionActiveArraySize to the sensor cropped
+ pixel area size in this way:
1. Translate the requested cropRegion w.r.t., the left top corner of the sensor
cropped pixel area by (tx, ty),
- where `ty = sensorCrop.top * (sensorCrop.height / activeArraySize.height)`
- and `tx = sensorCrop.left * (sensorCrop.width / activeArraySize.width)`. The
- (sensorCrop.top, sensorCrop.left) is the coordinate based off the
+ where `ty = sensorCrop.top * (sensorCrop.height / preCorrectionActiveArraySize.height)`
+ and `tx = sensorCrop.left * (sensorCrop.width / preCorrectionActiveArraySize.width)`.
+ The (sensorCrop.top, sensorCrop.left) is the coordinate based off the
android.sensor.info.activeArraySize.
2. Scale the width and height of requested cropRegion with scaling factor of
- sensorCrop.width/activeArraySize.width and sensorCrop.height/activeArraySize.height
+ sensorCrop.width/preCorrectionActiveArraySize.width and sensorCrop.height/preCorrectionActiveArraySize.height
respectively.
Once this new cropRegion is calculated, the HAL must use this region to crop the image
- with regard to the sensor crop size (effective active array size). The HAL still need
- follow the general cropping rule for this new cropRegion and effective active
- array size.
+ with regard to the sensor crop size (effective pre-correction active array size). The
+ HAL still need follow the general cropping rule for this new cropRegion and effective
+ pre-correction active array size.
- * The HAL must report the cropRegion with regard to android.sensor.info.activeArraySize.
- The HAL need convert the new cropRegion generated above w.r.t., full active array size.
- The reported cropRegion may be slightly different with the requested cropRegion since
- the HAL may adjust the crop region to account for rounding, conversion error, or other
- hardware limitations.
+ * The HAL must report the cropRegion with regard to android.sensor.info.preCorrectionActiveArraySize.
+ The HAL need convert the new cropRegion generated above w.r.t., full pre-correction
+ active array size. The reported cropRegion may be slightly different with the requested
+ cropRegion since the HAL may adjust the crop region to account for rounding, conversion
+ error, or other hardware limitations.
HAL2.x uses only (x, y, width)
</hal_details>
@@ -6517,8 +6615,21 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
this field, with `(0, 0)` being the top-left of this rectangle.
The active array may be smaller than the full pixel array, since the full array may
- include black calibration pixels or other inactive regions, and geometric correction
- resulting in scaling or cropping may have been applied.
+ include black calibration pixels or other inactive regions.
+
+ For devices that do not support android.distortionCorrection.mode control, the active
+ array must be the same as android.sensor.info.preCorrectionActiveArraySize.
+
+ For devices that support android.distortionCorrection.mode control, the active array must
+ be enclosed by android.sensor.info.preCorrectionActiveArraySize. The difference between
+ pre-correction active array and active array accounts for scaling or cropping caused
+ by lens geometric distortion correction.
+
+ In general, application should always refer to active array size for controls like
+ metering regions or crop region. Two exceptions are when the application is dealing with
+ RAW image buffers (RAW_SENSOR, RAW10, RAW12 etc), or when application explicitly set
+ android.distortionCorrection.mode to OFF. In these cases, application should refer
+ to android.sensor.info.preCorrectionActiveArraySize.
</details>
<ndk_details>
The data representation is `int[4]`, which maps to `(left, top, width, height)`.
@@ -6810,9 +6921,9 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
1. android.lens.distortion.
- If all of the geometric distortion fields are no-ops, this rectangle will be the same
- as the post-distortion-corrected rectangle given in
- android.sensor.info.activeArraySize.
+ If the camera device doesn't support geometric distortion correction, or all of the
+ geometric distortion fields are no-ops, this rectangle will be the same as the
+ post-distortion-corrected rectangle given in android.sensor.info.activeArraySize.
This rectangle is defined relative to the full pixel array; (0,0) is the top-left of
the full pixel array, and the size of the full pixel array is given by
@@ -8063,10 +8174,24 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
<description>List of landmarks for detected
faces.</description>
<details>
- The coordinate system is that of android.sensor.info.activeArraySize, with
+ For devices not supporting android.distortionCorrection.mode control, the coordinate
+ system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being
+ the top-left pixel of the active array.
+
+ For devices supporting android.distortionCorrection.mode control, the coordinate
+ system depends on the mode being set.
+ When the distortion correction mode is OFF, the coordinate system follows
+ android.sensor.info.preCorrectionActiveArraySize, with
+ `(0, 0)` being the top-left pixel of the pre-correction active array.
+ When the distortion correction mode is not OFF, the coordinate system follows
+ android.sensor.info.activeArraySize, with
`(0, 0)` being the top-left pixel of the active array.
Only available if android.statistics.faceDetectMode == FULL</details>
+ <hal_details>
+ HAL must always report face landmarks in the coordinate system of pre-correction
+ active array.
+ </hal_details>
<tag id="BC" />
</entry>
<entry name="faceRectangles" type="int32" visibility="ndk_public"
@@ -8079,13 +8204,27 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
<description>List of the bounding rectangles for detected
faces.</description>
<details>
- The coordinate system is that of android.sensor.info.activeArraySize, with
+ For devices not supporting android.distortionCorrection.mode control, the coordinate
+ system always follows that of android.sensor.info.activeArraySize, with `(0, 0)` being
+ the top-left pixel of the active array.
+
+ For devices supporting android.distortionCorrection.mode control, the coordinate
+ system depends on the mode being set.
+ When the distortion correction mode is OFF, the coordinate system follows
+ android.sensor.info.preCorrectionActiveArraySize, with
+ `(0, 0)` being the top-left pixel of the pre-correction active array.
+ When the distortion correction mode is not OFF, the coordinate system follows
+ android.sensor.info.activeArraySize, with
`(0, 0)` being the top-left pixel of the active array.
Only available if android.statistics.faceDetectMode != OFF</details>
<ndk_details>
- The data representation is `int[4]`, which maps to `(left, top, width, height)`.
+ The data representation is `int[4]`, which maps to `(left, top, right, bottom)`.
</ndk_details>
+ <hal_details>
+ HAL must always report face rectangles in the coordinate system of pre-correction
+ active array.
+ </hal_details>
<tag id="BC" />
</entry>
<entry name="faceScores" type="byte" visibility="ndk_public"
@@ -8485,9 +8624,17 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
</ndk_notes>
</value>
</enum>
- <description>A control for selecting whether OIS position information is included in output
- result metadata.</description>
+ <description>A control for selecting whether optical stabilization (OIS) position
+ information is included in output result metadata.</description>
<range>android.statistics.info.availableOisDataModes</range>
+ <details>
+ Since optical image stabilization generally involves motion much faster than the duration
+ of individualq image exposure, multiple OIS samples can be included for a single capture
+ result. For example, if the OIS reporting operates at 200 Hz, a typical camera operating
+ at 30fps may have 6-7 OIS samples per capture result. This information can be combined
+ with the rolling shutter skew to account for lens motion during image exposure in
+ post-processing algorithms.
+ </details>
</entry>
</controls>
<dynamic>
@@ -8516,12 +8663,17 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
<units>Pixels in active array.</units>
<details>
The array contains the amount of shifts in x direction, in pixels, based on OIS samples.
- A positive value is a shift from left to right in active array coordinate system. For
- example, if the optical center is (1000, 500) in active array coordinates, a shift of
- (3, 0) puts the new optical center at (1003, 500).
+ A positive value is a shift from left to right in the pre-correction active array
+ coordinate system. For example, if the optical center is (1000, 500) in pre-correction
+ active array coordinates, a shift of (3, 0) puts the new optical center at (1003, 500).
The number of shifts must match the number of timestamps in
android.statistics.oisTimestamps.
+
+ The OIS samples are not affected by whether lens distortion correction is enabled (on
+ supporting devices). They are always reported in pre-correction active array coordinates,
+ since the scaling of OIS shifts would depend on the specific spot on the sensor the shift
+ is needed.
</details>
</entry>
<entry name="oisYShifts" type="float" visibility="ndk_public" container="array" hal_version="3.3">
@@ -8534,12 +8686,17 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
<units>Pixels in active array.</units>
<details>
The array contains the amount of shifts in y direction, in pixels, based on OIS samples.
- A positive value is a shift from top to bottom in active array coordinate system. For
- example, if the optical center is (1000, 500) in active array coordinates, a shift of
- (0, 5) puts the new optical center at (1000, 505).
+ A positive value is a shift from top to bottom in pre-correction active array coordinate
+ system. For example, if the optical center is (1000, 500) in active array coordinates, a
+ shift of (0, 5) puts the new optical center at (1000, 505).
The number of shifts must match the number of timestamps in
android.statistics.oisTimestamps.
+
+ The OIS samples are not affected by whether lens distortion correction is enabled (on
+ supporting devices). They are always reported in pre-correction active array coordinates,
+ since the scaling of OIS shifts would depend on the specific spot on the sensor the shift
+ is needed.
</details>
</entry>
<entry name="oisSamples" type="float" visibility="java_public" synthetic="true"
@@ -8548,19 +8705,26 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
<size>n</size>
</array>
<description>
- An array of OIS samples.
+ An array of optical stabilization (OIS) position samples.
</description>
<details>
Each OIS sample contains the timestamp and the amount of shifts in x and y direction,
in pixels, of the OIS sample.
- A positive value for a shift in x direction is a shift from left to right in active array
- coordinate system. For example, if the optical center is (1000, 500) in active array
- coordinates, a shift of (3, 0) puts the new optical center at (1003, 500).
+ A positive value for a shift in x direction is a shift from left to right in the
+ pre-correction active array coordinate system. For example, if the optical center is
+ (1000, 500) in pre-correction active array coordinates, a shift of (3, 0) puts the new
+ optical center at (1003, 500).
- A positive value for a shift in y direction is a shift from top to bottom in active array
- coordinate system. For example, if the optical center is (1000, 500) in active array
- coordinates, a shift of (0, 5) puts the new optical center at (1000, 505).
+ A positive value for a shift in y direction is a shift from top to bottom in
+ pre-correction active array coordinate system. For example, if the optical center is
+ (1000, 500) in active array coordinates, a shift of (0, 5) puts the new optical center at
+ (1000, 505).
+
+ The OIS samples are not affected by whether lens distortion correction is enabled (on
+ supporting devices). They are always reported in pre-correction active array coordinates,
+ since the scaling of OIS shifts would depend on the specific spot on the sensor the shift
+ is needed.
</details>
</entry>
</dynamic>
@@ -9110,12 +9274,26 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
// Returns true if the device supports the required hardware level, or better.
boolean isHardwareLevelSupported(CameraCharacteristics c, int requiredLevel) {
+ final int[] sortedHwLevels = {
+ CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY,
+ CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_EXTERNAL,
+ CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LIMITED,
+ CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_FULL,
+ CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_3
+ };
int deviceLevel = c.get(CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL);
- if (deviceLevel == CameraCharacteristics.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY) {
- return requiredLevel == deviceLevel;
+ if (requiredLevel == deviceLevel) {
+ return true;
+ }
+
+ for (int sortedlevel : sortedHwLevels) {
+ if (sortedlevel == requiredLevel) {
+ return true;
+ } else if (sortedlevel == deviceLevel) {
+ return false;
+ }
}
- // deviceLevel is not LEGACY, can use numerical sort
- return requiredLevel &lt;= deviceLevel;
+ return false; // Should never reach here
}
At a high level, the levels are:
@@ -9129,6 +9307,8 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
post-processing settings, and image capture at a high rate.
* `LEVEL_3` devices additionally support YUV reprocessing and RAW image capture, along
with additional output stream configurations.
+ * `EXTERNAL` devices are similar to `LIMITED` devices with exceptions like some sensor or
+ lens information not reorted or less stable framerates.
See the individual level enums for full descriptions of the supported capabilities. The
android.request.availableCapabilities entry describes the device's capabilities at a
@@ -9740,16 +9920,29 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata
similar amount of enhancement applied.
The correction only applies to processed outputs such as YUV, JPEG, or DEPTH16; it is not
- applied to any RAW output. Metadata coordinates such as face rectangles or metering
- regions are also not affected by correction.
-
- Applications enabling distortion correction need to pay extra attention when converting
- image coordinates between corrected output buffers and the sensor array. For example, if
- the app supports tap-to-focus and enables correction, it then has to apply the distortion
- model described in android.lens.distortion to the image buffer tap coordinates to properly
- calculate the tap position on the sensor active array to be used with
- android.control.afRegions. The same applies in reverse to detected face rectangles if
- they need to be drawn on top of the corrected output buffers.
+ applied to any RAW output.
+
+ This control will be on by default on devices that support this control. Applications
+ disabling distortion correction need to pay extra attention with the coordinate system of
+ metering regions, crop region, and face rectangles. When distortion correction is OFF,
+ metadata coordinates follow the coordinate system of
+ android.sensor.info.preCorrectionActiveArraySize. When distortion is not OFF, metadata
+ coordinates follow the coordinate system of android.sensor.info.activeArraySize. The
+ camera device will map these metadata fields to match the corrected image produced by the
+ camera device, for both capture requests and results. However, this mapping is not very
+ precise, since rectangles do not generally map to rectangles when corrected. Only linear
+ scaling between the active array and precorrection active array coordinates is
+ performed. Applications that require precise correction of metadata need to undo that
+ linear scaling, and apply a more complete correction that takes into the account the app's
+ own requirements.
+
+ The full list of metadata that is affected in this way by distortion correction is:
+
+ * android.control.afRegions
+ * android.control.aeRegions
+ * android.control.awbRegions
+ * android.scaler.cropRegion
+ * android.statistics.faces
</details>
</entry>
</controls>