Accessing Histograms

There are several ways to access a histogram's data. The most straightforward method is to use OpenCV's accessor functions.

double cvQueryHistValue_1D(
  CvHistogram* hist,
  int          idx0
);
double cvQueryHistValue_2D(
  CvHistogram* hist,
  int          idx0,
  int          idx1
);
double cvQueryHistValue_3D(
  CvHistogram* hist,
  int          idx0,
  int          idx1,
  int          idx2
);
double cvQueryHistValue_nD(
  CvHistogram* hist,
  int*         idxN
);

Each of these functions returns a floating-point number for the value in the appropriate bin. Similarly, you can set (or get) histogram bin values with the functions that return a pointer to a bin (not to a bin's value):

float* cvGetHistValue_1D(
  CvHistogram* hist,
  int          idx0
);
float* cvGetHistValue_2D(
  CvHistogram* hist,
  int          idx0,
  int          idx1
);
float* cvGetHistValue_3D(
  CvHistogram* hist,
  int          idx0,
  int          idx1,
  int          idx2
);
float* cvGetHistValue_nD(
  CvHistogram* hist,
  int*         idxN
);

These functions look a lot like the cvGetReal*D and cvPtr*D families of functions, and in fact they are pretty much the same thing. Inside of these calls are essentially those same matrix accessors called with the matrix hist->bins passed on to them. Similarly, the functions for sparse histograms inherit the behavior of the corresponding sparse matrix functions. If you attempt to access a nonexistent bin using a GetHist*() function in a sparse histogram, then that bin is automatically created and its value set to 0. Note that QueryHist*() functions do not create missing bins.

This leads us to the more general topic of accessing the histogram. In many cases, for dense histograms we will want to access the bins member of the histogram directly. Of course, we might do this just as part of data access. For example, we might want to access all of the elements in a dense histogram sequentially, or we might want to access bins directly for performance reasons, in which case we might use hist->mat.data.fl (again, for dense histograms). Other reasons for accessing histograms include finding how many dimensions it has or what regions are represented by its individual bins. For this information we can use the following tricks to access either the actual data in the CvHistogram structure or the information imbedded in the CvMatND structure known as mat.

int n_dimension             = histogram->mat.dims;
int dim_i_nbins             = histogram->mat.dim[ i ].size;

// uniform histograms
int dim_i_bin_lower_bound   = histogram->thresh[ i ][ 0 ]; 
int dim_i_bin_upper_bound   = histogram->thresh[ i ][ 1 ];

// nonuniform histograms
int dim_i_bin_j_lower_bound = histogram->thresh2[ i ][ j ];
int dim_i_bin_j_upper_bound = histogram->thresh2[ i ][ j+1 ];

As you can see, there's a lot going on inside the histogram data structure.