PredefinedColorsQuantizerFromCustomPalette(Color, Color, Byte) Method

Gets a PredefinedColorsQuantizer instance that quantizes colors using the colors in the specified palette.

Definition

Namespace: KGySoft.Drawing.Imaging
Assembly: KGySoft.Drawing.Core (in KGySoft.Drawing.Core.dll) Version: 8.0.0-preview.1
C#
public static PredefinedColorsQuantizer FromCustomPalette(
	Color[] palette,
	Color backColor = default,
	byte alphaThreshold = 128
)

Parameters

palette  Color
The array of colors to be used by the returned instance.
backColor  Color  (Optional)
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  Byte  (Optional)
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

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.

Example

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

    IQuantizer quantizer = PredefinedColorsQuantizer.FromCustomPalette(new Palette(colors, colorSpace, backColor));

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

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

The example above may produce the following results:

Original image
Quantized 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 "Girl with a Pearl Earring"
Original test image "Girl with a Pearl Earring"

Test image "Girl with a Pearl Earring" with RGB111 palette, quantized in the sRGB color space
Default optional parameter values

Test image "Girl with a Pearl Earring" with RGB111 palette, quantized in the sRGB color space using Floyd-Steinberg dithering
Floyd-Steinberg dithering

Test image "Girl with a Pearl Earring" with RGB111 palette, quantized in the linear color space
Linear color space

Test image "Girl with a Pearl Earring" with RGB111 palette, quantized in the linear color space using Floyd-Steinberg dithering
Linear color space, Floyd-Steinberg dithering

See Also