img2txt: Convert Images to Color ASCII Text

img2txt: Convert Images to Color ASCII Text

A practical tool to turn images into color ASCII art and print it as text. It supports ANSI color output, so you can save or share art in plain text files.

Quick start (bare minimum)

  • Basic usage:
img2txt path/to/image.png
  • Save output to a file (text with ANSI colors):
img2txt path/to/image.png > output.txt
  • Resize the output by width or height:
# Set a fixed width (columns)
img2txt --width={{80}} path/to/image.png

# Set a fixed height (lines)
img2txt --height={{20}} path/to/image.png

Common options (examples)

  • Set output column count to a specific value:
img2txt --width={{10}} path/to/image.png
  • Set output line count to a specific value:
img2txt --height={{5}} path/to/image.png
  • Set output font width to a specific value:
img2txt --font-width={{12}} path/to/image.png
  • Set output font height to a specific value:
img2txt --font-height={{14}} path/to/image.png
  • Adjust brightness to influence contrast of the ASCII result:
img2txt --brightness={{2}} path/to/image.png

Tip: The —width and —height values control the resulting ASCII art size, not the input image size. If you pick too small dimensions, details may be lost quickly.

Practical tips

  • Image quality matters: high-contrast images yield clearer ASCII art.
  • Colors are emitted as ANSI escape codes. Ensure your terminal supports 24-bit or the color depth your terminal provides.
  • If the output looks garbled, try redirecting to a file and view with a pager:
img2txt path/to/image.png | less -R
  • Use sane defaults: start with a moderate width (e.g., 80–100) and adjust as needed.

Common pitfalls

  • Terminal color support varies: some terminals can’t render certain ANSI color sequences. If colors look wrong, try escaping color output or using a monochrome option if available.
  • Large images can produce very long text outputs. Use —width/—height to cap the size, or resize the image beforehand.
  • If the tool reports file not found or permission errors, verify the path and permissions of the image file.

Advanced notes

  • Combine with other tools: convert a set of images in a folder and log results:
for f in images/*.{png,jpg}; do
  img2txt "$f" > "${f%.*}.txt"
done
  • If you need to embed ASCII art in terminals that don’t support color, you can still use img2txt with default color off (check man page for a non-color option, if available).

Reference

See Also