Calculates a histogram of a set of arrays.
Parameters: 


The functions calcHist calculate the histogram of one or more arrays. The elements of a tuple used to increment a histogram bin are taken from the corresponding input arrays at the same location. The sample below shows how to compute a 2D HueSaturation histogram for a color image.
#include <cv.h>
#include <highgui.h>
using namespace cv;
int main( int argc, char** argv )
{
Mat src, hsv;
if( argc != 2  !(src=imread(argv[1], 1)).data )
return 1;
cvtColor(src, hsv, CV_BGR2HSV);
// Quantize the hue to 30 levels
// and the saturation to 32 levels
int hbins = 30, sbins = 32;
int histSize[] = {hbins, sbins};
// hue varies from 0 to 179, see cvtColor
float hranges[] = { 0, 180 };
// saturation varies from 0 (blackgraywhite) to
// 255 (pure spectrum color)
float sranges[] = { 0, 256 };
const float* ranges[] = { hranges, sranges };
MatND hist;
// we compute the histogram from the 0th and 1st channels
int channels[] = {0, 1};
calcHist( &hsv, 1, channels, Mat(), // do not use mask
hist, 2, histSize, ranges,
true, // the histogram is uniform
false );
double maxVal=0;
minMaxLoc(hist, 0, &maxVal, 0, 0);
int scale = 10;
Mat histImg = Mat::zeros(sbins*scale, hbins*10, CV_8UC3);
for( int h = 0; h < hbins; h++ )
for( int s = 0; s < sbins; s++ )
{
float binVal = hist.at<float>(h, s);
int intensity = cvRound(binVal*255/maxVal);
rectangle( histImg, Point(h*scale, s*scale),
Point( (h+1)*scale  1, (s+1)*scale  1),
Scalar::all(intensity),
CV_FILLED );
}
namedWindow( "Source", 1 );
imshow( "Source", src );
namedWindow( "HS Histogram", 1 );
imshow( "HS Histogram", histImg );
waitKey();
}
Calculates the back projection of a histogram.
Parameters: 


The functions calcBackProject calculate the back project of the histogram. That is, similarly to calcHist , at each location (x, y) the function collects the values from the selected channels in the input images and finds the corresponding histogram bin. But instead of incrementing it, the function reads the bin value, scales it by scale , and stores in backProject(x,y) . In terms of statistics, the function computes probability of each element value in respect with the empirical probability distribution represented by the histogram. See how, for example, you can find and track a brightcolored object in a scene:
This is an approximate algorithm of the CamShift() color object tracker.
See also
Compares two histograms.
Parameters: 


The functions compareHist compare two dense or two sparse histograms using the specified method:
Correlation (method=CV_COMP_CORREL)
where
and is a total number of histogram bins.
ChiSquare (method=CV_COMP_CHISQR)
Intersection (method=CV_COMP_INTERSECT)
Bhattacharyya distance (method=CV_COMP_BHATTACHARYYA)
The function returns .
While the function works well with 1, 2, 3dimensional dense histograms, it may not be suitable for highdimensional sparse histograms. In such histograms, because of aliasing and sampling problems, the coordinates of nonzero histogram bins can slightly shift. To compare such histograms or more general sparse configurations of weighted points, consider using the EMD() function.
Computes the “minimal work” distance between two weighted point configurations.
Parameters: 


The function computes the earth mover distance and/or a lower boundary of the distance between the two weighted point configurations. One of the applications described in [RubnerSept98] is multidimensional histogram comparison for image retrieval. EMD is a transportation problem that is solved using some modification of a simplex algorithm, thus the complexity is exponential in the worst case, though, on average it is much faster. In the case of a real metric the lower boundary can be calculated even faster (using lineartime algorithm) and it can be used to determine roughly whether the two signatures are far enough so that they cannot relate to the same object.
Equalizes the histogram of a grayscale image.
Parameters: 


The function equalizes the histogram of the input image using the following algorithm:
Calculate the histogram for src .
Normalize the histogram so that the sum of histogram bins is 255.
Compute the integral of the histogram:
Transform the image using as a lookup table:
The algorithm normalizes the brightness and increases the contrast of the image.
The rest of the section describes additional C functions operating on CvHistogram.
Locates a template within an image by using a histogram comparison.
Parameters: 


The function calculates the back projection by comparing histograms of the source image patches with the given histogram. The function is similar to matchTemplate(), but instead of comparing the raster patch with all its possible positions within the search window, the function CalcBackProjectPatch compares histograms. See the algorithm diagram below:
Divides one histogram by another.
Parameters: 


The function calculates the object probability density from two histograms as:
Clears the histogram.
Parameters:  hist – Histogram. 

The function sets all of the histogram bins to 0 in case of a dense histogram and removes all histogram bins in case of a sparse array.
Copies a histogram.
Parameters: 


The function makes a copy of the histogram. If the second histogram pointer *dst is NULL, a new histogram of the same size as src is created. Otherwise, both histograms must have equal types and sizes. Then the function copies the bin values of the source histogram to the destination histogram and sets the same bin value ranges as in src.
Creates a histogram.
Parameters: 


The function creates a histogram of the specified size and returns a pointer to the created histogram. If the array ranges is 0, the histogram bin ranges must be specified later via the function SetHistBinRanges(). Though CalcHist() and CalcBackProject() may process 8bit images without setting bin ranges, they assume they are equally spaced in 0 to 255 bins.
Returns a pointer to the histogram bin.
Parameters: 


#define cvGetHistValue_1D( hist, idx0 )
((float*)(cvPtr1D( (hist)>bins, (idx0), 0 ))
#define cvGetHistValue_2D( hist, idx0, idx1 )
((float*)(cvPtr2D( (hist)>bins, (idx0), (idx1), 0 )))
#define cvGetHistValue_3D( hist, idx0, idx1, idx2 )
((float*)(cvPtr3D( (hist)>bins, (idx0), (idx1), (idx2), 0 )))
#define cvGetHistValue_nD( hist, idx )
((float*)(cvPtrND( (hist)>bins, (idx), 0 )))
The macros GetHistValue return a pointer to the specified bin of the 1D, 2D, 3D, or ND histogram. In case of a sparse histogram, the function creates a new bin and sets it to 0, unless it exists already.
Finds the minimum and maximum histogram bins.
Parameters: 


The function finds the minimum and maximum histogram bins and their positions. All of output arguments are optional. Among several extremas with the same value the ones with the minimum index (in the lexicographical order) are returned. In case of several maximums or minimums, the earliest in the lexicographical order (extrema locations) is returned.
Makes a histogram out of an array.
Parameters: 


The function initializes the histogram, whose header and bins are allocated by the user. ReleaseHist() does not need to be called afterwards. Only dense histograms can be initialized this way. The function returns hist.
Normalizes the histogram.
Parameters: 


The function normalizes the histogram bins by scaling them so that the sum of the bins becomes equal to factor.
Queries the value of the histogram bin.
Parameters: 


The macros return the value of the specified bin of the 1D, 2D, 3D, or ND histogram. In case of a sparse histogram, the function returns 0. If the bin is not present in the histogram, no new bin is created.
Releases the histogram.
Parameters: 


The function releases the histogram (header and the data). The pointer to the histogram is cleared by the function. If *hist pointer is already NULL, the function does nothing.
Sets the bounds of the histogram bins.
Parameters: 


This is a standalone function for setting bin ranges in the histogram. For a more detailed description of the parameters ranges and uniform, see the CalcHist() function that can initialize the ranges as well. Ranges for the histogram bins must be set before the histogram is calculated or the backproject of the histogram is calculated.
Thresholds the histogram.
Parameters: 


The function clears histogram bins that are below the specified threshold.
Calculates a pairwise geometrical histogram for a contour.
Parameters: 


The function calculates a 2D pairwise geometrical histogram (PGH), described in [Iivarinen97] for the contour. The algorithm considers every pair of contour edges. The angle between the edges and the minimum/maximum distances are determined for every pair. To do this, each of the edges in turn is taken as the base, while the function loops through all the other edges. When the base edge and any other edge are considered, the minimum and maximum distances from the points on the nonbase edge and line of the base edge are selected. The angle between the edges defines the row of the histogram in which all the bins that correspond to the distance between the calculated minimum and maximum distances are incremented (that is, the histogram is transposed relatively to the definition in the original paper). The histogram can be used for contour matching.
[RubnerSept98] 

[Iivarinen97]  Jukka Iivarinen, Markus Peura, Jaakko Srel, and Ari Visa. Comparison of Combined Shape Descriptors for Irregular Objects, 8th British Machine Vision Conference, BMVC‘97. http://www.cis.hut.fi/research/IA/paper/publications/bmvc97/bmvc97.html 