Histogram

Creates a histogram for a given peak_frame. More...

Data Structures
struct	peak_histogram_channel_info
	peak histogram channel info More...

Typedefs
typedef struct peak_histogram *	peak_histogram_handle
	The handle type for a histogram.

Functions
peak_status	peak_IPL_Histogram_ProcessFrame (peak_frame_handle hFrame, peak_histogram_handle *hHistogram)
	Calculates the histogram for the given peak_frame_handle.
peak_status	peak_IPL_Histogram_Release (peak_histogram_handle hHistogram)
	Releases the histogram after use.
peak_status	peak_IPL_Histogram_Channel_GetCount (peak_histogram_handle hHistogram, size_t *numChannels)
	Get the number of channels in the histogram.
peak_status	peak_IPL_Histogram_Channel_GetInfo (peak_histogram_handle hHistogram, size_t channel, peak_histogram_channel_info *channelInfo)
	Get the channel info for a channel in the histogram.
peak_status	peak_IPL_Histogram_Channel_GetBinArray (peak_histogram_handle hHistogram, size_t channel, uint64_t *binArray, size_t *binArraySize)
	Get the bin array for a channel in the histogram.

Detailed Description

Creates a histogram for a given peak_frame.

The histogram represents the distribution of values of an image. The algorithm sorts the pixels to bins according to their pixel value. The bin index is the range of values, that each pixel can hold. This range depends on the bit depth, e.g. for 8 bit it is 0...255, for 10 bit 0...1024 and so on. The value of each bin refers to the number of pixels that hold this value in the image. For color images, where each pixel has three color values, the histogram shows three separate data series for each color channel. Histograms for RAW images can either be handled as a single channel or they first have to be debayered to create the three channels.

Example to use the histogram feature:

peak_histogram_handle histo_handle = PEAK_INVALID_HANDLE;
size_t channelCount = 0;
peak_status status = peak_IPL_Histogram_ProcessFrame(hFrame, &histo_handle);
if (PEAK_ERROR(status))
{
    // handle error
}
 
status = peak_IPL_Histogram_Channel_GetCount(histo_handle, &channelCount);
if (PEAK_ERROR(status))
{
    // handle error
}
 
for (size_t i = 0; i < channelCount; i++)
{
    peak_histogram_channel_info info = { 0 };
 
    status = peak_IPL_Histogram_Channel_GetInfo(histo_handle, i, &info);
    if (PEAK_ERROR(status))
    {
        // handle error
        continue;
    }
 
    uint64_t* array = (uint64_t*)malloc(info.binSize * sizeof(uint64_t));
 
    status = peak_IPL_Histogram_Channel_GetBinArray(histo_handle, i, array, &info.binSize);
    if (PEAK_ERROR(status))
    {
        free(array);
 
        // handle error
        continue;
    }
 
    for (size_t j = 0; j < info.binSize; j++)
    {
        // do something with bin
    }
 
    free(array);
}

Function Documentation

peak_IPL_Histogram_Channel_GetBinArray()

peak_status peak_IPL_Histogram_Channel_GetBinArray	(	peak_histogram_handle	hHistogram,
		size_t	channel,
		uint64_t *	binArray,
		size_t *	binArraySize )

Get the bin array for a channel in the histogram.

The histogram bin array represents the distribution of values of an image. Depending on the bit depth the array size varies, e.g. for 8 bit it is 0...255, for 10 bit 0...1024 and so on. The index represents the pixel value found and the value for a given index refers to the number of pixels that hold this value.

Example: Given an 1 Bit image of [0, 1, 1, 1] the histogram is of size 2 (2^numBits) with the values [1, 3].

This function implements the Two Staged Data Query principle.

Parameters

[in]	hHistogram	The handle to the histogram.
[in]	channel	The number of the channel to retrieve the bin array for.
[out]	binArray	Pointer to a user allocated array buffer to receive the bin array of the channel. If this parameter is NULL, binArraySize will contain the size of the bin array. The required size of binArray in bytes is binArraySize x sizeof(uint64_t).
[in,out]	binArraySize	binArray equal NULL: out: minimal size binArray must be to hold the bin array in size of uint64_t binArray unequal NULL: in: size of binArray in counts of uint64_t. In bytes this is `SizeInBytes / sizeof(uint64_t) out: filled number of uint64_t in binArray

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER info is an invalid pointer.

PEAK_STATUS_OUT_OF_RANGE channel number is out of range.

PEAK_STATUS_BUFFER_TOO_SMALL binArray is too small. The needed number of bytes is supplied in binArraySize .

PEAK_STATUS_INVALID_HANDLE hHistogram is an invalid frame handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.11

peak_IPL_Histogram_Channel_GetCount()

peak_status peak_IPL_Histogram_Channel_GetCount	(	peak_histogram_handle	hHistogram,
		size_t *	numChannels )

Get the number of channels in the histogram.

This function returns the number of channels present in the histogram. The number of channels relates to the supplied peak_pixel_format. For example PEAK_PIXEL_FORMAT_MONO8 is a mono format, so it has only one channel whereas PEAK_PIXEL_FORMAT_RGB8 has 3 channels for R, G, B in that order.

Parameters

[in]	hHistogram	The handle to the histogram.
[out]	numChannels	The number of channels in the histogram.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER numChannels is an invalid pointer.

PEAK_STATUS_INVALID_HANDLE hHistogram is an invalid handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.11

peak_IPL_Histogram_Channel_GetInfo()

peak_status peak_IPL_Histogram_Channel_GetInfo	(	peak_histogram_handle	hHistogram,
		size_t	channel,
		peak_histogram_channel_info *	channelInfo )

Get the channel info for a channel in the histogram.

This function fill will the peak_histogram_channel_info for the supplied channel number. The channelInfo will contain the number of pixels, the sum of all pixels of a channel and the size of the bin array in counts of uint64_t.

Parameters

[in]	hHistogram	The handle to the histogram.
[in]	channel	The number of the channel to retrieve the channelInfo for.
[out]	channelInfo	The channel channelInfo for the channel in the histogram.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER channelInfo is an invalid pointer.

PEAK_STATUS_OUT_OF_RANGE channel number is out of range.

PEAK_STATUS_INVALID_HANDLE hHistogram is an invalid frame handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.11

peak_IPL_Histogram_ProcessFrame()

peak_status peak_IPL_Histogram_ProcessFrame	(	peak_frame_handle	hFrame,
		peak_histogram_handle *	hHistogram )

Calculates the histogram for the given peak_frame_handle.

A call to this function may take some time. If a continuous processing of the histogram is needed, an extra thread calling this function may be preferred. The handle returned by hHistogram needs to be released after use by a call to peak_IPL_Histogram_Release.

Remarks

Will not work for packed formats

Parameters

[in]	hFrame	The frame handle.
[out]	hHistogram	The handle to the resulting histogram.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_PARAMETER hHistogram is an invalid pointer.

PEAK_STATUS_INVALID_HANDLE hFrame is an invalid frame handle.

PEAK_STATUS_NOT_SUPPORTED hFrame has an unsupported pixel format.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.11

peak_IPL_Histogram_Release()

peak_status peak_IPL_Histogram_Release

(

peak_histogram_handle

hHistogram

)

Releases the histogram after use.

Releases the peak_histogram_handle acquired by calling peak_IPL_Histogram_Process. After the call, the histogram handle is invalid. Further use of it will fail.

Parameters

[in]

hHistogram

The handle to the histogram to release.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_INVALID_HANDLE hHistogram is an invalid frame handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.11