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

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

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

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

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

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