L_AutoColorLevelBitmap

#include "l_bitmap.h"

L_LTIMGCLR_API L_INT L_AutoColorLevelBitmap(pBitmap, pLvlClr, uBlackClip, uWhiteClip, uFlags)

pBITMAPHANDLE pBitmap;	pointer to the bitmap handle
pLVLCLR pLvlClr;	pointer to a LVLCLR structure that specifies input level values for all channels
L_UINT uBlackClip;	percentage of the bitmaps black (Shadow) pixels to clip
L_UINT uWhiteClip;	percentage of the bitmaps white (Highlight) pixels to clip
L_UINT uFlags;	a flag that indicates the type of leveling to perform

Applies one of several types of automatic color leveling to an image. This function is also useful for pre-processing images to improve barcode recognition results.

Parameter	Description
pBitmap	Pointer to the bitmap handle.
pLvlClr	Pointer to a LVLCLR structure that specifies the color leveling information used by the function. If AUTO_NOPROCESS is not set in uFlags, you can pass NULL if you are not interested in using these values. If AUTO_NOPROCESS is set in uFlags, then this parameter cannot be NULL.
uBlackClip	An unsigned integer that represents the percentage of black pixels to clip from the bitmap, in hundredths of a percent. Valid values range from 0 to 10000 (which represents 100%). Best results are found using 0.3 to 0.9 %. The default is DEFAULT_BLACK_CLIP, which indicates to clip 0.5% of the black pixels.
uWhiteClip	An unsigned integer that represents the percentage of pixels to clip from the bitmap, in hundredths of a percent. Valid values range from 0 to 10000 (which represents 100%). The default is DEFAULT_WHITE_CLIP, which indicates to clip 0.5% of the white pixels.
uFlags	A flag that indicates the type of leveling to perform. Possible values are:
	Value	Meaning
	AUTO_LEVEL	[0x0001] Perform leveling on the individual R, G and B channels, treating each of the R, G and B channels as a separate entity. It introduces color cast on the image.
	AUTO_CONTRAST	[0x0002] Perform leveling on the MASTER</b>* channel (the grayscale values of the pixels). No color cast will be introduced.
	AUTO_INTENSITY	[0x0003] Perform leveling on the RGB channel (the sum of the R, G, and B channels). No color cast will be introduced.
	AUTO_NOPROCESS	[0x0004] Do not process the bitmap. Just update pLvlClr with the color leveling information used. The color leveling information used depends on which of the other flags was set with AUTO_NOPROCESS. Only one other flag may be set with AUTO_NOPROCESS.

Returns

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

Comments

This function makes dark values darker and light values lighter, automatically enhancing shadows and brightening the image. It also maximizes the tonal range of the image. It enhances contrast and intensity using the image's histogram and a color distribution-based algorithm.

Before calling L_AutoColorLevelBitmap, initialize the size of the LVLCLR structure. The other fields of the structure will be updated with the uMinInput, uMaxInput, uMinOutput, uMaxOutput and uGamma values used by the function for the appropriate channel(s).

If you set the AUTO_NOPROCESS flag in uFlags, the pLvlClr parameter will be updated with the color leveling information used by the L_AutoColorLevelBitmap function. If you then pass the updated pLvlClr structure to the L_ColorLevelBitmap function, you will obtain the same result that you would have obtained if you had called the L_AutoColorLevelBitmap function with the leveling flag by itself.

If you set AUTO_NOPROCESS in uFlags and pass NULL to pLvlClr the function will return an error code.

If you pass only AUTO_NOPROCESS to uFlags then the function will return an error code.

If the image is a grayscale image, then AUTO_LEVEL, AUTO_CONTRAST and AUTO_INTENSITY give identical results. Also the member variables master, red, green and blue of the structure pLvlClr will have the same values.

If the bitmap has a region, the effect will be applied only on the region.

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 theDocument and Medical Imaging toolkits.

This function does not support signed data images. It returns the error code ERROR_SIGNED_DATA_NOT_SUPPORTED if a signed data image is passed to this function.

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.

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

For an example, click here.

*Calculating Master Channel Values

In order to speed up widely used image processing filters in LEADTOOLS, the grayscale values (master channel) of a colored image are calculated using the following formulas:

        /// #define CalcGrayValue(r, g, b) ((L_UCHAR)(((L_UCHAR) (((2 * (L_UINT) (r)) + (5 * (L_UINT) (g)) + (L_UINT) (b) + 4) / 8)))) 
        /// #define CalcGrayValue16(r, g, b) ((L_UINT16) (((2 * (L_UINT32) (r)) + (5 * (L_UINT32) (g)) + (L_UINT32) (b) + 4) / 8)) 
        /// #define CalcGrayValue32(r, g, b) ((L_UINT32) (((2 * (L_UINT32) (r)) + (5 * (L_UINT32) (g)) + (L_UINT32) (b) + 4) / 8))

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.

Example

This example loads a bitmap and applies auto image leveling.

#define MAKE_IMAGE_PATH(pFileName) TEXT("C:\\Users\\Public\\Documents\\LEADTOOLS Images\\")pFileName 
L_INT AutoColorLevelBitmapExample(L_VOID) 
{ 
   L_INT nRet; 
   BITMAPHANDLE LeadBitmap;   /* Bitmap handle to hold the loaded image. */ 
   LVLCLR lc;        /* Structure to hold the level values, used for display only */ 
   L_TCHAR buffer[100]; 
   /* Load the bitmap, keeping the bits per pixel of the file */ 
   nRet = L_LoadBitmap (MAKE_IMAGE_PATH(TEXT("ImageProcessingDemo\\Image1.jpg")), &LeadBitmap, sizeof(BITMAPHANDLE), 0, ORDER_BGR, NULL, NULL); 
   if(nRet !=SUCCESS) 
      return nRet; 
   /* Apply "Auto Leveling" to the bitmap */ 
   lc.uStructSize = sizeof(LVLCLR); 
   nRet = L_AutoColorLevelBitmap (&LeadBitmap, &lc, DEFAULT_BLACK_CLIP, DEFAULT_WHITE_CLIP, AUTO_LEVEL); 
   if(nRet !=SUCCESS) 
      return nRet; 
   wsprintf (buffer, TEXT("Min and Max input values for the blue channel using auto level are %d and %d"), lc.blue.nMinInput, lc.blue.nMaxInput); 
   if(LeadBitmap.Flags.Allocated) 
      L_FreeBitmap(&LeadBitmap); 
   return SUCCESS; 
}

Help Version 19.0.2017.10.27

LEADTOOLS Raster Imaging C API Help

Introduction

Version History

Getting Started

LEADTOOLS Raster Imaging Features

Redistributables/Files To Be Included With Your Application

Functions:	L_SharpenBitmap, L_PosterizeBitmap, L_MosaicBitmap, L_EmbossBitmap, L_MedianFilterBitmap, L_AddBitmapNoise, L_IntensityDetectBitmap, L_SpatialFilterBitmap, L_BinaryFilterBitmap, L_MaxFilterBitmap, L_MinFilterBitmap, L_OilifyBitmap, L_SolarizeBitmap, L_DlgColor, L_WindowLevel, L_ColorLevelBitmap, L_SelectiveColorBitmap, L_GammaCorrectBitmapExt, L_AdjustBitmapTint, L_ColorHalfToneBitmap
Topics:	Raster Image Functions: Modifying Intensity Values
	Changing Brightness and Contrast
	Raster Image Functions: Changing Brightness and Contrast
	Correcting Colors
	Color Halftone and Halftone Images
	Raster Image Functions: Correcting Colors