From d348e06f224aa056511665c5c466411efc18fee9 Mon Sep 17 00:00:00 2001 From: makeworld Date: Fri, 30 Apr 2021 19:43:35 -0400 Subject: [PATCH] Improve MANPAGE.md --- MANPAGE.md | 27 +++++++++++++++++++++++++++ Makefile | 2 +- 2 files changed, 28 insertions(+), 1 deletion(-) diff --git a/MANPAGE.md b/MANPAGE.md index 3330373..5040662 100644 --- a/MANPAGE.md +++ b/MANPAGE.md @@ -22,11 +22,13 @@ Homepage: # GLOBAL OPTIONS **-i**, **\--in** *PATH* + Set the input file. This flag can be used multiple times to dither multiple images with the same palette and method. A *PATH* of \'**\-**' stands for standard input. 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: **-o**, **\--out** *PATH* + Set the output file or directory. A *PATH* of \'**\-**' stands for standard output. 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. @@ -34,6 +36,7 @@ If *PATH* is an existing directory, then for each image input, an output file wi 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. **-p**, **\--palette** *COLORS* + Set the color palette used for dithering. Colors are entered as a single quoted argument, with each color separated by a space. Colors can be formatted as RGB tuples (comma separated), hex codes (case-insensitive, with or without the '#'), a single number from 0-255 for grayscale, or a color name from the SVG 1.1 spec (aka the HTML or W3C color names). All colors are interpreted in the sRGB colorspace. A list of all color names is available at @@ -41,6 +44,7 @@ A list of all color names is available at . 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. @@ -50,6 +54,7 @@ For these situations, **\--recolor** should usually be a palette made up of one 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. **-s**, **\--strength** *DECIMAL/PERCENT* + 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. 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%. @@ -57,54 +62,70 @@ Reducing the strength is often visibly similar to reducing contrast. With the ** 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. **-j**, **\--threads** *NUM* + Set the number of threads used. By default a thread will be created for each CPU. As dithering is a CPU-bound operation, going above this will not improve performance. This flag does not affect **edm**, as error diffusion dithering cannot be parallelized. **-g**, **\--grayscale** + Make input image(s) grayscale before dithering. **\--saturation** *DECIMAL/PERCENT* + Change input image(s) saturation before dithering. Decimal range is -1.0 to 1.0, percentage range is -100% or 100%. Values that exceed the range will be rounded down. -1.0 or -100% saturation is equivalent to **\--grayscale**. **\--brightness** *DECIMAL/PERCENT* + Change input image(s) saturation before dithering. Decimal range is -1.0 to 1.0, percentage range is -100% or 100%. Values that exceed the range will be rounded down. **\--contrast** *DECIMAL/PERCENT* + Change input image(s) saturation before dithering. Decimal range is -1.0 to 1.0, percentage range is -100% or 100%. Values that exceed the range will be rounded down. **\--no-exif-rotation** + Disable using the EXIF rotation flag in image metadata to rotate the image before processing. **-f**, **\--format** *FORMAT* + Set the output file format. Valid options are \'png' and \'gif'. It will auto detect from filename when possible, so usually this does not need to be set. If **-o** is \'**-**' or a directory, then PNG files will be outputted by default. So this flag can be used to force GIF output instead. If your output file has an extension that is not .png or .gif the format will need to be specified. **\--no-overwrite** + Setting this flag means the program will stop before overwriting an existing file. Any files written before that one was encountered will stay in place. **-c**, **\--compression** *TYPE* + Set the type of PNG compression. Options are \'default', \'no', \'speed', and \'size'. This flag is ignored for non-PNG output. **\--fps** *DECIMAL* + Set frames per second for animated GIF output. Note that not all FPS values can be represented by the GIF format, and so the closest possible one will be chosen. This flag has no default, and is required when animated GIFs are being outputted. This flag is ignored for non animated GIF output. **-l**, **\--loop** *NUM* + Set the number of times animated GIF output should loop. 0 is the default, and means infinite looping. **-x**, **\--width** *NUM* + Set the width the input image(s) will be resized to, before dithering. Aspect ratio will be maintained if **\--height** is not specified as well. **-y**, **\--height** *NUM* + Set the height the input image(s) will be resized to, before dithering. Aspect ratio will be maintained if **\--width** is not specified as well. **-u**, **\--upscale** *NUM* + Scale image up after dithering. So \'2' will make the output two times as big as the input (after **-x** and/or **-y**). Only integers are allowed, as scaling up by a non-integer amount would distort the dithering pattern and introduce artifacts. **-v**, **\--version** + Get version information. # COMMANDS **random** + \- grayscale and RGB random dithering 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. @@ -112,14 +133,17 @@ Accepts two arguments (min and max) for RGB or grayscale, or six (min/max for ea -0.5,0.5 is a good default. **-s**, **\--seed** *DECIMAL* + Set the seed for randomization. This will also only use one thread, to keep output deterministic. By default a different seed is chosen each time. **bayer** + \- Bayer matrix ordered dithering 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. **odm** + \- Ordered Dither Matrix Select or provide an ordered dithering matrix. This only takes one argument, but there a few types available: @@ -163,6 +187,7 @@ The JSON format (whether inline or in a file) looks like the below. The matrix m ``` **edm** + \- Error Diffusion Matrix Select or provide an error diffusion matrix. This only takes one argument, but there a few types available: @@ -190,6 +215,7 @@ Their names are case-insensitive, and hyphens and underscores are treated the sa 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. **-s**, **\--serpentine** + Enable serpentine dithering, which "snakes" back and forth when moving down the image, instead of going left-to-right each time. This can reduce artifacts or patterns in the noise. # TIPS @@ -212,6 +238,7 @@ To increase the dithering artifacts for aesthetic effect, you can downscale the **didder --palette 'black white' -i input.jpg -o test.png bayer 16x16** + This command dithers `input.jpg` to just use black and white (implicitly converting to grayscale first), using a 16x16 Bayer matrix. The result is written to `test.png`. TODO diff --git a/Makefile b/Makefile index f0a2f7a..0676b47 100644 --- a/Makefile +++ b/Makefile @@ -33,7 +33,7 @@ man: $(SED) -i 's/DATE/$(DATE)/g' didder.1 $(CP) didder.1.md MANPAGE.md $(SED) -i '1s/^/\n/' MANPAGE.md - $(SED) -i 's/: //g' MANPAGE.md + $(SED) -i 's/: /\n/g' MANPAGE.md $(SED) -i 's/ //g' MANPAGE.md $(SED) -i 's/^\[/ \[/g' MANPAGE.md