ascii-image

Converts images and gifs to ASCII art.

Installation:

You will need to install Rust in order to install this program. After installing Rust, installation is simply:

cargo install image-to-ascii

Usage

Here are some examples of converting between various input and output formats:

image-to-ascii input_image.jpg
image-to-ascii input_image.gif -o output_image.gif
image-to-ascii input_image.jpeg -o output_image.json --width 200
image-to-ascii input_image.gif -o output_image.gif --metric dot --font bitocra-13 --alphabet minimal
image-to-ascii input_image.gif -o output_image.json --metric grad --font fonts/courier.bdf --alphabet alphabets/letters.txt

All image formats readable by image should be supported as inputs and are detected automatically from the input file name.

This program can output gifs or JSON, depending on the provided output file name. If the output format is .json and the input format is an animated gif, you can preview the animated result by opening it with viewer.html. If no output file is provided, the output will be displayed directly in the terminal; note that most terminals are not designed to keep up with the rate that this program outputs text, so the terminal output can be quite choppy.

This program only works with monospace bitmap fonts in .bdf format. If you would like to use a font other than the default, you can find a large collection of free bitmap fonts here.

Arguments

<IMAGE_PATH>

Path to the input image file. If the input file is an image, the output will be a static image. If the input is a .gif, then the output will be animated.

-a, --alphabet [default: alphabet]

Name or path specifying an alphabet to use. The provided font must have a glyph for each character in the provided alphabet. Valid alphabet names are:

• alphabet
• letters
• lowercase
• uppercase
• minimal
• symbols

-b, --brightness-offset <BRIGHTNESS_OFFSET> [default: 128, min: 0, max: 255]

Amount subtracted from each grayscale pixel of the image before computing character similarities. Darker images tend to look better with low brightness offsets, while lighter images tend to look better with high ones.

-f, --font <FONT> [default: courier]

Name or path specifying a font to use. The provided font must be monospace in .bdf format and have a glyph for each character in the provided alphabet. Valid font names are:

• courier
• bitocra-13

--fps [default: 30]

Frames per second for the gif or terminal output. For gif output, the max fps is 30.

-h, --help Print help information

-m, --metric [default: grad]

The metric used to determine which character best matches a particular chunk of an image. Valid values are:

• grad: how similar the gradient and intensity of the pixel values are to those of the bitmap values for a character
• fast: how close the brightness of the pixel values is to the brightness of the character bitmap
• dot: dot product between pixel values and character bitmap values
• jaccard: weighted jaccard index between pixel values and character bitmap values
• occlusion: how much the pixel values are "occluded" by the character bitmap, or vice versa
• clear: how much the font "clears" from the pixel when subtracted from it

-n, --noise-scale <NOISE_SCALE> [default: 0]

Adds noise to the value of the metric for each character. Can either be used to diversify characters in output by "breaking ties" or add a glitch effect, depending on the amount of noise used.

-o, --out-path <OUT_PATH>

Path to write the output to. If no value is provided, output will be displayed in the console. Supports outputting to .json or .gif. Any gif viewer can display .gif output, and viewer.html can be used to display .json gif output.

-t, --threads [default: 1]

Number of threads to use when converting pixel chunks to characters. Higher values can reduce conversion time.

-w, --width [default: 150]

The width in characters of the final output. Will preserve the aspect ratio as much as possible while having the output width and height be a multiple of the font width and height.