Skip to content
Convert images to beautiful ANSI escape codes for display in command line interfaces.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
climage
extra
.gitignore
LICENSE
README.md
setup.py

README.md

CLImage 📷

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

Available as both a CLI application and a Python library.

demo

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

demo

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

$ climage --unicode --truecolour image.png

demo

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

demo

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
You can’t perform that action at this time.