# Dither 1.3.10

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.10/dither/)
* [repository](https://gitlab.com/efronlicht/dither)
* [binaries](https://gitlab.com/efronlicht/dither-binaries)
* [dockerfile](https://hub.docker.com/r/efronlicht/dither)

## License: MIT

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

## Installation

* ### Compilation from source

    - Install rust  by following the instructions at [rustup.rs](https://rustup.rs/)/
    - Install dither

            cargo install dither

* ### Download a binary (x64-windows, x64-linux)

    - Download a binary from the [binaries repository](https://gitlab.com/efronlicht/dither-binaries)

* ### Run directly via Docker

        docker run efronlicht/dither:latest

## 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.5/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.