A Python CLI tool to convert PNG images to ASCII art with multiple dithering algorithms including Floyd-Steinberg, Atkinson, and Bayer ordered dithering.

• Multiple Dithering Algorithms

  • Floyd-Steinberg - Error diffusion dithering, best for photographs
  • Atkinson - Classic Macintosh-style dithering with lighter appearance
  • Ordered (Bayer) - Matrix-based dithering with stylized halftone look
  • None - Simple brightness-to-character mapping

• Customizable Output

  • Adjustable output width
  • Multiple character sets (detailed, simple, blocks)
  • Custom character sets support
  • Brightness inversion for dark/light terminals

• Easy to Use

  • Simple CLI interface
  • Save output to file or print to terminal

pip install Pillow numpy

python png_to_ascii.py image.png

# Floyd-Steinberg dithering (best for photos)
python png_to_ascii.py image.png -d floyd-steinberg

# Atkinson dithering (classic Mac style)
python png_to_ascii.py image.png -d atkinson

# Ordered/Bayer dithering (halftone effect)
python png_to_ascii.py image.png -d ordered

python png_to_ascii.py image.png -w 80

python png_to_ascii.py image.png --invert

python png_to_ascii.py image.png -o output.txt

# Detailed characters
python png_to_ascii.py image.png --charset detailed

# Simple characters
python png_to_ascii.py image.png --charset simple

# Unicode block characters
python png_to_ascii.py image.png --charset blocks

# Custom characters (darkest to lightest)
python png_to_ascii.py image.png -c "@#%*+=-:. "

Error diffusion algorithm that distributes quantization error to neighboring pixels. Produces smooth gradients and is ideal for photographs.

     *   7/16
3/16 5/16 1/16

Used in early Macintosh computers. Only distributes 3/4 of the error, creating a lighter, more artistic appearance.

     *  1/8 1/8
1/8 1/8 1/8
    1/8

Uses a threshold matrix to create regular dithering patterns. Produces a stylized halftone look reminiscent of print media.

Simple (no dithering):

............::::::.....
...........:+%@@@@%+....
..........:%@@@@@@@@@-..
..........#@@****#****..

Floyd-Steinberg:

@*@*@@*@*@@*@*@@*@*@@*@*
*@@*@*@@@@*@@*@@@@*@@*@@
@@*@@*@*@*@@*@*@@*@*@@*@
@*@@@*@@@@*@@@@*@@@@*@@@

• Python 3.8+
• Pillow
• NumPy

MIT License

• Dithering - Part 1
• Floyd-Steinberg Dithering
• Ordered Dithering
• Atkinson Dithering