ErrorDiffusionDithererConfigureErrorDiffusionMode Method

KGy SOFT Drawing Libraries Help
Gets a new ErrorDiffusionDitherer instance that has the specified error diffusion mode.
See the Remarks section for details.

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

public ErrorDiffusionDitherer ConfigureErrorDiffusionMode(
	Nullable<bool> byBrightness
)

Parameters

byBrightness
Type: SystemNullableBoolean
 to apply the same quantization error on every color channel determined by brightness difference;  to handle quantization errors on each color channels independently;  to auto select strategy. Deciding by brightness can produce a better result when fully saturated colors are mapped to a grayscale palette.

Return Value

Type: ErrorDiffusionDitherer
A new ErrorDiffusionDitherer instance that has the specified error diffusion mode.
Remarks

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

Calculation of the quantization error may happen in two ways. The publicly available algorithms usually calculate the error for each color channels, which usually provides good results with color palettes. However, when quantizing color images with a black and white or grayscale palette, this approach may fail. For example, if the quantizer returns black for a fully saturated blue pixel, the quantization error is zero on the red and green channels and 100% on the blue channel. The problem is that this error cannot be propagated to the neighboring pixels if they have the same color because adding any more blue to already fully saturated blue pixels will not change anything. Therefore, the ErrorDiffusionDitherer can propagate quantization error by brightness based on human perception, which is more appropriate for palettes with grayscale colors.

The following table demonstrates the effect of different strategies:

Original imageQuantized image

Color hues with alpha gradient
Color hues with alpha gradient

Color hues with system default 8 BPP palette, silver background and Floyd-Steinberg dithering, using error diffusion by RGB channels
Quantizing with system default 8 BPP palette and Floyd-Steinberg dithering, using error diffusion by RGB channels (the default strategy for non-grayscale palettes)

Color hues with system default 8 BPP palette, silver background and Floyd-Steinberg dithering, using error diffusion by brightness
Quantizing with system default 8 BPP palette and Floyd-Steinberg dithering, using error diffusion by brightness

Color wheel
Color wheel

Color wheel with black and white palette, blue background and Floyd-Steinberg dithering, using error diffusion by brightness (the default strategy for grayscale palettes)
Quantizing with black and white palette and Floyd-Steinberg dithering, using blue background and error diffusion by brightness (the default strategy for grayscale palettes). All colors appear in the result with different patterns.

Color wheel with black and white palette, blue background and Floyd-Steinberg dithering, using error diffusion by RGB channels
Quantizing with black and white palette and Floyd-Steinberg dithering, using blue background and error diffusion by RGB channels. The fully saturated colors turned completely black or white.

Examples

The following example demonstrates how to specify the error diffusion mode for a predefined filter:
C#
// getting a predefined ditherer that disperses quantization error by brightness:
IDitherer ditherer = ErrorDiffusionDitherer.FloydSteinberg.ConfigureErrorDiffusionMode(byBrightness: true);
See Also

Reference