ImageExtensionsConvertPixelFormat Method (Image, PixelFormat, IQuantizer, IDitherer)

KGy SOFT Drawing Libraries Help
Converts the specified image to a Bitmap with the desired PixelFormat.
See the Remarks section for details.

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

public static Bitmap ConvertPixelFormat(
	this Image image,
	PixelFormat newPixelFormat,
	IQuantizer quantizer,
	IDitherer ditherer = null
)

Parameters

image
Type: System.DrawingImage
The original image to convert.
newPixelFormat
Type: System.Drawing.ImagingPixelFormat
The desired new pixel format.
quantizer
Type: KGySoft.Drawing.ImagingIQuantizer
An optional IQuantizer instance to determine the conversion of the colors. If  and newPixelFormat is an indexed format, then a default palette and quantization logic will be used.
ditherer (Optional)
Type: KGySoft.Drawing.ImagingIDitherer
An optional IDitherer instance for dithering the result image, which usually produces a better result if colors are quantized. If quantizer is , then this parameter is ignored. This parameter is optional.
Default value: .

Return Value

Type: Bitmap
A new Bitmap instance with the desired pixel format.

Usage Note

In Visual Basic and C#, you can call this method as an instance method on any object of type Image. When you use instance method syntax to call this method, omit the first parameter. For more information, see Extension Methods (Visual Basic) or Extension Methods (C# Programming Guide).
Exceptions

ExceptionCondition
ArgumentNullExceptionimage is .
ArgumentOutOfRangeExceptionnewPixelFormat is out of the defined values.
ArgumentExceptionThe quantizer palette contains too many colors for the indexed format specified by newPixelFormat.
PlatformNotSupportedExceptionnewPixelFormat is not supported on the current platform.
Remarks

An unmatching quantizer and newPixelFormat may cause undesired results.

The ditherer may have no effect if the quantizer uses too many colors.

To use a quantizer with predefined colors you can use the PredefinedColorsQuantizer class. If you want to use a quantizer without a ditherer and newPixelFormat represents the same number of reduced colors as the quantizer produces, then you can use the ConvertPixelFormat(Image, PixelFormat, Color, Color, Byte) overload for a slightly better performance.

To produce a result with up to 256 colors best optimized for the source image you can use the OptimizedPaletteQuantizer class.

To quantize a Bitmap in place, without changing the pixel format you can use the BitmapExtensions.Quantize method.

To dither a Bitmap in place, without changing the pixel format you can use the BitmapExtensions.Dither method.

Note Note
For information about the possible usable PixelFormats on different platforms see the Remarks section of the ConvertPixelFormat(Image, PixelFormat, Color, Byte) overload.
Examples

The following example demonstrates the possible results of this method:
C#
using (Bitmap original = Icons.Shield.ExtractBitmap(new Size(256, 256)))
{
    // The original bitmap has 32 bpp color depth with transparency
    original.SaveAsPng(@"c:\temp\original.png");

    // Specifying a custom palette of 8 colors
    Color[] palette =
    {
        Color.Black, Color.Red, Color.Lime, Color.Blue,
        Color.Magenta, Color.Yellow, Color.Cyan, Color.White
    };

    // Using the custom palette without dithering
    using (Bitmap converted8Bpp = original.ConvertPixelFormat(PixelFormat.Format8bppIndexed,
        PredefinedColorsQuantizer.FromCustomPalette(palette, Color.Silver)))
    {
        converted8Bpp.SaveAsGif(@"c:\temp\8bpp custom palette.gif");
    }

    // Using the custom palette with Floyd-Steinberg dithering
    using (Bitmap converted8Bpp = original.ConvertPixelFormat(PixelFormat.Format8bppIndexed,
        PredefinedColorsQuantizer.FromCustomPalette(palette, Color.Silver), ErrorDiffusionDitherer.FloydSteinberg))
    {
        converted8Bpp.SaveAsGif(@"c:\temp\8bpp custom palette with dithering.gif");
    }

    // Using the system default palette without dithering
    using (Bitmap converted8Bpp = original.ConvertPixelFormat(PixelFormat.Format8bppIndexed,
        PredefinedColorsQuantizer.SystemDefault8BppPalette()))
    {
        converted8Bpp.SaveAsGif(@"c:\temp\8 bpp default palette.gif");
    }

    // Using the system default palette with Bayer 8x8 dithering
    using (Bitmap converted8Bpp = original.ConvertPixelFormat(PixelFormat.Format8bppIndexed,
        PredefinedColorsQuantizer.SystemDefault8BppPalette(), OrderedDitherer.Bayer8x8))
    {
        converted8Bpp.SaveAsGif(@"c:\temp\8 bpp default palette with dithering.gif");
    }

    // Using an optimized palette without dithering
    using (Bitmap converted8Bpp = original.ConvertPixelFormat(PixelFormat.Format8bppIndexed,
        OptimizedPaletteQuantizer.MedianCut()))
    {
        converted8Bpp.SaveAsGif(@"c:\temp\8 bpp optimized palette.gif");
    }

    // Using an optimized palette with blue noise dithering
    using (Bitmap converted8Bpp = original.ConvertPixelFormat(PixelFormat.Format8bppIndexed,
        OptimizedPaletteQuantizer.MedianCut(), OrderedDitherer.BlueNoise))
    {
        converted8Bpp.SaveAsGif(@"c:\temp\8 bpp optimized palette with dithering.gif");
    }

    // Converting to black-and-white without dithering.
    // Alpha pixels will be blended with Color.Silver, which will be white in the result.
    using (Bitmap converted1Bpp = original.ConvertPixelFormat(PixelFormat.Format1bppIndexed,
        PredefinedColorsQuantizer.BlackAndWhite(Color.Silver)))
    {
        converted1Bpp.SaveAsTiff(@"c:\temp\black and white.tiff");
    }

    // Converting to black-and-white with Floyd-Steinberg dithering
    // Alpha pixels will be blended with Color.Silver, which also affects the result.
    using (Bitmap converted1Bpp = original.ConvertPixelFormat(PixelFormat.Format8bppIndexed,
        PredefinedColorsQuantizer.BlackAndWhite(Color.Silver), ErrorDiffusionDitherer.FloydSteinberg))
    {
        converted1Bpp.SaveAsTiff(@"c:\temp\black and white with dithering.tiff");
    }
}

The example above produces the following results:

original.png32 BPP shield icon with transparent background
8bpp custom palette.gif8-color (RGB111) shield icon with silver background. Without dithering the background turned white.
8bpp custom palette with dithering.gif8-color (RGB111) shield icon with silver background and Floyd-Steinberg dithering
8 bpp default palette.gif8 BPP shield icon with system default palette, black background and alpha threshold = 128
8 bpp default palette with dithering.gif8 BPP shield icon with system default palette, black background, alpha threshold = 128 and Bayer 8x8 dithering
8 bpp optimized palette.gif8 BPP shield icon with optimized palette using the Median Cut algorithm without dithering
8 bpp optimized palette with dithering.gif8 BPP shield icon with optimized palette using the Median Cut algorithm with blue noise dithering
black and white.tiff1 BPP shield icon with black and white palette and silver background. Without dithering the background turned white.
black and white with dithering.tiff1 BPP shield icon with black and white palette, silver background and Floyd-Steinberg dithering

Tip Tip
To reduce the number of colors of an image in-place, without changing its PixelFormat use the Quantize or Dither extension methods.

For built-in IQuantizer implementations see the PredefinedColorsQuantizer and OptimizedPaletteQuantizer classes.

For built-in IDitherer implementations see the OrderedDitherer, ErrorDiffusionDitherer, RandomNoiseDitherer and InterleavedGradientNoiseDitherer classes.

See Also

Reference