Chafa: Terminal Graphics for the 21st Century

chafa /ˈtʃafa/ (adj): cheap, low quality; lame

Here's a gallery of pictures showing what can be achieved with some of Chafa's numerous command-line options. Enjoy!

Color modes (-c)

Input image — Original © Giacomo Callaioli, CC BY-NC 2.0

Terminal graphics with 24-bit color — -c full

Terminal graphics with 240 colors — -c 240

Terminal graphics with 16 colors — -c 16

Terminal graphics with default and inverse color — -c 2

Terminal graphics with no color codes — -c none

This option controls what kind of palette to use, and indirectly, which ANSI color codes to emit. "Full" is an alias for 24-bit color, which is only supported by the most modern terminal emulators. "240" uses a fixed 240-color palette that is a bit more common. "16" uses control codes popularized by AIXterm and should work with most terminal emulators and some older terminals. "2" relies on the terminal's default foreground and background colors only, with control codes to invert the colors. "none" allows no color control codes whatsoever.

Do take note of the appropriate use of thin line characters, especially diagonals, in this example!

Color spaces (--color-space)

Terminal graphics with 240 RGB colors — -c 240 --color-space rgb

Terminal graphics with 240 DIN99d colors — -c 240 --color-space din99d

Terminal graphics with 16 RGB colors — -c 16 --color-space rgb

Terminal graphics with 16 DIN99d colors — -c 16 --color-space din99d

The color space is relevant to color modes with restricted palettes (which is every mode except for the "full" 24-bit mode). It governs how the approximate colors are picked. DIN99d yields a more accurate color representation. However, the conversions involved are costly, so RGB is the default.

Dithering (--dither)

Terminal graphics, undithered — -c 240 --dither none

Terminal graphics with ordered dithering — -c 240 --dither bayer

Terminal graphics with error diffusion dihering — -c 240 --dither fs

Images can be dithered to produce perceptually smoother gradients. Two strategies are supported: "ordered" aka "bayer", which applies a uniform intensity-modulating pattern, and "diffusion" aka "fs" (Floyd-Steinberg), which calculates the color deviance at each pixel and compensates by spreading a correction factor to its neighbors.

Dithering grain shape (--dither-grain)

Terminal graphics dithered with 4x4 grain — -c 240 --dither bayer --dither-grain 4

Terminal graphics dithered with 8x4 grain — -c 240 --dither bayer --dither-grain 8x4

Terminal graphics dithered with 8x8 grain — -c 240 --dither bayer --dither-grain 8

Dithering works on rectangles that can be bigger than a single pixel. This enables you to align the dithered grid with the virtual resolution of the output symbols. Chafa's character cells correspond to 8x8 pixel rectangles. 4x4 grains will thus correspond to "quad" block symbols, 8x4 grains will match up with "vhalf" symbols, and 8x8 grains will modulate entire character cells.

Dithering intensity (--dither-intensity)

Terminal graphics with 0.5 intensity ordered dithering — -c 240 --dither bayer --dither-intensity 0.5

Terminal graphics with 1.0 intensity ordered dithering — -c 240 --dither bayer --dither-intensity 1.0

Terminal graphics with 2.0 intensity ordered dithering — -c 240 --dither bayer --dither-intensity 2.0

Terminal graphics with 1.0 intensity Floyd-Steinberg dithering — -c 240 --dither fs --dither-intensity 1.0

Terminal graphics with 2.0 intensity Floyd-Steinberg dithering — -c 240 --dither fs --dither-intensity 2.0

When enabled, dithering can be made more or less aggressive with this factor. 1.0 is neutral.

Fill symbols (--fill)

Terminal graphics with no fill — -c 16 --fill none

Terminal graphics with ASCII fill — -c 16 --fill ascii

Terminal graphics with Braille fill — -c 16 --fill braille

Some images will produce a lot of flat space with no symbols in it. This option allows you to fill these spaces with symbols that modulate the perceptual color. It can also be used together with --symbols none to create a very old-school look. It supports the same symbol classes as --symbols does.

Preprocessing (-p)

Terminal graphics, preprocessed — -c 16 -p on

Terminal graphics, no preprocessing — -c 16 -p off

This option automatically boosts contrast and saturation in reduced-color modes. This makes most images more legible and can improve color accuracy. It's on by default, but if you are doing your own preprocessing or want to use a different approach (e.g. with a different color space or dithering), you can turn it off with -p off.

Work factor (-w)

The work factor is a measure of how much CPU time and memory to spend refining the output. The factor ranges from 1 to 9. Lower values are fast, but produce rougher output, while the highest values are slower but more precise. The default factor is 5.

Some images are more affected than others. In the above example, the difference is most noticeable along the plant's stalks and other high-contrast edges.