dither 1.3.6

A ditherer for static images with a variety of color palettes
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135

# Dither 1.3.6


Inspired by: <http://www.tannerhelland.com/4660/dithering-eleven-algorithms-source-code/>
- [crate](https://crates.io/crates/dither)
- [documentation](https://docs.rs/dither/1.3.6/dither/)
- [repository](https://gitlab.com/efronlicht/dither)

## License: MIT

The test photo (`"bunny.png"`) was obtained under the creative common license and is in the public domain.

## installation

```bash
cargo install dither
```

## CLI help:


```bash
dither --help
```

## usage


```bash
dither INPUT [OUTPUT] [-v] [--dither="floyd"] [--color="bw"] [--depth="1"] [--help]
```

## examples


    # no-op
![bunny](bunny.png)

    dither bunny.png burkes.png --dither=burkes

![burkes](burkes.png)

    dither bunny.png crayon.png --color=crayon
![crayon](crayon.png)


# Args 


## `INPUT`


the path to an input image. known good image formats are `.png` and `.jpg`.

## `OUTPUT`


the path to write the output. this will create or truncate the file at the existing location, if necessary. the image type will be inferred from the filename. currently, only `.png` and `.jpg` are supported.

## `-c`, `--color`


The color mode to use. Default is "bw" (black and white). 
Available options are
- bw (default)
- color
- cga
- crayon
- $COLOR
- $FILENAME

### `--color=bw` (default)


grayscale mode. dither to `--depth` bits; --depth=1 uses pure black and white, --depth=2 uses black, white, and two shades of gray, etc, etc.

### `color=color`


use RGB channels with specified bit depth. i.e, `--color=color, --depth=2` uses two bits each for the red, green, and blue channels.



### `--color=crayon`


use the crayon color palette. see "crayon.plt" for details.

### `--color=cga`


use the [cga](https://en.wikipedia.org/wiki/Color_Graphics_Adapter) color palette. see the wikipedia article or "cga.plt" for details.

### `--color=$COLOR`


single-color mode. dither in black and white to the specified bit depth, then replace white with the given color, using black for the background.

- BLUE
- GREEN
- CYAN
- RED
- MAGENTA
- BROWN
- LIGHT_GRAY
- GRAY
- LIGHT_BLUE
- LIGHT_GREEN
- LIGHT_CYAN 
- LIGHT_RED
- LIGHT_MAGENTA
- YELLOW
- WHITE

### `--color=$FILENAME`


load a palette from file. palettes are specified as a list of two or more newline-separated 24-bit hexidecimals, with optional 0x prefix. see `crayon.plt` and `cga.plt` for examples.

    // WHITE
    0xffffff
    // BLACK
    0x000000
    // RED
    0xff0000
    // GREEN
    0x00ff00
    // BLUE
    0x0000ff

## `-d, --dither`


The type of ditherer to use. Available options are

- `"floyd"`, `"steinberg"`, `"floydsteinberg"` (default)
- `"atkinson"`,
- `"stucki"`,
- `"burkes"`,
- `"jarvis"`, `"judice"`, `ninke"`
- `"sierra"`, `"sierra3"`

See [the documentation](https://docs.rs/dither/1.3.6/dither/ditherer/index.html) or [Tanner Helland's article](http://www.tannerhelland.com/4660/dithering-eleven-algorithms-source-code) for technical details.

### `-v, --verbose`


Verbose debug output to stderr.

### `--depth`


The bit depth to compress each channel to. Should be an unsigned integer between 1 and 7 (default 1). Mutally exclusive with the `--color= $FILENAME`, `color==cga`, and `--color=crayon` options.