OptimizedPaletteQuantizer Class

KGy SOFT Drawing Libraries Help
Represents a quantizer that can generate an optimized set of colors best matching to the original image. Use the static methods to retrieve an instance. For using predefined colors see the PredefinedColorsQuantizer class.
See the Remarks section for details and results comparison.
Inheritance Hierarchy

SystemObject
  KGySoft.Drawing.ImagingOptimizedPaletteQuantizer

Namespace:  KGySoft.Drawing.Imaging
Assembly:  KGySoft.Drawing.Core (in KGySoft.Drawing.Core.dll) Version: 7.0.0-preview.2
Syntax

public sealed class OptimizedPaletteQuantizer : IQuantizer

The OptimizedPaletteQuantizer type exposes the following members.

Properties

  NameDescription
Public propertyPixelFormatHint
Gets a KnownPixelFormat, which is compatible with this OptimizedPaletteQuantizer instance.
Top
Methods

  NameDescription
Public methodConfigureBitLevel
Configures the bit level per color channel to be used while optimizing the palette. If the input image is a monochromatic one, then may determine the bit depth of the result, depending on the used algorithm. Affects the quality, speed and memory usage.
See the Remarks section for details.
Public methodStatic memberCode exampleMedianCut
Gets an OptimizedPaletteQuantizer instance that quantizes colors of an image using the Median Cut quantizing algorithm.
See the Examples section for an example, and the Remarks section of the OptimizedPaletteQuantizer for details and results comparison with the other algorithms.
Public methodStatic memberCode exampleOctree
Gets an OptimizedPaletteQuantizer instance that quantizes colors of an image using the Octree quantizing algorithm.
See the Examples section for an example, and the Remarks section of the OptimizedPaletteQuantizer for details and results comparison with the other algorithms.
Public methodStatic memberCode exampleWu
Gets an OptimizedPaletteQuantizer instance that quantizes colors of an image using Xiaolin Wu's quantizing algorithm.
See the Examples section for an example, and the Remarks section of the OptimizedPaletteQuantizer for details and results comparison with the other algorithms.
Top
Extension Methods

  NameDescription
Public Extension MethodInitializeAsync
Gets an IQuantizingSession instance potentially asynchronously that can be used to quantize the colors of the specified IReadableBitmapData instance. If quantizer is a known quantizer that can be evaluated quickly, then this method might be executed synchronously.
This method is available in.NET Framework 4.0 and above.
(Defined by QuantizerExtensions.)
Top
Remarks

The OptimizedPaletteQuantizer class can be used to reduce colors of an IReadableBitmapData using a palette of up to 65536 colors where the palette entries are optimized for the quantized image.

Note Note
Though more than 256 colors are supported, the typical goal of palette optimization is to adjust the colors for an indexed pixel format. Natively supported indexed formats cannot have more than 256 colors, though you are allowed to create images with custom pixel format by using the BitmapDataFactory.CreateBitmapData methods that have PixelFormatInfo parameters. Please note though that a large palette may have impact on both memory usage and performance.

This class supports palette optimization by three different algorithms (see the Octree, MedianCut and Wu methods)

The following table compares the algorithms supported by the OptimizedPaletteQuantizer class:

OctreeMedianCutWu
SpeedWith default settings usually slower than the Wu's algorithm but faster than MedianCut. When using high bit levels and the source is a true color image, then it is generally faster for high requested colors, and can be faster even than Wu's algorithm using the same bit level.In most cases this is the slowest one of the three algorithms, especially for larger images.With default settings this is almost always the fastest one of the three algorithms (still much slower though than the quantizers of the PredefinedColorsQuantizer class). When using high bit levels it can be the slowest one for small images and gets to be the fastest one for larger image sizes.
Memory consumption*Generating the palette may consume quite a large amount of memory but it also depends on the number of different colors of the source image and the requested color count. The memory is continuously allocated on demand and in extreme cases it may consume a huge amount of memory. The memory usage can be limited by the ConfigureBitLevel method.The memory usage mainly depends on the image size and somewhat on the requested color count. Quantizing a large image may consume a large amount of memory even if the image itself consist of just a few colors.This quantizer consumes a fairly large fix amount of memory, even if the source has few colors and the requested color count is small. Most of the memory is allocated at once, regardless of the image size or its actual colors, and a smaller portion is allocated dynamically, which depends on the number of requested colors. On platforms where available, array pooling is used, which releases the used memory only after a while if the buffers are not re-used within a time interval. The memory usage can be adjusted by the ConfigureBitLevel method.
Quality
  • Usually poorer quality for smaller palettes (below 16 colors).
  • Banding may appear in images with large low-frequency areas (eg. sky or water in photos).
  • Balanced quality for larger palettes and photo-like images.
  • Usually better quality for smaller palettes.
  • Excellent, nearly banding-free results with images with large low-frequency areas (eg. sky or water in photos).
  • May provide poorer quality for small areas with unique colors (eg. a smaller human face in a large photo).
  • Usually very good quality even for smaller palettes.
  • Banding may appear in images with large low-frequency areas (eg. sky or water in photos). By default, banding may appear for monochromatic images even if the requested number of colors would allow a banding-free result but this can be configured by the ConfigureBitLevel method.
  • Very good quality for photo-like images, especially if the image has no homogeneous low-frequency areas.
Note Note

*Memory consumption mentioned in the table affects palette generation only. That occurs when the IQuantizer.Initialize method of an OptimizedPaletteQuantizer instance is called. As soon as this method returns with an IQuantizingSession instance, the memory mentioned in the table can be reclaimed (which does not necessarily happen immediately on platforms that support array pooling, which is utilized by the Wu's algorithm).

On the other hand, the IQuantizingSession can also consume a large amount of memory during the quantization because its Palette caches the quantization results of the source image pixels, though this caching does not depend on the chosen algorithm and the used memory can also be reclaimed when the IQuantizingSession is disposed.

Keeping a reference to an OptimizedPaletteQuantizer consumes almost no memory when there is no active quantization session in progress.

The following table compares the results of the OptimizedPaletteQuantizer instances returned by the Octree, MedianCut and Wu methods.

Note Note
For better comparison none of the images are dithered in the examples, though the visual quality can be improved by using dithering. See the OrderedDitherer, ErrorDiffusionDitherer, RandomNoiseDitherer and InterleavedGradientNoiseDitherer classes for some built-in IDitherer implementations.
Original imageQuantized image

Color hues with alpha gradient
Color hues with alpha gradient

Color hues quantized by Octree algorithm using 256 colors, silver background, zero alpha threshold
Octree algorithm, 256 colors, silver background, zero alpha threshold

Color hues quantized by Median Cut algorithm using 256 colors, silver background, zero alpha threshold
MedianCut algorithm, 256 colors, silver background, zero alpha threshold

Color hues quantized by Wu's algorithm using 256 colors, silver background, zero alpha threshold
Wu's algorithm, 256 colors, silver background, zero alpha threshold

Information icon with transparent background
Information icon with transparency

Information icon quantized by Octree algorithm using 4 colors, silver background, zero alpha threshold
Octree algorithm, 4 colors, silver background, zero alpha threshold

Information icon quantized by Median Cut algorithm using 4 colors, silver background, zero alpha threshold
MedianCut algorithm, 4 colors, silver background, zero alpha threshold

Information icon quantized by Wu's algorithm using 4 colors, silver background, zero alpha threshold
Wu's algorithm, 4 colors, silver background, zero alpha threshold

Information icon quantized by Octree algorithm using 256 colors, black background, alpha threshold = 128
Octree algorithm, 256 colors, black background, alpha threshold = 128. Banding appeared in the result.

Information icon quantized by Median Cut algorithm using 256 colors, black background, alpha threshold = 128
MedianCut algorithm, 256 colors, black background, alpha threshold = 128. Practically there is no banding in the result.

Information icon quantized by Wu's algorithm using 256 colors, black background, alpha threshold = 128
Wu's algorithm, 256 colors, black background, alpha threshold = 128. A slight banding can be observed, as if the source image had been prequantized by the PredefinedColorsQuantizer.Argb1555 quantizer first. You get this result if you use the ConfigureBitLevel method with 5 bits (which is the default for Wu with 256 colors). The banding can be reduced by using higher bit levels, which increases also memory usage and processing time.

See Also

Reference