ImageGear for C and C++ on Windows v19.1 - Updated
IG_IP_color_reduce_to_bitonal
API Reference Guide > Core Component API Reference > Core Component Functions Reference > Image Processing Functions > IG_IP_color_reduce_to_bitonal

This function reduces the hIGear image from 24, 8, or 4 bpp to 1 bpp.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_IP_color_reduce_to_bitonal(
        HIGEAR hIGear, 
        const AT_MODE nOption, 
        const UINT nThreshold, 
        UINT nWeight1, 
        UINT nWeight2, 
        UINT nWeight3
);

Arguments:

Name Type Description
hIGear HIGEAR HIGEAR handle of image.
nOption const AT_MODE A constant of type AT_MODE, such as IG_REDUCE_BITONAL_AVE, that specifies what type of reduction to perform. See accucnst.h for the complete list.
nThreshold const UINT An integer value that specifies which pixel values will be changed to black, and which pixel values will be changed to white. Pixels with values greater than nThreshold will be changed to white, and pixels that have values less than nThreshold will be changed to black.
nWeight1 UINT These values are only used if nOption is set to IG_REDUCE_BITONAL_WEIGHTED. The range of values is 0 - 255. The default values are 255.
nWeight2 UINT The range of values is 0 - 255. The default values are 255.
nWeight3 UINT The range of values is 0 - 255. The default values are 255.

Return Value:

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

Supported Raster Image Formats:

Indexed RGB – 4, 8 bpp;
Grayscale – 4, 8 bpp;
RGB – 24 bpp.

Sample:

None

Example:

 
Copy Code
HIGEAR hIGear,      /* HIGEAR handle of input image   */
AT_ERRCOUNT nErrcount;   /* Returned count of errors  */
nErrcount = IG_IP_color_reduce_to_bitonal ( hIGear, IG_REDUCE_BITONAL_AVE, 100, 0, 0, 0 );

Remarks:

Set nOption to specify how to get the threshold value. If you set nOption to IG_REDUCE_BITONAL_WEIGHTED, you may also set the values of nWeight1, nWeight2, and nWeight3. These "weights" are used to determine how much influence the values of the red, green, or blue pixels will have on the reduction. For example, if nWeight1 (red)= 255, nWeight2 (green) = 0, nWeight3 (blue) = 0, the whole reduction will depend on the value of the red pixels. The green and blue pixel values will have "no weight."

IG_REDUCE_BITONAL_GRAYSCALE gives the most weight to the value of green. This optimizes for the perception of the human eye, in which blue is the hardest color to see, and therefore requires the least weight.

IG_REDUCE_BITONAL_AVE gives equal weight to all three pixel values.

Here are the formulas used by the three different reduction methods:

Use the nThreshold argument to set the threshold value for converting pixels to black or white. If the value, as calculated by one of the above reduction methods, is less than nThreshold, the pixels will be set to black; if it is greater or equal to nThreshold, the pixels will be set to white.

See also the section in entitled Color Reduction.