An image histogram represents the frequency of the occurrence of the various gray levels or colors in the image, in case of 2D and 3D histograms respectively. Therefore, the histogram is similar to the probability density function of the different pixel values, that is, the gray levels, present in the image. In OpenCV, the image histogram may be calculated with the function void calcHist(const Mat* images, int nimages, const int* channels, InputArray mask, OutputArray hist, int dims, const int* histSize, const float** ranges, bool uniform=true, bool accumulate=false). The first parameter is a pointer to the input image. It is possible to calculate the histogram of more than one input image. This allows you to compare image histograms and calculate the joint histogram of several images. The second parameter is the number of source images. The third input parameter is the list of the channels used to compute the histogram. It is possible to calculate the histogram of more than one channel of the same color image. Thus, in this case, the nimages value will be 1 and the const int* channels parameter will be an array with the list of channel numbers.

The number of channels goes from zero to two. The parameter InputArray mask is an optional mask to indicate the array elements (image pixels) counted in the histogram. The fifth parameter is the output histogram. The parameter int dims is the histogram dimensionality that must be positive and not greater than 32 (CV_MAX_DIMS). A histogram can be n-dimensional according to the number of bins used to quantize the pixel values of the image. The parameter const int* histSize is the array of histogram sizes in each dimension. It allows us to compute histograms with non-uniform binning (or quantification). The const float** ranges parameter is the array of the dims arrays of the histogram bin boundaries in each dimension. The last two parameters have Boolean values and by default are true and false respectively. They indicate that the histogram is uniform and non-accumulative.

The following ImgHisto example shows how to calculate and display the one-dimensional histogram of a 2D image:

#include "opencv2/imgproc/imgproc.hpp" // a dedicated include file
#include "opencv2/highgui/highgui.hpp"
#include <iostream>

using namespace cv;
using namespace std;

int main( int argc, char *argv[])
{
    int histSize = 255;

    long int dim;
    Mat hist, image;

    //Read original image
    Mat src = imread( "fruits.jpg");

    //Convert color image to gray level image
    cvtColor(src, image, CV_RGB2GRAY);

    //Create three windows
    namedWindow("Source", 0);
    namedWindow("Gray Level Image", 0);
    namedWindow("Histogram", WINDOW_AUTOSIZE);

    imshow("Source", src);
    imshow("Gray Level Image", image);

    calcHist(&image, 1, 0, Mat(), hist, 1, &histSize, 0);

    dim=image.rows *image.cols;
    Mat histImage = Mat::ones(255, 255, CV_8U)*255;

    normalize(hist, hist, 0, histImage.rows, CV_MINMAX, CV_32F);

    histImage = Scalar::all(255);
    int binW = cvRound((double)histImage.cols/histSize);

    for( int i = 0; i < histSize; i++ )
    rectangle( histImage, Point(i*binW, histImage.rows), Point((i+1)*binW, histImage.rows – cvRound(hist.at<float>(i))), Scalar::all(0), -1, 8, 0 );
    imshow("Histogram", histImage);

    cout << "Press any key to exit...
";
    waitKey(); // Wait for key press
    return 0;
}

The code explanation is given here: the example creates three windows with the source image, the grayscale image, and the result of the 1D histogram. The 1D histogram is shown as a bar diagram for the 255 gray values. Thus, first the color pixels are converted into gray values using the cvtColor function. The gray values are then normalized using the normalize function between 0 and the maximum gray level value. Then the 1D histogram is calculated by discretizing the colors in the image into a number of bins and counting the number of image pixels in each bin. The following screenshot shows the output of the example. Note that a new include file, imgproc.hpp, dedicated to image processing is needed.

Output of the histogram example