ImageExtensionsConvertPixelFormat(Image, PixelFormat, IQuantizer, IDitherer) Method
Namespace: KGySoft.DrawingAssembly: KGySoft.Drawing (in KGySoft.Drawing.dll) Version: 7.2.0
public static Bitmap ConvertPixelFormat(
this Image image,
PixelFormat newPixelFormat,
IQuantizer? quantizer,
IDitherer? ditherer = null
)
<ExtensionAttribute>
Public Shared Function ConvertPixelFormat (
image As Image,
newPixelFormat As PixelFormat,
quantizer As IQuantizer,
Optional ditherer As IDitherer = Nothing
) As Bitmap
public:
[ExtensionAttribute]
static Bitmap^ ConvertPixelFormat(
Image^ image,
PixelFormat newPixelFormat,
IQuantizer^ quantizer,
IDitherer^ ditherer = nullptr
)
[<ExtensionAttribute>]
static member ConvertPixelFormat :
image : Image *
newPixelFormat : PixelFormat *
quantizer : IQuantizer *
?ditherer : IDitherer
(* Defaults:
let _ditherer = defaultArg ditherer null
*)
-> Bitmap
- image Image
- The original image to convert.
- newPixelFormat PixelFormat
- The desired new pixel format.
- quantizer IQuantizer
- An optional IQuantizer instance to determine the colors of the result.
If and newPixelFormat is an indexed format, then a default palette and quantization logic will be used.
- ditherer IDitherer (Optional)
- 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: .
BitmapA new
Bitmap instance with the desired pixel format.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).
- This method adjusts the degree of parallelization automatically, blocks the caller, and does not support cancellation or reporting progress. Use the BeginConvertPixelFormat(Image, PixelFormat, IQuantizer, IDitherer, AsyncConfig)
or ConvertPixelFormatAsync(Image, PixelFormat, IQuantizer, IDitherer, TaskConfig) (in .NET Framework 4.0 and above) methods for asynchronous call and to adjust parallelization, set up cancellation and for reporting progress.
- If quantizer is and newPixelFormat requires blending, then this method selects the working color space automatically.
To apply a specific color space use the GetReadableBitmapData(Bitmap, WorkingColorSpace, Color, Byte) on
a Bitmap instance, and then call the ToBitmap extension method.
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 a specified number of colors 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.
For information about the possible usable
PixelFormats on different platforms see the
Remarks section of the
ConvertPixelFormat(Image, PixelFormat, Color, Byte) overload.
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.
The following example demonstrates the possible results of this method:
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.png |  |
| 8bpp custom palette.gif |  |
| 8bpp custom palette with dithering.gif |  |
| 8 bpp default palette.gif |  |
| 8 bpp default palette with dithering.gif |  |
| 8 bpp optimized palette.gif |  |
| 8 bpp optimized palette with dithering.gif |  |
| black and white.tiff |  |
| black and white with dithering.tiff |  |
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.
