| DIDDER(1) | User Manual | DIDDER(1) |
didder — dither images
didder [global options] command [command options] [arguments...]
Dither images with a variety of algorithms and processing options.
Images with transparency are supported, and their alpha channel is kept the way it was to begin with.
Mandatory global flags are --palette, --in, and --out, all others are optional. Each command applies a dithering algorithm or set of algorithms to the input image(s).
The most important parts of this manual are highlighted in the TIPS section, make sure you check it out!
Homepage: https://github.com/makeworld-the-better-one/didder
The input file path can also be parsed as a glob. This will only happen if the path contains an asterisk. For example -i '*.jpg’ will select all the .jpg files in the current directory as input. See this page for more info on glob pattern matching: https://golang.org/pkg/path/filepath/#Match
If PATH is an existing directory, then for each image input, an output file with the same name (but possibly different extension) will be created in that directory.
If PATH is a file, that ends in .gif (or --format gif is set) then multiple input files will be combined into an animated GIF.
A list of all color names is available at https://www.w3.org/TR/SVG11/types.html#ColorKeywords
Images are converted to grayscale automatically if the palette is grayscale. This produces more correct results.
Here’s an example of all color formats being used: --palette '23,230,100 D24242 135 forestGreen’
The --recolor flag exists because when palettes that are severely limited in terms of RGB spread are used, accurately representing the image colors with the desired palette is impossible. Instead of accuracy of color, the new goal is accuracy of luminance, or even just accuracy of contrast. For example, the original Nintendo Game Boy used a solely green palette: https://en.wikipedia.org/wiki/List_of_video_game_console_palettes#Game_Boy. By setting --palette to shades of gray and then --recolor-ing to the desired shades of green, input images will be converted to grayscale automatically and then dithered in one dimension (gray), rather than trying to dither a color image (three dimensions, RGB) into a one dimensional green palette. This is similar to “hue shifting” or “colorizing” an image in image editing software.
For these situations, --recolor should usually be a palette made up of one hue, and --palette should be the grayscale version of that palette. The --palette could also be just equally spread grayscale values, which would increase the contrast but make the luminance inaccurate.
Recoloring can also be useful for increasing contrast on a strange palette, like: --palette 'black white’ --recolor 'indigo LimeGreen’. Setting just --palette 'indigo LimeGreen’ would give bad (low contrast) results because that palette is not that far apart in RGB space. These “bad results” are much more pronounced when the input image is in color, because three dimensions are being reduced.
Reducing the strength is often visibly similar to reducing contrast. With the edm command, --strength can be used to reduce noise, when set to a value around 80%.
When using the bayer command with a grayscale palette, usually 100% is fine, but for 4x4 matrices or smaller, you may need to reduce the strength. For bayer (and by extension odm) color palette images, several sites recommend 64% strength (written as 256/4). This is often a good default for bayer/odm dithering color images, as 100% will distort colors too much. Do not use the default of 100% for Bayer dithering color images.
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.
Random dithering adds random noise to the image. The min and max numbers limit the range of the random noise. A good default is -0.5,0.5, which means that a middle gray pixel is 50% likely to become black and 50% likely to become white, assuming a black and white palette. So -0.2,2.0 will reduce the noise (20%), while -0.7,0.7 will increase it (70%). Values like -0.5,0.7 will bias the noise to one end of the channel(s).
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.
Select or provide an ordered dithering matrix. This only takes one argument, but there a few types available:
Here are all the built-in ordered dithering matrices. You can find details on these matrices here: https://github.com/makeworld-the-better-one/dither/blob/v2.0.0/ordered_ditherers.go
Their names are case-insensitive, and hyphens and underscores are treated the same.
The JSON format (whether inline or in a file) looks like the below. 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: https://pkg.go.dev/github.com/makeworld-the-better-one/dither/v2#OrderedDitherMatrix
{
"matrix": [
[12, 5, 6, 13],
[4, 0, 1, 7],
[11, 3, 2, 8],
[15, 10, 9, 14]
],
"max": 16
}
Select or provide an error diffusion matrix. This only takes one argument, but there a few types available:
Here are all the built-in error diffusion matrices. You can find details on these matrices here: https://github.com/makeworld-the-better-one/dither/blob/v2.0.0/error_diffusers.go
Their names are case-insensitive, and hyphens and underscores are treated the same.
The JSON format (whether inline or in a file) for a custom matrix is very simple, just a 2D array. The matrix must be “rectangular”, meaning each array must have the same length.
Read about --strength if you haven’t already.
Read about --recolor if you haven’t already.
It’s easy to mess up a dithered image by scaling it manually. It’s best to scale the image to the size you want before dithering (externally, or with --width and/or --height), and then leave it.
If you need to scale it up afterward, use --upscale, rather than another tool. This will prevent image artifacts and blurring.
Be wary of environments where you can’t make sure an image will be displayed at 100% size, pixel for pixel. Make sure to at least use nearest-neighbor scaling, do your best to preserve sharp pixel edges.
Dithered images must only be encoded in a lossless image format. This is why the tool only outputs PNG and GIF.
To increase the dithering artifacts for aesthetic effect, you can downscale the image before dithering and upscale after. Like if the image is 1000 pixels tall, your command can look like didder –height 500 –upscale 2 [...]. Depending on the input image size and what final size you want, you can of course just upscale as well.
If your palette (original or recolor) is low-spread — meaning it doesn’t span much of the available shades of a single hue or the entire RGB space — you can use flags like --brightness, --contrast, and --saturation to improve the way dithered images turn out. For example, if your palette is dark, you can turn up the brightness. As mentioned above, these flags apply their transformations to the original image and will not adjust your selected palette colors.
Any bugs can be reported by creating an issue on GitHub: https://github.com/makeworld-the-better-one/didder
| December 20, 2023 | didder v1.3.0 |