OrderedDithererConfigureStrength Method

KGy SOFT Drawing Libraries Help
Gets a new OrderedDitherer instance that has the specified dithering strength.
See the Remarks section for details.

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

public OrderedDitherer ConfigureStrength(
	float strength
)

Parameters

strength
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.

Return Value

Type: OrderedDitherer
A new OrderedDitherer instance that has the specified dithering strength.
Exceptions

ExceptionCondition
ArgumentOutOfRangeExceptionstrength must be between 0 and 1, inclusive bounds.
Remarks

Note Note
This method always returns a new OrderedDitherer instance instead of changing the strength of the original one. This is required for the static properties so they can return a cached instance.

If strength is too low, then banding may appear in the result in place of gradients in the original image; whereas if strength is too high, then dithering patterns may appear even in colors without quantization error (overdithering).

If strength is 0, then strength will be calibrated for each dithering session so that neither the black, nor the white colors will suffer from overdithering in the result. This is the default for OrderedDitherer instances returned by the static properties.

The following table demonstrates the effect of different strengths:

Original imageQuantized image

Grayscale color shades with different bit depths
Grayscale color shades

Grayscale color shades with system default 4 BPP palette
Quantizing with system default 4 BPP palette, no dithering. The asymmetry is due to the uneven distribution of gray shades of this palette.

Grayscale color shades with system default 4 BPP palette using Bayer 8x8 ordered dithering
Quantizing with system default 4 BPP palette and Bayer 8x8 dithering using auto strength. Darker shades have banding.

Grayscale color shades with system default 4 BPP palette using a stronger Bayer 8x8 ordered dithering
Quantizing with system default 4 BPP palette and Bayer 8x8 dithering using strength = 0.5. Now there is no banding but white suffers from overdithering.

Examples

The following example demonstrates how to specify the strength for a predefined ordered ditherer:
C#
// getting a predefined ditherer with custom strength:
IDitherer ditherer = OrderedDitherer.Bayer8x8.ConfigureStrength(0.5f);
See Also

Reference