OrderedDitherer Constructor

KGy SOFT Drawing Libraries Help
Initializes a new instance of the OrderedDitherer class using the specified matrix and strength.
See the Examples section for some examples.

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

public OrderedDitherer(
	byte[,] matrix,
	float strength = 0f


Type: SystemByte
A matrix to be used as the coefficients of the dithering. Ideally contains every value between zero and the maximum value in the matrix. Repeated values will appear always together for the same input colors.
strength (Optional)
Type: SystemSingle
The strength of the dithering effect between 0 and 1 (inclusive bounds). Specify 0 to use an auto value for each dithering session based on the used quantizer.
See the Remarks section of the ConfigureStrength method for details about dithering strength. This parameter is optional.
Default value: 0.

ArgumentNullExceptionmatrix is .
ArgumentExceptionmatrix is empty.
ArgumentOutOfRangeExceptionstrength must be between 0 and 1, inclusive bounds.

The following example demonstrates how to use a custom ditherer using the OrderedDitherer constructor. It produces a similar dotted halftone pattern to the result of the DottedHalftone property but in a rectangular arrangement and with less different patterns:
public static IReadWriteBitmapData ToCustomDithered(IReadWriteBitmapData source, IQuantizer quantizer)
    // Using a dotted halftone pattern. As it uses only 11 values in a 7x7 matrix it is much less optimal
    // than the DottedHalftone property but demonstrates the behavior of the ordered dithering quite well.
    byte[,] matrix =
       {  0,  2,  4,  5,  4,  2,  1 },
       {  2,  3,  6,  7,  6,  3,  2 },
       {  4,  6,  8,  9,  8,  6,  4 },
       {  5,  7,  9, 10,  9,  7,  5 },
       {  4,  6,  8,  9,  8,  6,  4 },
       {  2,  3,  6,  7,  6,  3,  2 },
       {  1,  2,  4,  5,  4,  2,  1 },

    IDitherer ditherer = new OrderedDitherer(matrix);

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

    // b.) alternatively, you can perform the dithering directly on the source bitmap data:
    source.Dither(quantizer, ditherer);
    return source;

The example above may produce the following results:

Original imageQuantized and dithered image

Color hues with alpha gradient
Color hues with alpha gradient

Grayscale color shades with different bit depths
Grayscale color shades

Grayscale color shades with black and white palette using a custom dotted halftone dithering
Quantizing with black and white palette

Tip Tip
  • Use the static properties to perform dithering with predefined patterns.
  • See the Remarks section of the OrderedDitherer class for more details and image examples.
See Also