/*
* Copyright (c) 2016-2017, NVIDIA CORPORATION. All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in the
* documentation and/or other materials provided with the distribution.
* * Neither the name of NVIDIA CORPORATION nor the names of its
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS'' AND ANY
* EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
* OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/**
* @file
* Libargus Extension: Bayer Average Map API
*
* @b Description: This file defines the BayerAverageMap extension.
*/
#ifndef _ARGUS_EXT_BAYER_AVERAGE_MAP_H
#define _ARGUS_EXT_BAYER_AVERAGE_MAP_H
namespace Argus
{
/**
* Generates local averages of a capture's raw Bayer data. These averages are generated for
* a number of small rectangles, called bins, that are evenly distributed across the image.
* These averages may be calculated before optical clipping to the output bit depth occurs, thus
* the working range of this averaging may extend beyond the optical range of the output pixels;
* this allows the averages to remain steady while the sensor freely modifies its optical range.
*
* Any pixel values outside of the working range are clipped with respect to this averaging.
* Specifically, the API excludes them from the average calculation and increments
* the clipped pixel counter for the containing region.
* @see Ext::IBayerAverageMap::getClipCounts()
*
* This extension introduces two new interfaces:
* - Ext::IBayerAverageMapSettings enables average map generation in a capture Request.
* - Ext::IBayerAverageMap exposes the average map values from the CaptureMetadata.
*
* @defgroup ArgusExtBayerAverageMap Ext::BayerAverageMap
* @ingroup ArgusExtensions
*/
DEFINE_UUID(ExtensionName, EXT_BAYER_AVERAGE_MAP, 12c3de20,64c5,11e6,bdf4,08,00,20,0c,9a,66);
namespace Ext
{
/**
* @class IBayerAverageMapSettings
*
* Interface to Bayer average map settings.
*
* @ingroup ArgusRequest ArgusExtBayerAverageMap
*/
DEFINE_UUID(InterfaceID, IID_BAYER_AVERAGE_MAP_SETTINGS, 12c3de21,64c5,11e6,bdf4,08,00,20,0c,9a,66);
class IBayerAverageMapSettings : public Interface
{
public:
static const InterfaceID& id() { return IID_BAYER_AVERAGE_MAP_SETTINGS; }
/**
* Enables or disables Bayer average map generation. When enabled, CaptureMetadata
* returned by completed captures will expose the IBayerAverageMap interface.
*
* @param[in] enable whether or not Bayer average map generation is enabled.
*/
virtual void setBayerAverageMapEnable(bool enable) = 0;
/**
* @returns whether or not Bayer average map generation is enabled.
*/
virtual bool getBayerAverageMapEnable() const = 0;
protected:
~IBayerAverageMapSettings() {}
};
/**
* @class IBayerAverageMap
*
* Interface to Bayer average map metadata.
*
* The Bayer average map provides local averages of the capture's raw pixels for a number
* of small rectangular regions, called bins, that are evenly distributed across the image.
* Each average is a floating-point value that is nomalized such that [0.0, 1.0] maps to the
* full optical range of the output pixels, but values outside this range may be included in
* the averages so long as they are within the working range of the average calculation.
* For pixels that have values outside the working range, the API excludes such pixels from the
* average calculation and increments the clipped pixel counter for the containing region.
* @see IBayerAverageMap::getWorkingRange()
* @see IBayerAverageMap::getClipCounts()
*
* The size and layout of the bins used to calculate the averages are determined by the Argus
* implementation and are illustrated in the following diagram. The bin size and interval are
* constant across the image, and are positioned such that the generated averages cover the
* majority of the full image. All dimensions are given in pixels.
*
* @code
* start.x interval.width
* _______ _________________
* | | | |
* _ ________________________________________________________
* | | |
* start.y | | |
* |_ | _____ _____ _____ | _
* | | | | | | | | |
* | | 0,0 | | 1,0 | | 2,0 | | |
* | |_____| |_____| |_____| | |
* | | | interval.height
* | | |
* | | |
* | _____ _____ _____ | _|
* | | | | | | | |
* | | 0,1 | | 1,1 | | 2,1 | |
* | |_____| |_____| |_____| |
* | |
* | |
* | |
* | _____ _____ _____ | _
* | | | | | | | | |
* | | 0,2 | | 1,2 | | 2,2 | | | size.height
* | |_____| |_____| |_____| | _|
* | |
* | |
* |________________________________________________________|
*
* |_____|
*
* size.width
* @endcode
*
* @ingroup ArgusCaptureMetadata ArgusExtBayerAverageMap
*/
DEFINE_UUID(InterfaceID, IID_BAYER_AVERAGE_MAP, 12c3de22,64c5,11e6,bdf4,08,00,20,0c,9a,66);
class IBayerAverageMap : public Interface
{
public:
static const InterfaceID& id() { return IID_BAYER_AVERAGE_MAP; }
/**
* Returns the starting location of the first bin, in pixels, where the
* location is relative to the top-left corner of the image.
*/
virtual Point2D getBinStart() const = 0;
/**
* Returns the size of each bin, in pixels.
*/
virtual Size2D getBinSize() const = 0;
/**
* Returns the number of bins in both the horizontal (width) and vertical (height) directions.
* This size is equivalent to the array dimensions for the output from
* IBayerAverageMap::getAverages() or IBayerAverageMap::getClipCounts().
*/
virtual Size2D getBinCount() const = 0;
/**
* Returns the bin intervals for both the x and y axis. These intervals are defined as the
* number of pixels between the first pixel of a bin and that of the immediate next bin.
*/
virtual Size2D getBinInterval() const = 0;
/**
* Returns the working range of the averaging calculation. The working range is defined as
* the range of values that are included in the average calculation (e.g. not clipped),
* and may extend beyond the normalized [0.0, 1.0] range of the optical output. For example,
* if the working range is [-0.5, 1.5], this means that values in [-0.5, 0) and (1, 1.5] will
* still be included in the average calculation despite being clipped to [0.0, 1.0] in the
* output pixels. Any pixels outside this working range are excluded from average calculation
* and will increment the clip count.
* @see IBayerAverageMap::getClipCounts()
*
* @note When the bit depth available for averaging is equal to the optical bit depth of
* the output, the working range will be less than the full [0.0, 1.0] optical range. For
* example, when 10 bits of data are available, the raw output pixels in [0u, 1023u] will
* map to [0.0, 1.0]; however, the values of 0 and 1023 will be considered clipped for the
* sake of average calculation, and so the working range would be [1/1023.0, 1022/1023.0].
*/
virtual Range getWorkingRange() const = 0;
/**
* Returns the average values for all bins. These values are normalized such that
* [0.0, 1.0] maps to the optical range of the output, but the range of possible values
* is determined by the working range. For input pixels that have values outside the
* working range, the API excludes such pixels from the average calculation and
* increments the clipped pixel counter for the containing region.
* @see IBayerAverageMap::getWorkingRange()
* @see IBayerAverageMap::getClipCounts()
*
* @param[out] averages The output array to store the averages for all bins. This
* 2-dimensional array is sized as returned by IBayerAverageMap::getBinCount(),
* where each array element is a floating point BayerTuple containing the R,
* G_EVEN, G_ODD, and B averages for that bin.
*/
virtual Status getAverages(Array2D< BayerTuple >* averages) const = 0;
/**
* Returns the clipped pixel counts for all bins. This is the number of pixels in the bin
* whose value exceeds the working range and have been excluded from average calculation.
* @see IBayerAverageMap::getWorkingRange()
*
* @param[out] clipCounts The output array to store the clip counts for all bins. This
* 2-dimensional array is sized as returned by
* Ext::IBayerAverageMap::getBinCount(), where each array element is an uint32_t
* BayerTuple containing the R, G_EVEN, G_ODD, and B clip counts for that bin.
*/
virtual Status getClipCounts(Array2D< BayerTuple >* clipCounts) const = 0;
protected:
~IBayerAverageMap() {}
};
} // namespace Ext
} // namespace Argus
#endif // _ARGUS_EXT_BAYER_AVERAGE_MAP_H