CLImage 📷

Convert images to beautiful ANSI escape codes for display in command line interfaces.

Available as both a CLI application and a Python library.

Features

• Custom sized images
• ASCII or Unicode support
  • Unicode enables 4x more detail
• 8/16/256/Truecolor support, for a wider gamut of colors
• Selectable system palettes to adjust for user terminal themes
• Fast color lookup with KDTrees & memoization

Usage

CLImage is available as both a standalone CLI program, or available for import as a Python3 library.

CLI Program

By default converting an image will output in 256 color, as 80 columns, and ASCII (for reasonable compatibility).

$ climage image.png

A nicer image can be obtained when enabling unicode and truecolor flags.

$ climage --unicode --truecolour image.png

For display in TTYs such as the Linux terminal before starting X11 (also accessible by Ctrl-Alt-F3, etc), you should restrict yourself to 8 color, and ASCII only. As 8 and 16 colors are solely constructed out of system colors (often set by the terminal theme), it is recommended to select a palette for these, depending on what you have selected.

$ climage --8color warhol.png --palette solarized

Further options may be found by running climage --help

Python Library

It is recommended that you use the Python library if converting a large number of images. Usage of the library mirrors that of the CLI tool.

import climage

output = climage.convert('image.png', is_unicode=True)
print(output)

Two functions are exposed in the Python library convert, and to_file:

convert(filename, is_unicode=False, is_truecolor=False, is_256color=True, is_16color=False, is_8color=False, width=80, palette="default")

This will read in the file given by filename, and return the output.

to_file(infile, outfile, is_unicode=False, is_truecolor=False, is_256color=True, is_16color=False, is_8color=False, width=80, palette="default"):

This is will in the file given by filename, and write the output to outfile.

Future:

• [ ] write docstrings
• [ ] investigate different scaling modes? 256 color sometimes looks better for colors (than truecolor)?
• [ ] rename the _toAnsi fn, as it's not really right (ANSI is restricted to the 16 color stuff, right?)
• [ ] add a detect option to --palette, to automatically detect mapping of system colors? this might be hard.
• [ ] run the fabled pylint on the codebase
• [ ] Python library section link in setup.py, and in this README
• [ ] Add option to select