Image Dithering Options

Dithering can be used to create the illusion of color depth when there is a limited color palette. It can also give a blended or smoothing effect on transitions in a color to black and white image. Both of these are desirable in electronic ink displays that are either black and white only; or are very limited in their color palette. Omni-EPD has built in support for dithering, utilizing the tool didder. Be aware that some dithering algorithms take a lot of time to run on smaller systems, like a Raspberry Pi Zero.

For a more in-depth explanation of dithering, read this.

Applying Dithering

Applying a dithering algorithm to an image is done via the omni-epd.ini file. The selected algorithm will be applied to all images as they pass through Omni-EPD and are sent to the device. Valid options are listed in the table below. Several of them have additional arguments as well.

[Display]
dither=FloydSteinberg
dither_strength=1.0
dither_serpentine=False

Ordered	Error-Diffusion	Other
Bayer	Simple2D	Random
ClusteredDotDiagonal8x8	FloydSteinberg
Vertical5x3	FalseFloydSteinberg
Horizontal3x5	JarvisJudiceNinke
ClusteredDotDiagonal6x6	Atkinson
ClusteredDotDiagonal8x8_2	Stucki
ClusteredDotDiagonal16x16	Burkes
ClusteredDot6x6	Sierra
ClusteredDotSpiral5x5	TwoRowSierra
ClusteredDotHorizontalLine	SierraLite
ClusteredDotVerticalLine	StevenPigeon
ClusteredDot4x4	CustomDiffusion
ClusteredDot8x8
ClusteredDot6x6_2
ClusteredDot6x6_3
ClusteredDotDiagonal8x8_3
CustomOrdered

Additional Options - taken from the didder manual page

dither_strength Set the strength of dithering. This will affect every command except random. Decimal format is -1.0 to 1.0, and percentage format is -100% or 100%. The range is not limited. A zero value will be ignored. Defaults to 100%, meaning that the dithering is applied at full strength.

dither_serpentine Enable serpentine dithering, which "snakes" back and forth when moving down the image, instead of going left-to-right each time. Default: False

Bayer

The Bayer algorithm has additional arguments that can be set.

dither_args Requires two arguments, for the X and Y dimension of the matrix. They can be separated by a space, comma, or x. Both arguments must be a power of two, with the exception of: 3x5, 5x3, and 3x3. Default: 4x4

Custom Diffusion

This allows you to provide your own error diffusion matrix.

dither_args JSON of a custom matrix, or a path to JSON file for your custom matrix. Zero values can be used to represent pixels that have already been processed. The current pixel is assumed to be the right-most zero value in the top row. Example:

# matrix examples
dither_args=[[0, 0, 0.4375], [0.1875, 0.3125, 0.0625]]
dither_args=[
              [0, 0, 0.4375],
              [0.1875, 0.3125, 0.0625]
            ]

# file example
dither_args=/path/to/file.json

Custom Ordered

This allows you to provide your own custom ordered dithering matrix. The matrix must be "rectangular", meaning each array must have the same length. More information how to use a custom matrix can be found here.

dither_args JSON of a custom matrix, or a path to JSON file for your custom matrix.

# matrix examples
dither_args={"matrix": [[12, 5, 6, 13], [4, 0, 1, 7], [11, 3, 2, 8], [15, 10, 9, 14]], "max": 16}
dither_args={
              "matrix": [
                [12, 5, 6, 13],
                [4, 0, 1, 7],
                [11, 3, 2, 8],
                [15, 10, 9, 14]
              ],
              "max": 16
            }

# file example
dither_args=/path/to/file.json

Random Noise

The random dithering option adds random noise to the image. The min and max arguments limit the range of the random noise.

dither_args Accepts two arguments (min and max) for RGB or grayscale, or six (min/max for each channel) to control each RGB channel. Arguments can be separated by commas or spaces. Default: -0.5,0.5