ImageGear for C and C++ on Linux v19.10 - Updated
IG_IP_color_reduce_octree
API Reference Guide > Core Component API Reference > Core Component Functions Reference > Image Processing Functions > IG_IP_color_reduce_octree

This function reduces a 24-bit or 8-bit image to an 8-bit or 4-bit image, having the number of colors specified by nMaxColors.

Declaration:

 
Copy Code
AT_ERRCOUNT ACCUAPI IG_IP_color_reduce_octree ( 
        HIGEAR hIGear, 
        BOOL bFastRemap, 
        UINT nMaxColors, 
        const UINT nPaletteSize, 
        const LPAT_RGB lpPalette 
);

Arguments:

Name Type Description
hIGear HIGEAR HIGEAR handle of image.
bFastRemap BOOL Set = TRUE for reduction algorithm optimized for speed. Set = FALSE for algorithm optimized for quality.
nMaxColors UINT The maximum number of colors (that is, maximum number of unique pixel values) you want in the resulting image. If you set this to > 16, the resulting image will be an 8-bit. Valid values are 8 - 256. If you pass in a value out of this range, ImageGear will set the value to either 8 or 256. See description below for details.
nPaletteSize const UINT Number of entries in palette lpPalette that will be used by ImageGear during reduction. This should be >= nMaxColors. Setting this to 0, and setting lpPalette to NULL will have ImageGear make an optimized palette for you.
lpPalette const LPAT_RGB LONG pointer to an array of palette entries, where the number of entries = nPaletteSize. Set to NULL if you want ImageGear to make an optimized palette for you.

Return Value:

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

Supported Raster Image Formats:

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

Example:

 
Copy Code
HIGEAR hIGear;   /* HIGEAR handle of image   */
AT_RGB rgbPalette[64];  /* Pointer to image's palette */
AT_ERRCOUNT   nErrcount;    /* Tally of ImageGear errors on stack*/
/* Reduce image to 64 colors using given palette */
nErrcount = IG_IP_color_reduce_octree (hIGear, FALSE, 64, 64, rgbPalette);
/* Reduce image to 64 colors, having ImageGear build optimal palette  */
nErrcount = IG_IP_color_reduce_octree (hIGear, FALSE, 64, 0, NULL);

Remarks:

If you set nPaletteSize > 0 and supply an address to lpPalette, ImageGear will use your palette. If you set either nPaletteSize = 0 or lpPalette to NULL, ImageGear will build an optimized palette for you. If you set nMaxColors > 16, then an 8-bit image will always result. Setting nMaxColors <=16 will result in a 4-bit image. You may not specify less than 8 colors.

nPaletteSize should be set to >= nMaxColors. If nPaletteSize is set to 0, ImageGear will build an optimal palette and lpPalette will be unused. The table below demonstrates some sample cases of 8 and 24-bit images being reduced, using the setting of nMaxColors (middle column). The right-most column shows the number of Bits Per Pixel that the resulting image will have.

Octree Bit Depths In and Out

Bpp of orig. HIGEAR # of resulting colors Bpp reduced image
24 17-256 8
24 8-16 4
24 1-7 *
8 17-256 8
8 8-16 4
8 1-7 *

*Not possible, nMaxColors will be changed to 8

See also the section in entitled Color Reduction.