L_GetBitmapHistogram

Show in webframe

#include "l_bitmap.h"

L_LTIMGCLR_API L_INT L_GetBitmapHistogram(pBitmap, pHisto, uHistoLen, uFlags)

pBITMAPHANDLE pBitmap;	/* pointer to the bitmap handle */
L_UINT64 *pHisto;	/* an array to hold the histogram */
L_SIZE_T uHistoLen;	/* length of the histogram */
L_UINT uFlags;	/* flags */

Creates an array that charts how many times each intensity level occurs in a bitmap. This function can chart red, green, and blue separately or together. It is used for all resolutions, including 12 and 16-bit grayscale.

Parameter	Description
pBitmap	Pointer to the bitmap handle referencing the bitmap.
pHisto	An array of unsigned 64-bit integers that charts the number of times each intensity level occurs in the image.
uHistoLen	Length of the histogram.
uFlags	Flags that indicate the channel for which to get the histogram and the bits to use in calculating the histogram. The following flags indicate the channel to use. This value is ignored if the bitmap is 12 or 16-bit grayscale. Possible values are:
	Value	Meaning
	CHANNEL_MASTER	[0x0000] All channels.
	CHANNEL_RED	[0x0001] Red channel only.
	CHANNEL_GREEN	[0x0002] Green channel only.
	CHANNEL_BLUE	[0x0003] Blue channel only.
	The following flags determine which bits to use when calculating the histogram. This value is used only if the bitmap is 12 or 16-bit grayscale. Possible values are:
	Value	Meaning
	HIST_LOWHIGH_BITS	[0x0000] Use the only the bits between the LowBit and HighBit values stored in the bitmap handle.
	HIST_ALL_BITS	[0x0010] Use all the bits for calculating the histogram (the LowBit and HighBit values from the bitmap handle are ignored.

Returns

SUCCESS	The function was successful.
< 1	An error occurred. Refer to Return Codes.

Comments

For 1, 2, 3, 4, 5, 6, 7, 8, 16, 24, and 32 bit color bitmaps, intensity levels range from 0 to 255. Therefore, the resulting array has 256 items, indexed by intensity value. The value of each item is the number of occurrences of the intensity level.

This function supports 12 and 16-bit grayscale and 48 and 64-bit color images. Support for 12 and 16-bit grayscale and 48 and 64-bit color images is available in the Document and Medical Imaging toolkits.

For 48 and 64-bit images, the intensity levels range from 0 to 65535. Therefore, the resulting array has 65536 items, indexed by intensity value. The value of each item is the number of occurrences of the intensity level.

This functions also works on 12 and 16-bit grayscale images. Intensity values in these bitmaps can range from 0 to (2^16 1) for 16-bit grayscale or from 0 to (2^12 1) for 12- bit grayscale. The LowBit and HighBit identify which bits in a 12-bit or 16-bit entry are used. The LowBit and HighBit can be obtained by using L_GetMinMaxBits or by looking at the corresponding fields in the BITMAPHANDLE itself.

Specifically, the table must hold at least 2^(HighBit LowBit + 1) entries if HIST_LOWHIGH_BITS is set in uFlags. If HIST_ALL_BITS is set in uFlags, the table must hold at least 4096 for 12-bit bitmaps and 65536 for 16-bit bitmaps.

For example, suppose HIST_LOWHIGH_BITS is set in uFlags and you have a 16-bit grayscale image with LowBit = 2 and HighBit = 7. There are 2^(7-2+1) = 64 possible grayscale intensities. The table must therefore hold at least 64 entries. The number of grayscale values with bits 2 7 set to 0 can be found in pHisto [0]. The number of grayscale values with bit 2 set to 1 and bits 3 7 set to 0 can be found in pHisto [1], and so on up to pHisto [63]. Since the low bit is 2 and the high bit is 7, bits 0, 1, and bits 8 15 must all be 0. Therefore the values set in bits 2 7 determine the intensities present in the image. In the table below, the gray columns represent those bits that are always 0 for the image. The columns bit 7 through bit 2 represent possible settings for those bits. The last column gives the location within the pHisto array of the number of grayscale values having the corresponding settings. For example, pHisto [0] contains the number of grayscale values of intensity 0 (all bits set to 0). pHisto [1] contains all the grayscale values with intensity 4 (the 2 bit position set to 1). pHisto [2] contains all the grayscale values with intensity 8 (the 3 bit set to 1 and the remaining bits set to 0) and so on.

bits 8 15	bit 7	bit 6	bit 5	bit 4	bit 3	bit 2	bit 1	bit 0	count location in pHisto
all 0s	0	0	0	0	0	0	0	0	pHisto [0]
all 0s	0	0	0	0	0	1	0	0	pHisto [1]
all 0s	0	0	0	0	1	0	0	0	pHisto [2]
all 0s	0	0	0	0	1	1	0	0	pHisto [3]
all 0s	0	0	0	1	0	0	0	0	pHisto [4]
									and so on
all 0s	1	1	1	1	1	1	0	0	pHisto [63]

As another example, suppose you have a 16-bit grayscale image with LowBit = 0 and HighBit = 15. The table must hold 2^16 = 65,536 L_UINT64 values.

To update a status bar or detect a user interrupt during execution of this function, refer to L_SetStatusCallback.

This function does not support 32-bit grayscale images. It returns the error code ERROR_GRAY32_UNSUPPORTED if a 32-bit grayscale image is passed to this function.

Required DLLs and Libraries

LTIMGCLR

For a listing of the exact DLLs and Libraries needed, based on the toolkit version, refer to Files To Be Included With Your Application.

Platforms

Win32, x64, Linux.

See Also

Functions:	L_ChangeBitmapIntensity, L_GammaCorrectBitmap, L_ChangeBitmapContrast, L_HistoContrastBitmap, L_StretchBitmapIntensity, L_RemapBitmapIntensity, L_InvertBitmap, L_ChangeBitmapHue, L_ChangeBitmapSaturation, L_HistoEqualizeBitmap, L_FillBitmap, L_GetPixelColor, L_PutPixelColor, L_WindowLevel , L_ChannelMix, L_DeinterlaceBitmap, L_DesaturateBitmap, L_EdgeDetectStatisticalBitmap, L_LightControlBitmap, L_SmoothEdgesBitmap, L_LocalHistoEqualizeBitmap, L_AddWeightedBitmaps, L_ColorMergeBitmap, L_ColorSeparateBitmap, L_ConvertColorSpace, L_MultiplyBitmap, L_AutoColorLevelBitmap, L_ColorLevelBitmap, L_CorrelationBitmap, L_GrayScaleToDuotone, L_GrayScaleToMultitone, L_HolesRemovalBitmapRgn, L_SelectiveColorBitmap, L_SkeletonBitmap, L_ChangeHueSatIntBitmap, L_ColorReplaceBitmap, L_ColorThresholdBitmap, L_MathFunctionBitmap, L_SegmentBitmap, L_AdaptiveContrastBitmap, L_ApplyMathLogicBitmap, L_ColorIntensityBalance, L_ColorizeGrayBitmap, L_ContBrightIntBitmap, L_DigitalSubtractBitmap, L_DynamicBinaryBitmap, L_EdgeDetectEffectBitmap, L_FunctionalLightBitmap, L_MultiScaleEnhancementBitmap, L_SelectBitmapData, L_ShiftBitmapData
Topics:	Raster Image Functions: Modifying Intensity Values
	Changing Brightness and Contrast
	Raster Image Functions: Changing Brightness and Contrast
	Color Halftone and Halftone Images

Example

This example loads a bitmap at 24 bit per pixel and creates a red-channel histogram, finds the brightest and darkest intensities in the histogram, and displays the values

#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName


 L_INT GetBitmapHistogramExample(L_VOID)
{
   L_INT nRet;
   L_TCHAR szMessage[80];               /* Buffer for the MessageBox string */
   BITMAPHANDLE LeadBitmap;    /* Bitmap handle to hold the loaded image */
   L_UINT64 Histogram[256];           /* Array for the histogram */
   L_INT nIndex;                               /* Array index */
   L_INT nBrightest;                         /* Brightest value */
   L_INT nDarkest;                           /* Darkest value */
   /* Load the bitmap at 24  bits per pixel */
   nRet = L_LoadBitmap (MAKE_IMAGE_PATH(TEXT("ImageProcessingDemo\\Image3.cmp")), &LeadBitmap, sizeof(BITMAPHANDLE), 24, ORDER_BGR, NULL, NULL);
   if(nRet !=SUCCESS)
      return nRet;
   /* Create the red-channel histogram */
   nRet = L_GetBitmapHistogram(&LeadBitmap, Histogram, 256, CHANNEL_RED | HIST_ALL_BITS);
   if(nRet !=SUCCESS)
      return nRet;
   /* Initialize the darkest and brightest index values */
   nDarkest = 0;
   nBrightest = 0;
   /* Find the brightest and darkest intensities in the histogram */
   for(nIndex = 0; nIndex < 256; nIndex++)
   {
       if (Histogram[nIndex] != 0)
       {
           nBrightest = nIndex;
           if (nDarkest == 0)
              nDarkest = nIndex;
       }
   }
   /* Display the values in a message box */
   wsprintf (szMessage, TEXT("Darkest red = %d;  Brightest red = %d"), nDarkest, nBrightest);
   MessageBox (NULL, szMessage, TEXT("Notice"), MB_OK);
   if(LeadBitmap.Flags.Allocated)  
      L_FreeBitmap(&LeadBitmap);  
   return SUCCESS;
}