xil_histogram_create(3)

NAME

xil_histogram_create, xil_histogram_create_copy, xil_histogram_destroy − create, create and return a copy, or destroy histogram

SYNOPSIS

#include <xil/xil.h>

XilHistogram xil_histogram_create ( XilSystemState State,

unsigned int nbands,
unsigned int ∗nbins,
float ∗low_value,
float ∗high_value);

XilHistogram xil_histogram_create_copy ( XilHistogram histogram);

void xil_histogram_destroy ( XilHistogram histogram);

DESCRIPTION

These routines create and destroy histogram objects. Histograms are used to accumulate level information from images. XIL histograms can have an arbitrary numbers of bands, but the number of bands must match the number of bands in the image that is to be histogrammed. A histogram of a 3-band RGB image for example, contains a cube of information that reflects the number of pixels found in each of the bins, as in the three-dimensional array pixel_count[red_bin][green_bin][blue_bin].

State is the XIL system state.

nbands is the number of independent bands in the histogram.

nbins is a pointer to an array that contains the number of bins for each band. These bins are used to hold information about gray or color levels.

CAUTION: The total number of bins in the histogram is the product of the nbins value for all bands. Specifying too many bins for multi-band images may consume large quantities of memory and lead to significantly degraded performance. For example, specifying 256 bins for each band of a 3 band images would require a histogram data array of approximately 16 million bins (64 Mbytes).

low_value is a pointer to an array of floats that defines the central value of the first bin for each band.

high_value is a pointer to an array of floats that defines the central value of the last bin for each band.

For each of the arrays nbins, low_value, and high_value, the number of elements in the array must match the number of bands in the image.

xil_histogram_create_copy () creates and returns a copy of the specified histogram. The name of a copy is initially empty (NULL). xil_histogram_destroy() destroys the specified histogram object.

ERRORS

For a complete list of XIL error messages by number, consult Appendix B of the XIL Programmer’s Guide.

EXAMPLES

Create a histogram structure appropriate for calculating the histogram of a 3-band XIL_BYTE image. Note the use of the first and last bin central values for low_value and high_value:

XilSystemState State;
XilHistogram histogram;
unsigned int nbins[3] = {32,32,32}; /∗ Total bins = 32768 ∗/
float low_value[3] = {4.0, 4.0, 4.0};
float high_value[3] = {252.0, 252.0, 252.0};
histogram = xil_histogram_create (State, 3, nbins, low_value, high_value);

Museum