im2ascii

im2ascii converts an input image to ASCII art. Images are converted using the following procedure:

• Load and convert image to grey-scale
• Re-scale the grey-scale image so that the width in pixels is the desired output width in ASCII characters
• Map each pixel in the re-scaled image to the ASCII character with the closest perceptual luminance.

Installation

This code supports installation using pip (via setuptools). To install from the git repository:

git clone https://github.com/asherbender/im2ascii
cd im2ascii
sudo pip install .

Once installed, the command im2ascii is available from the command-line. The script is typically installed in

/usr/local/bin/

To uninstall the package:

pip uninstall im2ascii

Dependencies

The following libraries are used in im2ascii and are managed by pip:

• NumPy
• scikit-image

Usage

To print the ASCII art to standard out:

im2ascii image.png --width 300

To save the ASCII art to a file:

im2ascii image.png > image.txt

Additional functionality is documented in im2ascii --help:

usage: im2ascii [-h] [-w [int]] [-l [int]] [-r [float]] [-b] [--list] [image]

Convert image into ASCII art.

positional arguments:
  image                 Path to image.

optional arguments:
  -h, --help            show this help message and exit
  -w [int], --width [int]
                        Width of ASCII art in characters. The default is 80
                        characters.
  -l [int], --levels [int]
                        By default ASCII art is generated by allocating each
                        pixel to the nearest character based on the
                        characters' perceptual luminance (no binning). If
                        binning is enabled, the characters are arranged into a
                        number of perceptual luminance bins. ASCII art is then
                        generated by assigning each pixel to a luminance bin
                        and drawing a random character from the bin. Levels
                        must be an integer between 5 and 50.
  -r [float], --ratio [float]
                        Height:width ratio per ASCII character. The ratio must
                        be greater than or equal to one (square characters).
                        The default is 2.
  -b, --boarder         Add boarder to ASCII art.
  --list                Print characters with associated perceptual luminance
                        and exit. If binning has been enabled, each luminance
                        level and its associated characters will be printed.
                        The characters are ordered by luminance intensity from
                        least to highest.

License

This code is licensed under the GNU General Public License Version 3 (GPLv3).