OrderedDithererConfigureStrength Method

Gets a new OrderedDitherer instance that has the specified dithering strength.

Definition

Namespace: KGySoft.Drawing.Imaging
Assembly: KGySoft.Drawing.Core (in KGySoft.Drawing.Core.dll) Version: 8.0.0-preview.1
C#
public OrderedDitherer ConfigureStrength(
	float strength
)

Parameters

strength  Single
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. The auto strength strategy can be specified by the ConfigureAutoStrengthMode method.

Return Value

OrderedDitherer
A new OrderedDitherer instance that has the specified dithering strength.

Remarks

  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 auto strength strategy itself can be specified by the ConfigureAutoStrengthMode method.

The following table demonstrates the effect of different strengths:

Original image
Quantized 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.

Grayscale color shades with system default 4 BPP palette using 8x8 ordered dithering with interpolated ato strength
Quantizing with system default 4 BPP palette and Bayer 8x8 dithering using Interpolated auto strength strategy. Now there is neither banding nor overdithering for black or white colors.

Example

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);

// getting a predefined ditherer with custom auto strength strategy:
ditherer = OrderedDitherer.Bayer8x8.ConfigureAutoStrengthMode(AutoStrengthMode.Interpolated);

Exceptions

ArgumentOutOfRangeExceptionstrength must be between 0 and 1, inclusive bounds.

See Also