237 lines
11 KiB
C++
237 lines
11 KiB
C++
/*
|
|
* 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
|
|
* <b>Libargus Extension: Bayer Average Map API</b>
|
|
*
|
|
* @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<uint32_t> getBinStart() const = 0;
|
|
|
|
/**
|
|
* Returns the size of each bin, in pixels.
|
|
*/
|
|
virtual Size2D<uint32_t> 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<uint32_t> 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<uint32_t> 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<float> 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<float> >* 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<uint32_t> >* clipCounts) const = 0;
|
|
|
|
protected:
|
|
~IBayerAverageMap() {}
|
|
};
|
|
|
|
} // namespace Ext
|
|
|
|
} // namespace Argus
|
|
|
|
#endif // _ARGUS_EXT_BAYER_AVERAGE_MAP_H
|