PredefinedColorsQuantizerFromCustomPalette Method (Color, Color, Byte)

KGy SOFT Drawing Libraries Help
Gets a PredefinedColorsQuantizer instance that quantizes colors using the colors in the specified palette.
See the Remarks section for details and some examples.

Namespace:  KGySoft.Drawing.Imaging
Assembly:  KGySoft.Drawing (in KGySoft.Drawing.dll) Version: 5.1.0
Syntax

public static PredefinedColorsQuantizer FromCustomPalette(
	Color[] palette,
	Color backColor = null,
	byte alphaThreshold = 128
)

Parameters

palette
Type: System.DrawingColor
The array of colors to be used by the returned instance.
backColor (Optional)
Type: System.DrawingColor
Colors with alpha (transparency), which are considered opaque will be blended with this color before quantization. The Color.A property of the background color is ignored. This parameter is optional.
Default value: Empty, which has the same RGB values as Black.
alphaThreshold (Optional)
Type: SystemByte
If the specified palette contains a transparent color, then specifies a threshold value for the Color.A property, under which a quantized color is considered transparent. If 0, then the quantized colors will never be transparent. This parameter is optional.
Default value: 128.

Return Value

Type: PredefinedColorsQuantizer
A PredefinedColorsQuantizer instance that quantizes colors using the colors in the specified palette.
Remarks

The PredefinedColorsQuantizer instance returned by this method will use a Palette internally, created from the colors specified in the palette parameter. When quantizing, best matching colors might be looked up sequentially and results might be cached.

If a color to be quantized can be mapped to a color index directly, then create a Palette instance explicitly, specifying the custom mapping logic and use the FromCustomPalette(Palette) overload instead.

If a color to be quantized can be transformed to a result color directly, and the quantized result is not needed to be an indexed image, then use the FromCustomFunction overloads instead.

Examples

The following example demonstrates how to use the quantizer returned by this method:
C#
public static Bitmap ToRgb111(Bitmap source, Color backColor = default, IDitherer ditherer = null)
{
    Color[] colors =
    {
        Color.Black, Color.Red, Color.Lime, Color.Blue,
        Color.Magenta, Color.Yellow, Color.Cyan, Color.White
    };

    IQuantizer quantizer = PredefinedColorsQuantizer.FromCustomPalette(colors, backColor);
    // or: quantizer = PredefinedColorsQuantizer.FromCustomPalette(new Palette(colors, backColor));

    // a.) this solution returns a new bitmap and does not change the original one:
    return source.ConvertPixelFormat(PixelFormat.Format4bppIndexed, quantizer, ditherer);

    // b.) alternatively, you can perform the quantization directly on the source bitmap:
    if (ditherer == null)
        source.Quantize(quantizer);
    else
        source.Dither(quantizer, ditherer);
    return source;
}

The example above may produce the following results:

Original imageQuantized image

Color hues with alpha gradient
Color hues with alpha gradient

Color hues with RGB111 palette and black background
Default optional parameter values (black background). The bottom half of the result is black.

Color hues with RGB111 palette and silver background
Silver background. The bottom part of the result is white.

Color hues with RGB111 palette and silver background, using Bayer 8x8 ordered dithering
Silver background, Bayer 8x8 dithering

Grayscale color shades with different bit depths
Grayscale color shades

Grayscale color shades with RGB111 palette
Default optional parameter values

Grayscale color shades with RGB111 palette, using Bayer 8x8 ordered dithering
Bayer 8x8 dithering

Shield icon with transparent background
Shield icon with transparency

Shield icon with RGB111 palette and black background
Default optional parameter values (black background)

Shield icon with RGB111 palette and silver background
Silver background

Shield icon with RGB111 palette, silver background, using Floyd-Steinberg dithering
Silver background, Floyd-Steinberg dithering

Test image "Lena"
Original test image "Lena"

Test image "Lena" with RGB111 palette
Default optional parameter values

Test image "Lena" with RGB111 palette and Floyd-Steinberg dithering
Floyd-Steinberg dithering

See Also

Reference