Histograms

CvHistogram

Comments from the Wiki

CvHistogram

Multi-dimensional histogram.

typedef struct CvHistogram
{
    int     type;
    CvArr*  bins;
    float   thresh[CV_MAX_DIM][2]; /* for uniform histograms */
    float** thresh2; /* for non-uniform histograms */
    CvMatND mat; /* embedded matrix header for array histograms */
}
CvHistogram;

CalcBackProject

Comments from the Wiki

void cvCalcBackProject(IplImage** image, CvArr* back_project, const CvHistogram* hist)

Calculates the back projection.

Parameters:

• image – Source images (though you may pass CvMat** as well)
• back_project – Destination back projection image of the same type as the source images
• hist – Histogram

The function calculates the back project of the histogram. For each tuple of pixels at the same position of all input single-channel images the function puts the value of the histogram bin, corresponding to the tuple in the destination image. In terms of statistics, the value of each output image pixel is the probability of the observed tuple given the distribution (histogram). For example, to find a red object in the picture, one may do the following:

1. Calculate a hue histogram for the red object assuming the image contains only this object. The histogram is likely to have a strong maximum, corresponding to red color.
2. Calculate back projection of a hue plane of input image where the object is searched, using the histogram. Threshold the image.
3. Find connected components in the resulting picture and choose the right component using some additional criteria, for example, the largest connected component.

That is the approximate algorithm of Camshift color object tracker, except for the 3rd step, instead of which CAMSHIFT algorithm is used to locate the object on the back projection given the previous object position.

CalcBackProjectPatch

Comments from the Wiki

void cvCalcBackProjectPatch(IplImage** images, CvArr* dst, CvSize patch_size, CvHistogram* hist, int method, double factor)

Locates a template within an image by using a histogram comparison.

Parameters:

• images – Source images (though, you may pass CvMat** as well)
• dst – Destination image
• patch_size – Size of the patch slid though the source image
• hist – Histogram
• method – Comparison method, passed to CompareHist (see description of that function)
• factor – Normalization factor for histograms, will affect the normalization scale of the destination image, pass 1 if unsure

The function calculates the back projection by comparing histograms of the source image patches with the given histogram. Taking measurement results from some image at each location over ROI creates an array image . These results might be one or more of hue, x derivative, y derivative, Laplacian filter, oriented Gabor filter, etc. Each measurement output is collected into its own separate image. The image image array is a collection of these measurement images. A multi-dimensional histogram hist is constructed by sampling from the image image array. The final histogram is normalized. The hist histogram has as many dimensions as the number of elements in image array.

Each new image is measured and then converted into an image image array over a chosen ROI. Histograms are taken from this image image in an area covered by a “patch” with an anchor at center as shown in the picture below. The histogram is normalized using the parameter norm_factor so that it may be compared with hist . The calculated histogram is compared to the model histogram; hist uses The function cvCompareHist with the comparison method= method ). The resulting output is placed at the location corresponding to the patch anchor in the probability image dst . This process is repeated as the patch is slid over the ROI. Iterative histogram update by subtracting trailing pixels covered by the patch and adding newly covered pixels to the histogram can save a lot of operations, though it is not implemented yet.

Back Project Calculation by Patches

CalcHist

Comments from the Wiki

void cvCalcHist(IplImage** image, CvHistogram* hist, int accumulate=0, const CvArr* mask=NULL)

Calculates the histogram of image(s).

Parameters:

• image – Source images (though you may pass CvMat** as well)
• hist – Pointer to the histogram
• accumulate – Accumulation flag. If it is set, the histogram is not cleared in the beginning. This feature allows user to compute a single histogram from several images, or to update the histogram online
• mask – The operation mask, determines what pixels of the source images are counted

The function calculates the histogram of one or more single-channel images. The elements of a tuple that is used to increment a histogram bin are taken at the same location from the corresponding input images.

#include <cv.h>
#include <highgui.h>

int main( int argc, char** argv )
{
    IplImage* src;
    if( argc == 2 && (src=cvLoadImage(argv[1], 1))!= 0)
    {
        IplImage* h_plane = cvCreateImage( cvGetSize(src), 8, 1 );
        IplImage* s_plane = cvCreateImage( cvGetSize(src), 8, 1 );
        IplImage* v_plane = cvCreateImage( cvGetSize(src), 8, 1 );
        IplImage* planes[] = { h_plane, s_plane };
        IplImage* hsv = cvCreateImage( cvGetSize(src), 8, 3 );
        int h_bins = 30, s_bins = 32;
        int hist_size[] = {h_bins, s_bins};
        /* hue varies from 0 (~0 deg red) to 180 (~360 deg red again) */
        float h_ranges[] = { 0, 180 };
        /* saturation varies from 0 (black-gray-white) to
           255 (pure spectrum color) */
        float s_ranges[] = { 0, 255 };
        float* ranges[] = { h_ranges, s_ranges };
        int scale = 10;
        IplImage* hist_img =
            cvCreateImage( cvSize(h_bins*scale,s_bins*scale), 8, 3 );
        CvHistogram* hist;
        float max_value = 0;
        int h, s;

        cvCvtColor( src, hsv, CV_BGR2HSV );
        cvCvtPixToPlane( hsv, h_plane, s_plane, v_plane, 0 );
        hist = cvCreateHist( 2, hist_size, CV_HIST_ARRAY, ranges, 1 );
        cvCalcHist( planes, hist, 0, 0 );
        cvGetMinMaxHistValue( hist, 0, &max_value, 0, 0 );
        cvZero( hist_img );

        for( h = 0; h < h_bins; h++ )
        {
            for( s = 0; s < s_bins; s++ )
            {
                float bin_val = cvQueryHistValue_2D( hist, h, s );
                int intensity = cvRound(bin_val*255/max_value);
                cvRectangle( hist_img, cvPoint( h*scale, s*scale ),
                             cvPoint( (h+1)*scale - 1, (s+1)*scale - 1),
                             CV_RGB(intensity,intensity,intensity),
                             CV_FILLED );
            }
        }

        cvNamedWindow( "Source", 1 );
        cvShowImage( "Source", src );

        cvNamedWindow( "H-S Histogram", 1 );
        cvShowImage( "H-S Histogram", hist_img );

        cvWaitKey(0);
    }
}

CalcProbDensity

Comments from the Wiki

void cvCalcProbDensity(const CvHistogram* hist1, const CvHistogram* hist2, CvHistogram* dst_hist, double scale=255)

Divides one histogram by another.

Parameters:

• hist1 – first histogram (the divisor)
• hist2 – second histogram
• dst_hist – destination histogram
• scale – scale factor for the destination histogram

The function calculates the object probability density from the two histograms as:

So the destination histogram bins are within less than scale .

ClearHist

Comments from the Wiki

void cvClearHist(CvHistogram* hist)

Clears the histogram.

Parameters:

• hist – Histogram

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

CompareHist

Comments from the Wiki

double cvCompareHist(const CvHistogram* hist1, const CvHistogram* hist2, int method)

Compares two dense histograms.

Parameters:

• hist1 – The first dense histogram
• hist2 – The second dense histogram
• method –

  Comparison method, one of the following:

  • CV_COMP_CORREL Correlation
  • CV_COMP_CHISQR Chi-Square
  • CV_COMP_INTERSECT Intersection
  • CV_COMP_BHATTACHARYYA Bhattacharyya distance

The function compares two dense histograms using the specified method ( denotes the first histogram, the second):

• Correlation (method=CV_COMP_CORREL)

  

  where

  

  where N is the number of histogram bins.

• Chi-Square (method=CV_COMP_CHISQR)

  

• Intersection (method=CV_COMP_INTERSECT)

  

• Bhattacharyya distance (method=CV_COMP_BHATTACHARYYA)

  

The function returns .

Note: the method CV_COMP_BHATTACHARYYA only works with normalized histograms.

To compare a sparse histogram or more general sparse configurations of weighted points, consider using the CalcEMD2 function.

CopyHist

Comments from the Wiki

void cvCopyHist(const CvHistogram* src, CvHistogram** dst)

Copies a histogram.

Parameters:

• src – Source histogram
• dst – Pointer to destination histogram

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 source histogram’s bin values to the destination histogram and sets the same bin value ranges as in src .

CreateHist

Comments from the Wiki

CvHistogram* cvCreateHist(int dims, int* sizes, int type, float** ranges=NULL, int uniform=1)

Creates a histogram.

Parameters:

• dims – Number of histogram dimensions
• sizes – Array of the histogram dimension sizes
• type – Histogram representation format: CV_HIST_ARRAY means that the histogram data is represented as a multi-dimensional dense array CvMatND; CV_HIST_SPARSE means that histogram data is represented as a multi-dimensional sparse array CvSparseMat
• ranges – Array of ranges for the histogram bins. Its meaning depends on the uniform parameter value. The ranges are used for when the histogram is calculated or backprojected to determine which histogram bin corresponds to which value/tuple of values from the input image(s)
• uniform – Uniformity flag; if not 0, the histogram has evenly spaced bins and for every ranges[i] is an array of two numbers: lower and upper boundaries for the i-th histogram dimension. The whole range [lower,upper] is then split into dims[i] equal parts to determine the i-th input tuple value ranges for every histogram bin. And if uniform=0 , then i-th element of ranges array contains dims[i]+1 elements: where and are lower and upper boundaries of i-th input tuple value for j-th bin, respectively. In either case, the input values that are beyond the specified range for a histogram bin are not counted by CalcHist and filled with 0 by CalcBackProject

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 8-bit images without setting bin ranges, they assume thy are equally spaced in 0 to 255 bins.

GetHistValue*D

Comments from the Wiki

float cvGetHistValue_1D(hist, idx0)

float cvGetHistValue_2D(hist, idx0, idx1)

float cvGetHistValue_3D(hist, idx0, idx1, idx2)

float cvGetHistValue_nD(hist, idx)

Returns a pointer to the histogram bin.

Parameters:

• hist – Histogram
• idx1, idx2, idx3 (idx0,) – Indices of the bin
• idx – Array of indices

#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 N-D histogram. In the case of a sparse histogram the function creates a new bin and sets it to 0, unless it exists already.

GetMinMaxHistValue

Comments from the Wiki

void cvGetMinMaxHistValue(const CvHistogram* hist, float* min_value, float* max_value, int* min_idx=NULL, int* max_idx=NULL)

Finds the minimum and maximum histogram bins.

Parameters:

• hist – Histogram
• min_value – Pointer to the minimum value of the histogram
• max_value – Pointer to the maximum value of the histogram
• min_idx – Pointer to the array of coordinates for the minimum
• max_idx – Pointer to the array of coordinates for the maximum

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 lexicographical order) are returned. In the case of several maximums or minimums, the earliest in lexicographical order (extrema locations) is returned.

MakeHistHeaderForArray

Comments from the Wiki

CvHistogram* cvMakeHistHeaderForArray(int dims, int* sizes, CvHistogram* hist, float* data, float** ranges=NULL, int uniform=1)

Makes a histogram out of an array.

Parameters:

• dims – Number of histogram dimensions
• sizes – Array of the histogram dimension sizes
• hist – The histogram header initialized by the function
• data – Array that will be used to store histogram bins
• ranges – Histogram bin ranges, see CreateHist
• uniform – Uniformity flag, see CreateHist

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

NormalizeHist

Comments from the Wiki

void cvNormalizeHist(CvHistogram* hist, double factor)

Normalizes the histogram.

Parameters:

• hist – Pointer to the histogram
• factor – Normalization factor

The function normalizes the histogram bins by scaling them, such that the sum of the bins becomes equal to factor .

QueryHistValue*D

Comments from the Wiki

float QueryHistValue_1D(CvHistogram hist, int idx0)

Queries the value of the histogram bin.

Parameters:

• hist – Histogram
• idx1, idx2, idx3 (idx0,) – Indices of the bin
• idx – Array of indices

#define cvQueryHistValue_1D( hist, idx0 ) \
    cvGetReal1D( (hist)->bins, (idx0) )
#define cvQueryHistValue_2D( hist, idx0, idx1 ) \
    cvGetReal2D( (hist)->bins, (idx0), (idx1) )
#define cvQueryHistValue_3D( hist, idx0, idx1, idx2 ) \
    cvGetReal3D( (hist)->bins, (idx0), (idx1), (idx2) )
#define cvQueryHistValue_nD( hist, idx ) \
    cvGetRealND( (hist)->bins, (idx) )

The macros return the value of the specified bin of the 1D, 2D, 3D or N-D histogram. In the case of a sparse histogram the function returns 0, if the bin is not present in the histogram no new bin is created.

ReleaseHist

Comments from the Wiki

void cvReleaseHist(CvHistogram** hist)

Releases the histogram.

Parameters:

• hist – Double pointer to the released histogram

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.

SetHistBinRanges

Comments from the Wiki

void cvSetHistBinRanges(CvHistogram* hist, float** ranges, int uniform=1)

Sets the bounds of the histogram bins.

Parameters:

• hist – Histogram
• ranges – Array of bin ranges arrays, see CreateHist
• uniform – Uniformity flag, see CreateHist

The function is a stand-alone 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.

ThreshHist

Comments from the Wiki

void cvThreshHist(CvHistogram* hist, double threshold)

Thresholds the histogram.

Parameters:

• hist – Pointer to the histogram
• threshold – Threshold level

The function clears histogram bins that are below the specified threshold.