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.2.1
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 colors if the result. If  and newPixelFormat is an indexed format, then a default palette and quantization logic will be used.
ditherer (Optional)
Type: KGySoft.Drawing.ImagingIDitherer
The ditherer to be used. Might be ignored if quantizer is not specified and newPixelFormat represents an at least 24 bits-per-pixel size. 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 does not specify a valid format.
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 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.
Tip Tip
To convert an image to any PixelFormat on any platform obtain an IReadWriteBitmapData from a Bitmap by the GetReadWriteBitmapData extension method and use the Clone extension methods.
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