Image Histogram

Overview

An image histogram is the representation of the tonal distribution in a digital image. It counts the number of pixels for each tonal value. For more information, see [1].

Input	Parameters	Output
	start = 0 end = 256 numBins = 256

Implementation

This algorithm partitions the distribution into a number of bins and counts the number of occurrences of each pixel value within the bins.

A pixel with intensity 'i' will result in incrementing histogram bin \(b_i\) where

\[ b_i = \frac{(i - \text{start}) * \text{numBins}}{\text{end}-\text{start}} \]

Note

The histogram result from CPU and CUDA backends do not match in some corner cases because these backends perform floating point calculations differently. Floating point calculations on CPU and CUDA are gauranteed to be the same only to some level of precision. These minor difference may cause bin indexes to be calculated differently. For example, when start = 0, end = 245, number of bins = 50, in case of pixel value = 147, the CPU backend will return bin index = 30 while CUDA backend will return bin index = 29.999998.

C API functions

For list of limitations, constraints and backends that implements the algorithm, consult reference documentation of the following functions:

Function	Description
vpiCreateHistogramEven	Creates payload for Image Histogram Even algorithm.
vpiSubmitHistogram	Computes the image histogram.

Usage

Language: C/C++ Python

1. Import VPI module

   import vpi

2. Use the CUDA backend calculate the histogram of the input VPI image. The output is a VPI array with numBins elements.

   with vpi.Backend.CUDA:
       output = input.histogram(numBins, range=(start, end))

1. Initialization phase
   1. Include the header that defines the image histogram function.

      #include <vpi/algo/Histogram.h>

   2. Define the input image.

          VPIImage input = /*...*/;

   3. Create the output array.

          VPIArray output;
          vpiArrayCreate(numBins, VPI_ARRAY_TYPE_U32, 0, &output);

   4. Since this algorithm needs temporary memory buffers, create the payload for it on the CUDA backend.

          VPIPayload payload;
          vpiCreateHistogramEven(VPI_BACKEND_CUDA, VPI_IMAGE_FORMAT_U8, start, end, numBins, &payload);

   5. Create the stream where the algorithm is to be submitted for execution.

          VPIStream stream;
          vpiStreamCreate(0, &stream);

2. Processing phase
   1. Submit the algorithm to the stream using the CUDA backend, along with all parameters.

          vpiSubmitHistogram(stream, VPI_BACKEND_CUDA, payload, input, output, 0);

   2. Optionally, wait until the processing is done.

          vpiStreamSync(stream);

3. Cleanup phase
   1. Free resources held by the stream and the input and output images.

          vpiStreamDestroy(stream);
          vpiImageDestroy(input);
          vpiArrayDestroy(output);
          vpiPayloadDestroy(payload);

For more information, see Image Histogram in the "C API Reference" section of VPI - Vision Programming Interface.

Performance

For information on how to use the performance table below, see Algorithm Performance Tables.
Before comparing measurements, consult Comparing Algorithm Elapsed Times.
For further information on how performance was benchmarked, see Performance Benchmark.

clear filters Device: Jetson AGX Xavier Jetson AGX Orin  -  Streams: 1 2 4 8

References

1. https://en.wikipedia.org/wiki/Image_histogram