ImageGear for C and C++ on Windows v19.6 - Updated
MED_IP_histo_tabulate
API Reference Guide > MD Component API Reference > MD Component Functions Reference > Image Processing Functions > MED_IP_histo_tabulate

This function is used to tabulate the histogram of a 8 or 16-bit grayscale image.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI MED_IP_histo_tabulate(
        const HIGEAR hIGear, 
        const LPAT_RECT lpRect, 
        LPLONG lpHisto, 
        const WORD nBin_width, 
        const DWORD dwBin_count, 
        LPBOOL lpSigned, 
        LPLONG lpCount
);

Arguments:

Name Type Description
hIGear const HIGEAR The HIGEAR handle to the image for which to create a histogram.
lpRect const LPAT_RECT A far pointer to a struct of type AT_RECT that defines the rectangular portion of the image to use for creating a histogram. Please see the ImageGear User's Manual if you are unfamiliar with this structure.
lpHisto LPLONG A far pointer to a buffer to be used for holding the histogram.
nBin_width const WORD An integer variable that specifies the range of pixel values to be counted into one bin.
dwBin_count const DWORD A DWORD variable that specifies the number of bins allocated.
lpSigned LPBOOL A far pointer to a BOOL that returns the sign status of the image. If it returns TRUE, the image is signed.
lpCount LPLONG A far pointer to a LONG which returns the number of pixels counted.

Return Value:

Returns the number of ImageGear errors that occurred during the function call.

Supported Raster Image Formats:

Grayscale – 8…16 bpp.

Remarks:

The histogram is returned in the memory block, lpHisto, allocated by the application. This memory block must be large enough to hold the histogram for the image. Each histogram bin must be 4 bytes wide. The size of lpHisto needed (in bytes) can be computed as follows:

size = ((possible_pixel_values) * 4) / nBin_width

where possible_pixel_values depends on the bit depth of the image (8g=256, 9g=512,...). nBin_width is used to determine the range of pixel values that are counted in their own bin. A value of 1 indicates that each pixel value is counted in its own histogram bin. A value of 2 would allow neighboring values (such as 128 and 129) to be counted as a single bin (as a single value). If nBin_width==possible_pixel_values then only a single histogram bin (4 bytes) is filled and the count will be equal to the number of pixel values in the lpRect.

nBin_count is used as a safety. This should be set to the number of bins in the histogram that your application has allocated. If a pixel value is going to overflow this memory it will be ignored. This pixel value will not be included in the sum returned in lpCount (you can use this to determine if any values were ignored).