img2ascii

This Command-Line tool converts input images into ASCII art.

It can be configured using flags on the command line, a few options of which are:

• Simple ASCII (using the map .:-=+*#%@")
• Complex ASCII (using the map .'`^",:;Il!i><~+_-?][}{1)(|\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$)
• Braille symbols
• Custom character maps (through the --map flag)
• Output in full colour
• Output in grayscale

Prerequisites

• Rust (building from source only)

Installation

Installing is pretty easy, just grab the appropriate executable from the releases tab, and you're good to go!

Building from source

git clone https://github.com/djairoh/img2ascii
cd ./img-search
cargo build --release
mv ./target/release/
./img2ascii <FILE> [FLAGS]

Running

Running the program is very simple. Simply execute ./img2ascii <IMAGE> and it will convert to ASCII and print to stdout.

Of course the output can be customized, by using one (or more) flags.

options

• -c, --complex: uses the extended character map
• -C, --colour: Display ASCII art in full 24-bit colour
• --background: Colour the background instead of the foreground
• -g, --grayscale: Display ASCII art in grayscale
• -b, --braille: Use braille characters instead of a character map
• -d, --debug: Print debugging information
• -f, --full: use the full width of the terminal, instead of fitting the image to the terminal dimensions
• --threshold: use a custom threshold when converting to braille (range 0-255, default: 128)
• -M, --map: use a custom character map
• -w, --width: force a specific width of the output
• -o, --output: Save the output to a text file, instead of printing to terminal
• -h, --help: Print help information (extended info with '--help')

conflicting flags

The flags --complex, --braille, --map conflict. When two or more of these are entered in the same command, the program uses the one with the highest precedence, in the order braille > complex > map.

The flags --output, --colour and --grayscale also conflict. When both are entered, the flag --output takes precedence (leading to a simple txt file).

The flags --full and --width are mutually exclusive. When both are entered, the flag -full will be applied (full > width).

Lastly, the flags --colour and --grayscale are not mutually applicable. When both are entered, the flag --colour will be applied.

Note also that the --background flag requires either --colour or --grayscale to do anything.

Documentation

The program has been documented with RustDoc, which can be compiled and viewed with cargo doc --open.