From 224eb3a4f1eaae067ce7dfedd3f7fb352132bb74 Mon Sep 17 00:00:00 2001 From: Ruben Brunk Date: Mon, 15 Jun 2015 17:32:06 -0700 Subject: Add metadata for pre-distortion dimensions. Bug: 20491394 Change-Id: I6b95a7fe2fd765571bcd2774aee486d18169a727 --- .../hardware/camera2/CameraCharacteristics.java | 110 +++++++++++++++++---- 1 file changed, 89 insertions(+), 21 deletions(-) (limited to 'core/java') diff --git a/core/java/android/hardware/camera2/CameraCharacteristics.java b/core/java/android/hardware/camera2/CameraCharacteristics.java index b69ca88..04510d9 100644 --- a/core/java/android/hardware/camera2/CameraCharacteristics.java +++ b/core/java/android/hardware/camera2/CameraCharacteristics.java @@ -1959,22 +1959,25 @@ public final class CameraCharacteristics extends CameraMetadata("android.scaler.croppingType", int.class); /** - *

The area of the image sensor which corresponds to - * active pixels.

- *

This is the region of the sensor that actually receives light from the scene. - * Therefore, the size of this region determines the maximum field of view and the maximum - * number of pixels that an image from this sensor can contain.

- *

The rectangle is defined in terms of 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 + *

The area of the image sensor which corresponds to active pixels after any geometric + * distortion correction has been applied.

+ *

This is the rectangle representing the size of the active region of the sensor (i.e. + * the region that actually receives light from the scene) after any geometric correction + * has been applied, and should be treated as the maximum size in pixels of any of the + * image output formats aside from the raw formats.

+ *

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 * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.

- *

Most other keys listing pixel coordinates have their coordinate systems based on the - * active array, with (0, 0) being the top-left of the active array rectangle.

+ *

The coordinate system for most other keys that list pixel coordinates, including + * {@link CaptureRequest#SCALER_CROP_REGION android.scaler.cropRegion}, is defined relative to the active array rectangle given in + * 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.

+ * include black calibration pixels or other inactive regions, and geometric correction + * resulting in scaling or cropping may have been applied.

*

Units: Pixel coordinates on the image sensor

- *

Range of valid values:

*

This key is available on all devices.

* + * @see CaptureRequest#SCALER_CROP_REGION * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE */ @PublicKey @@ -1982,6 +1985,69 @@ public final class CameraCharacteristics extends CameraMetadata("android.sensor.info.activeArraySize", android.graphics.Rect.class); /** + *

The area of the image sensor which corresponds to active pixels prior to the + * application of any geometric distortion correction.

+ *

This is the rectangle representing the size of the active region of the sensor (i.e. + * the region that actually receives light from the scene) before any geometric correction + * has been applied, and should be treated as the active region rectangle for any of the + * raw formats. All metadata associated with raw processing (e.g. the lens shading + * correction map, and radial distortion fields) treats the top, left of this rectangle as + * the origin, (0,0).

+ *

The size of this region determines the maximum field of view and the maximum number of + * pixels that an image from this sensor can contain, prior to the application of + * geometric distortion correction. The effective maximum pixel dimensions of a + * post-distortion-corrected image is given by the {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} + * field, and the effective maximum field of view for a post-distortion-corrected image + * can be calculated by applying the geometric distortion correction fields to this + * rectangle, and cropping to the rectangle given in {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.

+ *

E.g. to calculate position of a pixel, (x,y), in a processed YUV output image with the + * dimensions in {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} given the position of a pixel, + * (x', y'), in the raw pixel array with dimensions give in + * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}:

+ *
    + *
  1. Choose a pixel (x', y') within the active array region of the raw buffer given in + * android.sensor.info.preCorrectedActiveArraySize, otherwise this pixel is considered + * to be outside of the FOV, and will not be shown in the processed output image.
    2. + *
  2. Apply geometric distortion correction to get the post-distortion pixel coordinate, + * (x_i, y_i). When applying geometric correction metadata, note that metadata for raw + * buffers is defined relative to the top, left of the + * android.sensor.info.preCorrectedActiveArraySize rectangle.
    3. + *
  3. If the resulting corrected pixel coordinate is within the region given in + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}, then the position of this pixel in the + * processed output image buffer is (x_i - activeArray.left, y_i - activeArray.top), + * when the top, left coordinate of that buffer is treated as (0, 0).
    4. + *
+ *

Thus, for pixel x',y' = (25, 25) on a sensor where {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize} + * is (100,100), android.sensor.info.preCorrectedActiveArraySize is (10, 10, 100, 100), + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} is (20, 20, 80, 80), and the geometric distortion + * correction doesn't change the pixel coordinate, the resulting pixel selected in + * pixel coordinates would be x,y = (25, 25) relative to the top,left of the raw buffer + * with dimensions given in {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}, and would be (5, 5) + * relative to the top,left of post-processed YUV output buffer with dimensions given in + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize}.

+ *

The currently supported fields that correct for geometric distortion are:

+ *
    + *
  1. android.lens.radialDistortion.
    2. + *
+ *

If all of the geometric distortion fields are no-ops, this rectangle will be the same + * as the post-distortion-corrected rectangle given in + * {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE 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 + * {@link CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE android.sensor.info.pixelArraySize}.

+ *

The pre-correction active array may be smaller than the full pixel array, since the + * full array may include black calibration pixels or other inactive regions.

+ *

Units: Pixel coordinates on the image sensor

+ *

This key is available on all devices.

+ * + * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PIXEL_ARRAY_SIZE + */ + @PublicKey + public static final Key SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE = + new Key("android.sensor.info.preCorrectionActiveArraySize", android.graphics.Rect.class); + + /** *

Range of sensitivities for {@link CaptureRequest#SENSOR_SENSITIVITY android.sensor.sensitivity} supported by this * camera device.

*

The values are the standard ISO sensitivity values, @@ -2089,22 +2155,24 @@ public final class CameraCharacteristics extends CameraMetadataDimensions of the full pixel array, possibly * including black calibration pixels.

- *

The pixel count of the full pixel array, - * which covers {@link CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE android.sensor.info.physicalSize} area.

- *

If a camera device supports raw sensor formats, either this - * or {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} is the maximum output - * raw size listed in {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap}. - * If a size corresponding to pixelArraySize is listed, the resulting - * raw sensor image will include black pixels.

+ *

The pixel count of the full pixel array of the image sensor, which covers + * {@link CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE android.sensor.info.physicalSize} area. This represents the full pixel dimensions of + * the raw buffers produced by this sensor.

+ *

If a camera device supports raw sensor formats, either this or + * {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} is the maximum dimensions for the raw + * output formats listed in {@link CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP android.scaler.streamConfigurationMap} (this depends on + * whether or not the image sensor returns buffers containing pixels that are not + * part of the active array region for blacklevel calibration or other purposes).

*

Some parts of the full pixel array may not receive light from the scene, - * or are otherwise inactive. The {@link CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE android.sensor.info.activeArraySize} key - * defines the rectangle of active pixels that actually forms an image.

+ * or be otherwise inactive. The {@link CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE android.sensor.info.preCorrectionActiveArraySize} key + * defines the rectangle of active pixels that will be included in processed image + * formats.

*

Units: Pixels

*

This key is available on all devices.

* * @see CameraCharacteristics#SCALER_STREAM_CONFIGURATION_MAP - * @see CameraCharacteristics#SENSOR_INFO_ACTIVE_ARRAY_SIZE * @see CameraCharacteristics#SENSOR_INFO_PHYSICAL_SIZE + * @see CameraCharacteristics#SENSOR_INFO_PRE_CORRECTION_ACTIVE_ARRAY_SIZE */ @PublicKey public static final Key SENSOR_INFO_PIXEL_ARRAY_SIZE = -- cgit v1.1