DLBitsPerPixelConverter Class Reference

A collection of algorithms to convert among binary, grayscale and color images. More...

#include <DLBitsPerPixelConverter.h>

List of all members.

Public Types

enum  DLImageConversions { DL_2BINARY = 1, DL_2GRAY = 2, DL_2COLOR = 3 }
 image conversions More...
enum  DLBinarizeType { DL_NIBLACK, DL_SAUVOLA, DL_WOLFJOLION, DL_ADANIBLACK }
 Variations of the Niblack binarization algorithm. More...

Static Public Member Functions

static DLImage dlBinary2Gray (const DLImage &imageData)
static DLImage dlGray2Color (const DLImage &imageData)
static DLImage dlBinary2Color (const DLImage &imageData, const DLColor &color)
static DLImage dlBinary2Color (const DLImage &imageData, DL_BYTE r=DL_BLACK, DL_BYTE g=DL_BLACK, DL_BYTE b=DL_BLACK)
static DLImage dlConvertImage (const DLImage &imageData, DLImageConversions conversionCode)
static DLImage dlDownscaleGray2Binary_global (const DLImage &imageData, int th=static_cast< int >(DL_WHITE/2))
static DLImage dlDownscaleGray2Binary_niblack (const DLImage &gImg, DL_BINARIZE_TYPE algorithm=(DL_BINARIZE_TYPE) DL_ADANIBLACK, double k=-0.5, bool detect_inverted=true)
static DLImage dlDownscaleGray2Binary_niblack (const DLImage &gImg, DLBitsPerPixelConverter::DLBinarizeType algorithm, double k=-0.5, bool detect_inverted=true)
static DLImage dlDownscaleColor2Gray_global (const DLImage &imageData)
static DLImage dlDownscaleColor2Gray_weighted (const DLImage &cImg, float rWt, float gWt, float bWt)
static DLImage dlDownscaleColor2Binary_threshold (const DLImage &tImg, int rThresh=100, int gThresh=100, int bThresh=100)
static DLImage dlDownscaleColor2Binary_percentThreshold (const DLImage &tImg, double percent)
static DLImage dlDownscalePercentThresholdBinarization (const DLImage &tImg, int percent)
static DLImage dlDownscale256Color_global (const DLImage &image_in, bool &quantized)
static DLImage dlDownscaleYCrCbBinarization (const DLImage &tImg)


Detailed Description

A collection of algorithms to convert among binary, grayscale and color images.

The DLBitsPerPixelConverter offers a melange of different ways to perform bits-per-pixel conversions. Abstracting this behavior into a single class allows researchers to easily use different conversion algorithms against their work to see how it affects performance. Algorithms that perform upscaling, or converting from a lower bit-depth image to a higher bit-depth image, (ie. binary2color, binary2gray, gray2color) have one generally accepted way of doing so without influencing image data. Thus, each has a one to one function mapping. Alternatively, downscale operations, which convert a high bit-depth image to a low bit-depth image, (ie. gray2binary, color2gray, color2binary) can be done in a plethora of different ways. Detailed documentation of each function will give the user an idea of what type of algorithm each uses. Additionally, an attempt was made to develop function names that generally explain how the downscaling operation is being performed.

All of the bits-per-pixel conversions are accesible as static methods. Therefore, you do not need to instantiate a DLBitsPerPixelConverter object to call these functions. A typical function call is as follows:

 DLImage colorImage("input.tif");
 DLImage grayImage = DLBitsPerPixelConverter::dlDownscaleColor2Gray_global(colorImage);

Definition at line 42 of file DLBitsPerPixelConverter.h.


Member Enumeration Documentation

enum DLBitsPerPixelConverter::DLImageConversions

image conversions

Enumerator:
DL_2BINARY 
DL_2GRAY 
DL_2COLOR 

Definition at line 47 of file DLBitsPerPixelConverter.h.

enum DLBitsPerPixelConverter::DLBinarizeType

Variations of the Niblack binarization algorithm.

Enumerator:
DL_NIBLACK 
DL_SAUVOLA 
DL_WOLFJOLION 
DL_ADANIBLACK 

Definition at line 54 of file DLBitsPerPixelConverter.h.


Member Function Documentation

static DLImage DLBitsPerPixelConverter::dlBinary2Gray ( const DLImage imageData  )  [static]

Convert a binary DLImage (1 bit per pixel) into a grayscale DLImage (1 byte per pixel) by mapping black pixels to 0x00 and white pixels to 0xFF (255).

Parameters:
imageData binary image pass-by-reference that is to be converted.
Returns:
grayscale DLImage

static DLImage DLBitsPerPixelConverter::dlGray2Color ( const DLImage imageData  )  [static]

Convert gray DLImage into color DLImage by mapping each grayscale byte value to each of the R-G-B values in the color domain. For example, a pixel with gray value 0x80 will be mapped to a pixel with red, green and blue channels all equal to 0x80.

Parameters:
imageData grayscale image pass-by-reference that is to be converted to the color domain
Returns:
color DLImage

static DLImage DLBitsPerPixelConverter::dlBinary2Color ( const DLImage imageData,
const DLColor color 
) [static]

Convert binary DLImage into color DLImage by mapping black pixels to color and white pixels to (0xFF, 0xFF, 0xFF).

Parameters:
imageData binary pass-by-reference image to be converted
color DLColor representing the color to which black pixels will be converted
Returns:
color DLImage

static DLImage DLBitsPerPixelConverter::dlBinary2Color ( const DLImage imageData,
DL_BYTE  r = DL_BLACK,
DL_BYTE  g = DL_BLACK,
DL_BYTE  b = DL_BLACK 
) [static]

Convert binary DLImage into color DLImage by mapping black pixels to (r, g, b) and white pixels to (0xFF, 0xFF, 0xFF), where (R, G, B) indicates the values of the red, green and blue channels. If r, g and b are not supplied, it is assummed that black pixels will stay black.

Parameters:
imageData binary pass-by-reference image to be converted
r Value of Red to apply to black pixels. DL_BLACK (No red) is default.
g Value of Green to apply to black pixels. DL_BLACK (No green) is default.
b Value of Blue to apply to black pixels. DL_BLACK (No blue) is default.
Returns:
color DLImage

static DLImage DLBitsPerPixelConverter::dlConvertImage ( const DLImage imageData,
DLImageConversions  conversionCode 
) [static]

Image Conversion upscaling routine that is useful when an image needs to be converted to a specific image domain (binary, grayscale, color) without knowledge of its current state. However, because of the ambiguity of upscaling routines, this function will only work in up-scaling conversion (ie. binary2gray, gray2color, binary2color,etc). Otherwise, an exception will be thrown asking the user to invoke an appropriate downscaling routine (downscale_global, downscalePercentThreshold, etc)

Parameters:
imageData image to convert
conversionCode code
Returns:
converted DLImage object

static DLImage DLBitsPerPixelConverter::dlDownscaleGray2Binary_global ( const DLImage imageData,
int  th = static_cast< int >(DL_WHITE/2) 
) [static]

Convert grayscale to binary using a threshold value.

Parameters:
imageData image to convert
th Threshold value. Pixels with gray value above which will be assigned to white; pixels with lower gray levels will be made black. Threshold value must be in the range of 0-255.
Returns:
binary DLImage

static DLImage DLBitsPerPixelConverter::dlDownscaleGray2Binary_niblack ( const DLImage gImg,
DL_BINARIZE_TYPE  algorithm = (DL_BINARIZE_TYPE) DL_ADANIBLACK,
double  k = -0.5,
bool  detect_inverted = true 
) [static]

Convert grayscale to binary using some variation of the local thresholding method proposed by Niblack in 1986. The current implementation of this function permits the calling routine to specify one of four algorithms to binarize the image: the original Niblack method, the 1997 method of Sauvola, the 2002 method of Wolf and Jolion, or an adaptive Niblack method developed locally as part of Doclib.

Niblack's original method sets a threshold at $T = \mu + k\sigma $, where $\mu$ and $\sigma$ are the mean and standard deviation values of the gray levels in a local window. Typical k-values are around -0.5.

Sauvola's method (as coded here) adjusts for background regions by setting $T = \mu (1 + k (1 - \sigma/128) ) $. Typical k-values are also around -0.5.

The method of Wolf and Jolion is a bit more complicated, but essentially sets the threshold based on local and global measures of contrast. It has a gain parameter. For consistency with the other methods, we have coded this so that the gain should typically be negative for dark text on a light background (this is different than the formula as published by Wolf and Jolion).

The adaptive Niblack algorithm adjusts the binarization threshold based on (1) bimodal areas of the document, (2) areas of low contrast, and (3) background.

The algorithm was arrived at through "experimentation" on a large collection of varied documents, and also on some scene images. Another feature included in this function is the detection of inverted text (light text on a darker background) versus normal text. The function detects such regions and adjusts for them, which is something not covered by the traditional published methods. To turn off this detection and adjustment, set the detect_inverted parameter to false.

Parameters:
gImg Gray image to be converted
algorithm One of DL_NIBLACK, DL_SAUVOLA, DL_WOLFJOLION, or DL_ADANIBLACK (default)
k The adjustment/gain parameter for each method. Default is k = -0.5
detect_inverted Boolean value indicating whether to detect and adjust for inverted text (default) or not to
Returns:
binary DLImage
Deprecated:
Use DLBitsPerPixelConverter::dlDownscaleGray2Binary_niblack (const DLImage &, DLBitsPerPixelConverter::DLBinarizeType, double, bool) instead
This is in Phase One of the Documented Deprecation Process

static DLImage DLBitsPerPixelConverter::dlDownscaleGray2Binary_niblack ( const DLImage gImg,
DLBitsPerPixelConverter::DLBinarizeType  algorithm,
double  k = -0.5,
bool  detect_inverted = true 
) [static]

Convert grayscale to binary using some variation of the local thresholding method proposed by Niblack in 1986. The current implementation of this function permits the calling routine to specify one of four algorithms to binarize the image: the original Niblack method, the 1997 method of Sauvola, the 2002 method of Wolf and Jolion, or an adaptive Niblack method developed locally as part of Doclib.

Niblack's original method sets a threshold at $T = \mu + k\sigma $, where $\mu$ and $\sigma$ are the mean and standard deviation values of the gray levels in a local window. Typical k-values are around -0.5.

Sauvola's method (as coded here) adjusts for background regions by setting $T = \mu (1 + k (1 - \sigma/128) ) $. Typical k-values are also around -0.5.

The method of Wolf and Jolion is a bit more complicated, but essentially sets the threshold based on local and global measures of contrast. It has a gain parameter. For consistency with the other methods, we have coded this so that the gain should typically be negative for dark text on a light background (this is different than the formula as published by Wolf and Jolion).

The adaptive Niblack algorithm adjusts the binarization threshold based on (1) bimodal areas of the document, (2) areas of low contrast, and (3) background.

The algorithm was arrived at through "experimentation" on a large collection of varied documents, and also on some scene images. Another feature included in this function is the detection of inverted text (light text on a darker background) versus normal text. The function detects such regions and adjusts for them, which is something not covered by the traditional published methods. To turn off this detection and adjustment, set the detect_inverted parameter to false.

Parameters:
gImg Gray image to be converted
algorithm One of
k The adjustment/gain parameter for each method. Default is k = -0.5
detect_inverted Boolean value indicating whether to detect and adjust for inverted text (default) or not to
Returns:
binary DLImage

static DLImage DLBitsPerPixelConverter::dlDownscaleColor2Gray_global ( const DLImage imageData  )  [static]

Convert color DLImage into gray DLImage by averaging the R-G-B color band values and assigning to the grayscale(DL_BYTE) domain.

Parameters:
imageData Image passed in by reference that is to be converted.
Returns:
downscaled grayscale image

static DLImage DLBitsPerPixelConverter::dlDownscaleColor2Gray_weighted ( const DLImage cImg,
float  rWt,
float  gWt,
float  bWt 
) [static]

Convert color DLImage into gray DLImage by applying a specific weight to each of the R-G-B color bands. The value for each of the color bands is multiplied by its weight. These values are summed to produce the output gray value, which is scaled to be in the range [0, 255]. The weights must each be greater than 0.

Parameters:
cImg Color image to be converted
rWt Weight to use for the red channel
gWt Weight to use for the green channel
bWt Weight to use for the blue channel
Returns:
grayscale DLImage

static DLImage DLBitsPerPixelConverter::dlDownscaleColor2Binary_threshold ( const DLImage tImg,
int  rThresh = 100,
int  gThresh = 100,
int  bThresh = 100 
) [static]

Threshold Binarization.

Parameters:
tImg color image passed in by reference to downscale to binary
rThresh Threshold to use for the red channel
gThresh Threshold to use for the green channel
bThresh Threshold to use for the blue channel
Returns:
binary DLImage

static DLImage DLBitsPerPixelConverter::dlDownscaleColor2Binary_percentThreshold ( const DLImage tImg,
double  percent 
) [static]

Percent Threshold Binarization. Binarizes based upon the range of values within each color band:

Parameters:
tImg image that is passed in by reference that is to be converted
percent threshold in decimal form (0--1)
Returns:
binary DLImage

static DLImage DLBitsPerPixelConverter::dlDownscalePercentThresholdBinarization ( const DLImage tImg,
int  percent 
) [static]

Percent Threshold Binarization. Binarizes based upon the range of values within each color band:

Parameters:
tImg image that is passed in by reference that is to be converted
percent threshold as a percentage (0-100)
Returns:
binary DLImage

static DLImage DLBitsPerPixelConverter::dlDownscale256Color_global ( const DLImage image_in,
bool &  quantized 
) [static]

Convert high color DLImage into 256 color DLImage

Parameters:
[in] image_in image to convert
[out] quantized 
  • true indicates that the original image did in fact use more than 256 colors, and that therefore color quantization was performed.
  • false indicates that the original image used fewer than 256 colors, and therefore the output image is identical to the input image.
Returns:
256-color DLImage

static DLImage DLBitsPerPixelConverter::dlDownscaleYCrCbBinarization ( const DLImage tImg  )  [static]

YCrCb Binarization.

Parameters:
tImg to be processed
Returns:
binary DLImage


The documentation for this class was generated from the following file:

DOCLIB is being developed under contract by a collaboration between:
The Laboratory for Language and Media Processing
Unviersity of Maryland, College Park
and
Booz | Allen | Hamilton

All Rights Reserved, 2003-2007